projects / pub / USBasp.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
Minor documentation corrections.
[pub/USBasp.git] / LUFA / Drivers / USB / Class / Host / StillImage.h
diff --git a/LUFA/Drivers/USB/Class/Host/StillImage.h b/LUFA/Drivers/USB/Class/Host/StillImage.h
index d2e6fe0..2c5c6b1 100644 (file)
--- a/LUFA/Drivers/USB/Class/Host/StillImage.h
+++ b/LUFA/Drivers/USB/Class/Host/StillImage.h
@@ -1,13 +1,13 @@
 /*
              LUFA Library
 /*
              LUFA Library
-     Copyright (C) Dean Camera, 2010.
+     Copyright (C) Dean Camera, 2011.
 
   dean [at] fourwalledcubicle [dot] com
 
   dean [at] fourwalledcubicle [dot] com
-      www.fourwalledcubicle.com
+           www.lufa-lib.org
 */
 
 /*
 */
 
 /*
-  Copyright 2010  Dean Camera (dean [at] fourwalledcubicle [dot] com)
+  Copyright 2011  Dean Camera (dean [at] fourwalledcubicle [dot] com)
 
   Permission to use, copy, modify, distribute, and sell this
   software and its documentation for any purpose is hereby granted
 
   Permission to use, copy, modify, distribute, and sell this
   software and its documentation for any purpose is hereby granted
@@ -33,18 +33,18 @@
  *
  *  Host mode driver for the library USB Still Image Class driver.
  *
  *
  *  Host mode driver for the library USB Still Image Class driver.
  *
- *  \note This file should not be included directly. It is automatically included as needed by the class driver
- *        dispatch header located in LUFA/Drivers/USB/Class/StillImage.h.
+ *  \note This file should not be included directly. It is automatically included as needed by the USB module driver
+ *        dispatch header located in LUFA/Drivers/USB.h.
  */
 
 /** \ingroup Group_USBClassSI
  */
 
 /** \ingroup Group_USBClassSI
- *  @defgroup Group_USBClassStillImageHost Still Image Class Host Mode Driver
+ *  \defgroup Group_USBClassStillImageHost Still Image Class Host Mode Driver
  *
  *  \section Sec_Dependencies Module Source Dependencies
  *  The following files must be built with any user project that uses this module:
  *    - LUFA/Drivers/USB/Class/Host/StillImage.c <i>(Makefile source module name: LUFA_SRC_USBCLASS)</i>
  *
  *
  *  \section Sec_Dependencies Module Source Dependencies
  *  The following files must be built with any user project that uses this module:
  *    - LUFA/Drivers/USB/Class/Host/StillImage.c <i>(Makefile source module name: LUFA_SRC_USBCLASS)</i>
  *
- *  \section Module Description
+ *  \section Sec_ModDescription Module Description
  *  Host Mode USB Class driver framework interface, for the Still Image USB Class driver.
  *
  *  @{
  *  Host Mode USB Class driver framework interface, for the Still Image USB Class driver.
  *
  *  @{
@@ -64,7 +64,7 @@
 
        /* Preprocessor Checks: */
                #if !defined(__INCLUDE_FROM_SI_DRIVER)
 
        /* Preprocessor Checks: */
                #if !defined(__INCLUDE_FROM_SI_DRIVER)
-                       #error Do not include this file directly. Include LUFA/Drivers/Class/StillImage.h instead.
+                       #error Do not include this file directly. Include LUFA/Drivers/USB.h instead.
                #endif
 
        /* Public Interface - May be used in end-application: */
                #endif
 
        /* Public Interface - May be used in end-application: */
@@ -76,7 +76,7 @@
                        /** \brief Still Image Class Host Mode Configuration and State Structure.
                         *
                         *  Class state structure. An instance of this structure should be made within the user application,
                        /** \brief Still Image Class Host Mode Configuration and State Structure.
                         *
                         *  Class state structure. An instance of this structure should be made within the user application,
-                        *  and passed to each of the Still Image class driver functions as the SIInterfaceInfo parameter. This
+                        *  and passed to each of the Still Image class driver functions as the \c SIInterfaceInfo parameter. This
                         *  stores each Still Image interface's configuration and state information.
                         */
                        typedef struct
                         *  stores each Still Image interface's configuration and state information.
                         */
                        typedef struct
@@ -100,7 +100,7 @@
                                                            *   after \ref SI_Host_ConfigurePipes() is called and the Host state machine is in the
                                                            *   Configured state.
                                                            */
                                                            *   after \ref SI_Host_ConfigurePipes() is called and the Host state machine is in the
                                                            *   Configured state.
                                                            */
