git.sur5r.net Git - freertos/blob

   1 /*\r
   2  * @brief Host mode driver for the library USB Still Image Class driver\r
   3  *\r
   4  * @note\r
   5  * Copyright(C) NXP Semiconductors, 2012\r
   6  * Copyright(C) Dean Camera, 2011, 2012\r
   7  * All rights reserved.\r
   8  *\r
   9  * @par\r
  10  * Software that is described herein is for illustrative purposes only\r
  11  * which provides customers with programming information regarding the\r
  12  * LPC products.  This software is supplied "AS IS" without any warranties of\r
  13  * any kind, and NXP Semiconductors and its licensor disclaim any and\r
  14  * all warranties, express or implied, including all implied warranties of\r
  15  * merchantability, fitness for a particular purpose and non-infringement of\r
  16  * intellectual property rights.  NXP Semiconductors assumes no responsibility\r
  17  * or liability for the use of the software, conveys no license or rights under any\r
  18  * patent, copyright, mask work right, or any other intellectual property rights in\r
  19  * or to any products. NXP Semiconductors reserves the right to make changes\r
  20  * in the software without notification. NXP Semiconductors also makes no\r
  21  * representation or warranty that such application will be suitable for the\r
  22  * specified use without further testing or modification.\r
  23  *\r
  24  * @par\r
  25  * Permission to use, copy, modify, and distribute this software and its\r
  26  * documentation is hereby granted, under NXP Semiconductors' and its\r
  27  * licensor's relevant copyrights in the software, without fee, provided that it\r
  28  * is used in conjunction with NXP Semiconductors microcontrollers.  This\r
  29  * copyright, permission, and disclaimer notice must appear in all copies of\r
  30  * this code.\r
  31  */\r
  32 \r
  33 /** @ingroup Group_USBClassSI\r
  34  *  @defgroup Group_USBClassStillImageHost Still Image Class Host Mode Driver\r
  35  *\r
  36  *  @section Sec_Dependencies Module Source Dependencies\r
  37  *  The following files must be built with any user project that uses this module:\r
  38  *    - LPCUSBlib/Drivers/USB/Class/Host/StillImage.c <i>(Makefile source module name: LPCUSBlib_SRC_USBCLASS)</i>\r
  39  *\r
  40  *  @section Sec_ModDescription Module Description\r
  41  *  Host Mode USB Class driver framework interface, for the Still Image USB Class driver.\r
  42  *\r
  43  *  @{\r
  44  */\r
  45 \r
  46 #ifndef __SI_CLASS_HOST_H__\r
  47 #define __SI_CLASS_HOST_H__\r
  48 \r
  49         /* Includes: */\r
  50                 #include "../../USB.h"\r
  51                 #include "../Common/StillImageClassCommon.h"\r
  52 \r
  53         /* Enable C linkage for C++ Compilers: */\r
  54                 #if defined(__cplusplus)\r
  55                         extern "C" {\r
  56                 #endif\r
  57 \r
  58         /* Preprocessor Checks: */\r
  59                 #if !defined(__INCLUDE_FROM_SI_DRIVER)\r
  60                         #error Do not include this file directly. Include LPCUSBlib/Drivers/USB.h instead.\r
  61                 #endif\r
  62 \r
  63         /* Public Interface - May be used in end-application: */\r
  64                 /* Macros: */\r
  65                         /** Error code for some Still Image Host functions, indicating a logical (and not hardware) error. */\r
  66                         #define SI_ERROR_LOGICAL_CMD_FAILED              0x80\r
  67 \r
  68                 /* Type Defines: */\r
  69                         /** @brief Still Image Class Host Mode Configuration and State Structure.\r
  70                          *\r
  71                          *  Class state structure. An instance of this structure should be made within the user application,\r
  72                          *  and passed to each of the Still Image class driver functions as the \c SIInterfaceInfo parameter. This\r
  73                          *  stores each Still Image interface's configuration and state information.\r
  74                          */\r
  75                         typedef struct\r
  76                         {\r
  77                                 const struct\r
  78                                 {\r
  79                                         uint8_t  DataINPipeNumber; /**< Pipe number of the Still Image interface's IN data pipe. */\r
  80                                         bool     DataINPipeDoubleBank; /**< Indicates if the Still Image interface's IN data pipe should use double banking. */\r
  81 \r
  82                                         uint8_t  DataOUTPipeNumber; /**< Pipe number of the Still Image interface's OUT data pipe. */\r
  83                                         bool     DataOUTPipeDoubleBank; /**< Indicates if the Still Image interface's OUT data pipe should use double banking. */\r
  84 \r
  85                                         uint8_t  EventsPipeNumber; /**< Pipe number of the Still Image interface's IN events endpoint, if used. */\r
  86                                         bool     EventsPipeDoubleBank; /**< Indicates if the Still Image interface's events data pipe should use double banking. */\r
  87                                         uint8_t  PortNumber;            /**< Port number that this interface is running.\r
  88                                                                                                 */\r
  89                                 } Config; /**< Config data for the USB class interface within the device. All elements in this section\r
  90                                            *   <b>must</b> be set or the interface will fail to enumerate and operate correctly.\r
  91                                            */\r
  92                                 struct\r
  93                                 {\r
  94                                         bool     IsActive; /**< Indicates if the current interface instance is connected to an attached device, valid\r
  95                                                             *   after @ref SI_Host_ConfigurePipes() is called and the Host state machine is in the\r
  96                                                             *   Configured state.\r
  97                                                             */\r
  98                                         uint8_t  InterfaceNumber; /**< Interface index of the Still Image interface within the attached device. */\r
  99 \r
 100                                         uint16_t DataINPipeSize; /**< Size in bytes of the Still Image interface's IN data pipe. */\r
 101                                         uint16_t DataOUTPipeSize;  /**< Size in bytes of the Still Image interface's OUT data pipe. */\r
 102                                         uint16_t EventsPipeSize;  /**< Size in bytes of the Still Image interface's IN events pipe. */\r
 103 \r
 104                                         bool IsSessionOpen; /**< Indicates if a PIMA session is currently open with the attached device. */\r
 105                                         uint32_t TransactionID; /**< Transaction ID for the next transaction to send to the device. */\r
 106                                 } State; /**< State data for the USB class interface within the device. All elements in this section\r
 107                                                   *   <b>may</b> be set to initial values, but may also be ignored to default to sane values when\r
 108                                                   *   the interface is enumerated.\r
 109                                                   */\r
 110                         } USB_ClassInfo_SI_Host_t;\r
 111 \r
 112                 /* Enums: */\r
 113                         /** Enum for the possible error codes returned by the @ref SI_Host_ConfigurePipes() function. */\r
 114                         enum SI_Host_EnumerationFailure_ErrorCodes_t\r
 115                         {\r
 116                                 SI_ENUMERROR_NoError                    = 0, /**< Configuration Descriptor was processed successfully. */\r
 117                                 SI_ENUMERROR_InvalidConfigDescriptor    = 1, /**< The device returned an invalid Configuration Descriptor. */\r
 118                                 SI_ENUMERROR_NoCompatibleInterfaceFound = 2, /**< A compatible Still Image interface was not found in the device's\r
 119                                                                               *   Configuration Descriptor.\r
 120                                                                               */\r
 121                                 SI_ENUMERROR_PipeConfigurationFailed    = 3, /**< One or more pipes for the specified interface could not be configured correctly. */\r
 122                         };\r
 123 \r
 124                 /* Function Prototypes: */\r
 125                         /** @brief Host interface configuration routine, to configure a given Still Image host interface instance using the\r
 126                          *  Configuration Descriptor read from an attached USB device. This function automatically updates the given Still\r
 127                          *  Image Host instance's state values and configures the pipes required to communicate with the interface if it is\r
 128                          *  found within the device. This should be called once after the stack has enumerated the attached device, while\r
 129                          *  the host state machine is in the Addressed state.\r
 130                          *\r
 131                          *  @param SIInterfaceInfo      : Pointer to a structure containing a Still Image Class host configuration and state.\r
 132                          *  @param ConfigDescriptorSize : Length of the attached device's Configuration Descriptor.\r
 133                          *  @param ConfigDescriptorData : Pointer to a buffer containing the attached device's Configuration Descriptor.\r
 134                          *\r
 135                          *  @return A value from the @ref SI_Host_EnumerationFailure_ErrorCodes_t enum.\r
 136                          */\r
 137                         uint8_t SI_Host_ConfigurePipes(USB_ClassInfo_SI_Host_t* const SIInterfaceInfo,\r
 138                                                        uint16_t ConfigDescriptorSize,\r
 139                                                        void* ConfigDescriptorData) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3);\r
 140 \r
 141                         /** @brief Opens a new PIMA session with the attached device. This should be used before any session-orientated PIMA commands\r
 142                          *  are issued to the device. Only one session can be open at the one time.\r
 143                          *\r
 144                          *  @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the\r
 145                          *       call will fail.\r
 146                          *\r
 147                          *  @param SIInterfaceInfo : Pointer to a structure containing a Still Image Class host configuration and state.\r
 148                          *\r
 149                          *  @return A value from the @ref Pipe_Stream_RW_ErrorCodes_t enum, or @ref SI_ERROR_LOGICAL_CMD_FAILED if the device\r
 150                          *          returned a logical command failure.\r
 151                          */\r
 152                         uint8_t SI_Host_OpenSession(USB_ClassInfo_SI_Host_t* const SIInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);\r
 153 \r
 154                         /** @brief Closes an already opened PIMA session with the attached device. This should be used after all session-orientated\r
 155                          *  PIMA commands have been issued to the device.\r
 156                          *\r
 157                          *  @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the\r
 158                          *       call will fail.\r
 159                          *\r
 160                          *  @param SIInterfaceInfo : Pointer to a structure containing a Still Image Class host configuration and state.\r
 161                          *\r
 162                          *  @return A value from the @ref Pipe_Stream_RW_ErrorCodes_t enum, or @ref SI_ERROR_LOGICAL_CMD_FAILED if the device\r
 163                          *          returned a logical command failure.\r
 164                          */\r
 165                         uint8_t SI_Host_CloseSession(USB_ClassInfo_SI_Host_t* const SIInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);\r
 166 \r
 167                         /** @brief Sends a raw PIMA block header to the device, filling out the transaction ID automatically. This can be used to send\r
 168                          *  arbitrary PIMA blocks to the device with or without parameters.\r
 169                          *\r
 170                          *  @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the\r
 171                          *       call will fail.\r
 172                          *\r
 173                          *  @param SIInterfaceInfo : Pointer to a structure containing a Still Image Class host configuration and state.\r
 174                          *  @param PIMAHeader      : Pointer to a PIMA container structure that is to be sent.\r
 175                          *\r
 176                          *  @return A value from the @ref Pipe_Stream_RW_ErrorCodes_t enum.\r
 177                          */\r
 178                         uint8_t SI_Host_SendBlockHeader(USB_ClassInfo_SI_Host_t* const SIInterfaceInfo,\r
 179                                                         PIMA_Container_t* const PIMAHeader) ATTR_NON_NULL_PTR_ARG(1)\r
 180                                                         ATTR_NON_NULL_PTR_ARG(2);\r
 181 \r
 182                         /** @brief Receives a raw PIMA block header from the device. This can be used to receive arbitrary PIMA blocks from the device with\r
 183                          *  or without parameters.\r
 184                          *\r
 185                          *  @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the\r
 186                          *       call will fail.\r
 187                          *\r
 188                          *  @param SIInterfaceInfo : Pointer to a structure containing a Still Image Class host configuration and state.\r
 189                          *  @param PIMAHeader      : Pointer to a PIMA container structure where the received block is to be stored.\r
 190                          *\r
 191                          *  @return A value from the @ref Pipe_Stream_RW_ErrorCodes_t enum.\r
 192                          */\r
 193                         uint8_t SI_Host_ReceiveBlockHeader(USB_ClassInfo_SI_Host_t* const SIInterfaceInfo,\r
 194                                                            PIMA_Container_t* const PIMAHeader) ATTR_NON_NULL_PTR_ARG(1)\r
 195                                                            ATTR_NON_NULL_PTR_ARG(2);\r
 196 \r
 197                         /** @brief Sends a given PIMA command to the attached device, filling out the PIMA command header's Transaction ID automatically.\r
 198                          *\r
 199                          *  @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the\r
 200                          *       call will fail.\r
 201                          *\r
 202                          *  @param SIInterfaceInfo : Pointer to a structure containing a Still Image Class host configuration and state.\r
 203                          *  @param Operation       : PIMA operation code to issue to the device.\r
 204                          *  @param TotalParams     : Total number of 32-bit parameters to send to the device in the issued command block.\r
 205                          *  @param Params          : Pointer to an array of 32-bit values containing the parameters to send in the command block.\r
 206                          *\r
 207                          *  @return A value from the @ref Pipe_Stream_RW_ErrorCodes_t enum, or @ref SI_ERROR_LOGICAL_CMD_FAILED if the device\r
 208                          *          returned a logical command failure.\r
 209                          */\r
 210                         uint8_t SI_Host_SendCommand(USB_ClassInfo_SI_Host_t* const SIInterfaceInfo,\r
 211                                                     const uint16_t Operation,\r
 212                                                     const uint8_t TotalParams,\r
 213                                                     uint32_t* const Params) ATTR_NON_NULL_PTR_ARG(1);\r
 214 \r
 215                         /** @brief Receives and checks a response block from the attached Still Image device, once a command has been issued and all data\r
 216                          *  associated with the command has been transferred.\r
 217                          *\r
 218                          *  @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the\r
 219                          *       call will fail.\r
 220                          *\r
 221                          *  @param SIInterfaceInfo : Pointer to a structure containing a Still Image Class host configuration and state.\r
 222                          *\r
 223                          *  @return A value from the @ref Pipe_Stream_RW_ErrorCodes_t enum, or @ref SI_ERROR_LOGICAL_CMD_FAILED if the device\r
 224                          *          returned a logical command failure.\r
 225                          */\r
 226                         uint8_t SI_Host_ReceiveResponse(USB_ClassInfo_SI_Host_t* const SIInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);\r
 227 \r
 228                         /** @brief Indicates if the device has issued a PIMA event block to the host via the asynchronous events pipe.\r
 229                          *\r
 230                          *  @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the\r
 231                          *       call will fail.\r
 232                          *\r
 233                          *  @param SIInterfaceInfo : Pointer to a structure containing a Still Image Class host configuration and state.\r
 234                          *\r
 235                          *  @return Boolean \c true if an event is waiting to be read, \c false otherwise.\r
 236                          */\r
 237                         bool SI_Host_IsEventReceived(USB_ClassInfo_SI_Host_t* const SIInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);\r
 238 \r
 239                         /** @brief Receives an asynchronous event block from the device via the asynchronous events pipe.\r
 240                          *\r
 241                          *  @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the\r
 242                          *       call will fail.\r
 243                          *\r
 244                          *  @param SIInterfaceInfo : Pointer to a structure containing a Still Image Class host configuration and state.\r
 245                          *  @param PIMAHeader      : Pointer to a PIMA container structure where the event should be stored.\r
 246                          *\r
 247                          *  @return A value from the @ref Pipe_Stream_RW_ErrorCodes_t enum, or @ref SI_ERROR_LOGICAL_CMD_FAILED if the device\r
 248                          *          returned a logical command failure.\r
 249                          */\r
 250                         uint8_t SI_Host_ReceiveEventHeader(USB_ClassInfo_SI_Host_t* const SIInterfaceInfo,\r
 251                                                            PIMA_Container_t* const PIMAHeader) ATTR_NON_NULL_PTR_ARG(1)\r
 252                                                            ATTR_NON_NULL_PTR_ARG(2);\r
 253 \r
 254                         /** @brief Sends arbitrary data to the attached device, for use in the data phase of PIMA commands which require data\r
 255                          *  transfer beyond the regular PIMA command block parameters.\r
 256                          *\r
 257                          *  @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the\r
 258                          *       call will fail.\r
 259                          *\r
 260                          *  @param SIInterfaceInfo : Pointer to a structure containing a Still Image Class host configuration and state.\r
 261                          *  @param Buffer          : Pointer to a buffer where the data to send has been stored.\r
 262                          *  @param Bytes           : Length in bytes of the data in the buffer to send to the attached device.\r
 263                          *\r
 264                          *  @return A value from the @ref Pipe_Stream_RW_ErrorCodes_t enum.\r
 265                          */\r
 266                         uint8_t SI_Host_SendData(USB_ClassInfo_SI_Host_t* const SIInterfaceInfo,\r
 267                                                  void* Buffer,\r
 268                                                  const uint16_t Bytes) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);\r
 269 \r
 270                         /** @brief Receives arbitrary data from the attached device, for use in the data phase of PIMA commands which require data\r
 271                          *  transfer beyond the regular PIMA command block parameters.\r
 272                          *\r
 273                          *  @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the\r
 274                          *       call will fail.\r
 275                          *\r
 276                          *  @param SIInterfaceInfo : Pointer to a structure containing a Still Image Class host configuration and state.\r
 277                          *  @param Buffer          : Pointer to a buffer where the received data is to be stored.\r
 278                          *  @param Bytes           : Length in bytes of the data to read.\r
 279                          *\r
 280                          *  @return A value from the @ref Pipe_Stream_RW_ErrorCodes_t enum.\r
 281                          */\r
 282                         uint8_t SI_Host_ReadData(USB_ClassInfo_SI_Host_t* const SIInterfaceInfo,\r
 283                                                  void* Buffer,\r
 284                                                  const uint16_t Bytes) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);\r
 285 \r
 286                 /* Inline Functions: */\r
 287                         /** @brief General management task for a given Still Image host class interface, required for the correct operation of the\r
 288                          *  interface. This should be called frequently in the main program loop, before the master USB management task\r
 289                          *  @ref USB_USBTask().\r
 290                          *\r
 291                          *  @param SIInterfaceInfo : Pointer to a structure containing a Still Image Class host configuration and state.\r
 292                          *      @return Nothing\r
 293                          */\r
 294                         static inline void SI_Host_USBTask(USB_ClassInfo_SI_Host_t* const SIInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;\r
 295                         static inline void SI_Host_USBTask(USB_ClassInfo_SI_Host_t* const SIInterfaceInfo)\r
 296                         {\r
 297                                 (void)SIInterfaceInfo;\r
 298                         }\r
 299 \r
 300         /* Private Interface - For use in library only: */\r
 301         #if !defined(__DOXYGEN__)\r
 302                 /* Macros: */\r
 303                         #define SI_COMMAND_DATA_TIMEOUT_MS        10000\r
 304 \r
 305                 /* Function Prototypes: */\r
 306                         #if defined(__INCLUDE_FROM_STILLIMAGE_HOST_C)\r
 307                                 static uint8_t DCOMP_SI_Host_NextSIInterface(void* const CurrentDescriptor)\r
 308                                                                              ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1);\r
 309                                 static uint8_t DCOMP_SI_Host_NextSIInterfaceEndpoint(void* const CurrentDescriptor)\r
 310                                                                                      ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1);\r
 311                         #endif\r
 312         #endif\r
 313 \r
 314         /* Disable C linkage for C++ Compilers: */\r
 315                 #if defined(__cplusplus)\r
 316                         }\r
 317                 #endif\r
 318 \r
 319 #endif\r
 320 \r
 321 /** @} */\r
 322 \r