-                                       uint8_t  InterfaceNumber; /**< Interface index of the Mass Storage interface within the attached device. */
+                                       uint8_t  InterfaceNumber; /**< Interface index of the Still Image interface within the attached device. */
 
                                        uint16_t DataINPipeSize; /**< Size in bytes of the Still Image interface's IN data pipe. */
                                        uint16_t DataOUTPipeSize;  /**< Size in bytes of the Still Image interface's OUT data pipe. */
 
                                        uint16_t DataINPipeSize; /**< Size in bytes of the Still Image interface's IN data pipe. */
                                        uint16_t DataOUTPipeSize;  /**< Size in bytes of the Still Image interface's OUT data pipe. */
@@ -123,6 +123,7 @@
                                SI_ENUMERROR_NoCompatibleInterfaceFound = 2, /**< A compatible Still Image interface was not found in the device's
                                                                              *   Configuration Descriptor.
                                                                              */
                                SI_ENUMERROR_NoCompatibleInterfaceFound = 2, /**< A compatible Still Image interface was not found in the device's
                                                                              *   Configuration Descriptor.
                                                                              */
+                               SI_ENUMERROR_PipeConfigurationFailed    = 3, /**< One or more pipes for the specified interface could not be configured correctly. */
                        };
 
                /* Function Prototypes: */
                        };
 
                /* Function Prototypes: */
@@ -132,10 +133,6 @@
                         *  found within the device. This should be called once after the stack has enumerated the attached device, while
                         *  the host state machine is in the Addressed state.
                         *
                         *  found within the device. This should be called once after the stack has enumerated the attached device, while
                         *  the host state machine is in the Addressed state.
                         *
-                        *  \note The pipe index numbers as given in the interface's configuration structure must not overlap with any other
-                        *        interface, or pipe bank corruption will occur. Gaps in the allocated pipe numbers or non-sequential indexes
-                        *        within a single interface is allowed, but no two interfaces of any type have have interleaved pipe indexes.
-                        *
                         *  \param[in,out] SIInterfaceInfo       Pointer to a structure containing a Still Image Class host configuration and state.
                         *  \param[in]     ConfigDescriptorSize  Length of the attached device's Configuration Descriptor.
                         *  \param[in]     ConfigDescriptorData  Pointer to a buffer containing the attached device's Configuration Descriptor.
                         *  \param[in,out] SIInterfaceInfo       Pointer to a structure containing a Still Image Class host configuration and state.
                         *  \param[in]     ConfigDescriptorSize  Length of the attached device's Configuration Descriptor.
                         *  \param[in]     ConfigDescriptorData  Pointer to a buffer containing the attached device's Configuration Descriptor.
@@ -184,10 +181,10 @@
                         *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
                         */
                        uint8_t SI_Host_SendBlockHeader(USB_ClassInfo_SI_Host_t* const SIInterfaceInfo,
                         *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
                         */
                        uint8_t SI_Host_SendBlockHeader(USB_ClassInfo_SI_Host_t* const SIInterfaceInfo,
-                                                       SI_PIMA_Container_t* const PIMAHeader) ATTR_NON_NULL_PTR_ARG(1)
+                                                       PIMA_Container_t* const PIMAHeader) ATTR_NON_NULL_PTR_ARG(1)
                                                        ATTR_NON_NULL_PTR_ARG(2);
 
                                                        ATTR_NON_NULL_PTR_ARG(2);
 
-                       /** Receives a raw PIMA block header to the device. This can be used to receive arbitrary PIMA blocks from the device with
+                       /** Receives a raw PIMA block header from the device. This can be used to receive arbitrary PIMA blocks from the device with
                         *  or without parameters.
                         *
                         *  \pre This function must only be called when the Host state machine is in the \ref HOST_STATE_Configured state or the
                         *  or without parameters.
                         *
                         *  \pre This function must only be called when the Host state machine is in the \ref HOST_STATE_Configured state or the
@@ -199,7 +196,7 @@
                         *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
                         */
                        uint8_t SI_Host_ReceiveBlockHeader(USB_ClassInfo_SI_Host_t* const SIInterfaceInfo,
                         *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
                         */
                        uint8_t SI_Host_ReceiveBlockHeader(USB_ClassInfo_SI_Host_t* const SIInterfaceInfo,
-                                                          SI_PIMA_Container_t* const PIMAHeader) ATTR_NON_NULL_PTR_ARG(1)
+                                                          PIMA_Container_t* const PIMAHeader) ATTR_NON_NULL_PTR_ARG(1)
                                                           ATTR_NON_NULL_PTR_ARG(2);
 
                        /** Sends a given PIMA command to the attached device, filling out the PIMA command header's Transaction ID automatically.
                                                           ATTR_NON_NULL_PTR_ARG(2);
 
                        /** Sends a given PIMA command to the attached device, filling out the PIMA command header's Transaction ID automatically.
@@ -220,7 +217,7 @@
                                                    const uint8_t TotalParams,
                                                    uint32_t* const Params) ATTR_NON_NULL_PTR_ARG(1);
 
                                                    const uint8_t TotalParams,
                                                    uint32_t* const Params) ATTR_NON_NULL_PTR_ARG(1);
 
-                       /** Receives and checks a response block from the attached PIMA device, once a command has been issued and all data
+                       /** Receives and checks a response block from the attached Still Image device, once a command has been issued and all data
                         *  associated with the command has been transferred.
                         *
                         *  \pre This function must only be called when the Host state machine is in the \ref HOST_STATE_Configured state or the
                         *  associated with the command has been transferred.
                         *
                         *  \pre This function must only be called when the Host state machine is in the \ref HOST_STATE_Configured state or the
@@ -240,7 +237,7 @@
                         *
                         *  \param[in,out] SIInterfaceInfo  Pointer to a structure containing a Still Image Class host configuration and state.
                         *
                         *
                         *  \param[in,out] SIInterfaceInfo  Pointer to a structure containing a Still Image Class host configuration and state.
                         *
-                        *  \return Boolean true if an event is waiting to be read, false otherwise.
+                        *  \return Boolean \c true if an event is waiting to be read, \c false otherwise.
                         */
                        bool SI_Host_IsEventReceived(USB_ClassInfo_SI_Host_t* const SIInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
 
                         */
                        bool SI_Host_IsEventReceived(USB_ClassInfo_SI_Host_t* const SIInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
 
@@ -256,7 +253,7 @@
                         *          returned a logical command failure.
                         */
                        uint8_t SI_Host_ReceiveEventHeader(USB_ClassInfo_SI_Host_t* const SIInterfaceInfo,
                         *          returned a logical command failure.
                         */
                        uint8_t SI_Host_ReceiveEventHeader(USB_ClassInfo_SI_Host_t* const SIInterfaceInfo,
-                                                          SI_PIMA_Container_t* const PIMAHeader) ATTR_NON_NULL_PTR_ARG(1)
+                                                          PIMA_Container_t* const PIMAHeader) ATTR_NON_NULL_PTR_ARG(1)
                                                           ATTR_NON_NULL_PTR_ARG(2);
 
                        /** Sends arbitrary data to the attached device, for use in the data phase of PIMA commands which require data
                                                           ATTR_NON_NULL_PTR_ARG(2);
 
                        /** Sends arbitrary data to the attached device, for use in the data phase of PIMA commands which require data
@@ -298,7 +295,7 @@
                         *
                         *  \param[in,out] SIInterfaceInfo  Pointer to a structure containing a Still Image Class host configuration and state.
                         */
                         *
                         *  \param[in,out] SIInterfaceInfo  Pointer to a structure containing a Still Image Class host configuration and state.
                         */
-                       static inline void SI_Host_USBTask(USB_ClassInfo_SI_Host_t* const SIInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
+                       static inline void SI_Host_USBTask(USB_ClassInfo_SI_Host_t* const SIInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
                        static inline void SI_Host_USBTask(USB_ClassInfo_SI_Host_t* const SIInterfaceInfo)
                        {
                                (void)SIInterfaceInfo;
                        static inline void SI_Host_USBTask(USB_ClassInfo_SI_Host_t* const SIInterfaceInfo)
                        {
                                (void)SIInterfaceInfo;
@@ -307,16 +304,14 @@
        /* Private Interface - For use in library only: */
        #if !defined(__DOXYGEN__)
                /* Macros: */
        /* Private Interface - For use in library only: */
        #if !defined(__DOXYGEN__)
                /* Macros: */
-                       #define STILL_IMAGE_CLASS              0x06
-                       #define STILL_IMAGE_SUBCLASS           0x01
-                       #define STILL_IMAGE_PROTOCOL           0x01
-
-                       #define COMMAND_DATA_TIMEOUT_MS        10000
+                       #define SI_COMMAND_DATA_TIMEOUT_MS        10000
 
                /* Function Prototypes: */
 
                /* Function Prototypes: */
-                       #if defined(__INCLUDE_FROM_SI_CLASS_HOST_C)
-                               static uint8_t DCOMP_SI_Host_NextSIInterface(void* const CurrentDescriptor) ATTR_NON_NULL_PTR_ARG(1);
-                               static uint8_t DCOMP_SI_Host_NextSIInterfaceEndpoint(void* const CurrentDescriptor) ATTR_NON_NULL_PTR_ARG(1);
+                       #if defined(__INCLUDE_FROM_STILLIMAGE_HOST_C)
+                               static uint8_t DCOMP_SI_Host_NextSIInterface(void* const CurrentDescriptor)
+                                                                            ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1);
+                               static uint8_t DCOMP_SI_Host_NextSIInterfaceEndpoint(void* const CurrentDescriptor)
+                                                                                    ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1);
                        #endif
        #endif
 
                        #endif
        #endif
 
USB isp AVR programmer