1 /* 2 * Copyright (c) 2015 - 2016, Freescale Semiconductor, Inc. 3 * Copyright 2016 NXP 4 * All rights reserved. 5 * 6 * SPDX-License-Identifier: BSD-3-Clause 7 */ 8 9 #ifndef __USB_DEVICE_CLASS_H__ 10 #define __USB_DEVICE_CLASS_H__ 11 12 /*! 13 * @addtogroup usb_device_class_driver 14 * @{ 15 */ 16 17 /******************************************************************************* 18 * Definitions 19 ******************************************************************************/ 20 21 /*! @brief Macro to define class handle */ 22 typedef void *class_handle_t; 23 24 /*! @brief Available class types. */ 25 typedef enum _usb_usb_device_class_type 26 { 27 kUSB_DeviceClassTypeHid = 1U, 28 kUSB_DeviceClassTypeCdc, 29 kUSB_DeviceClassTypeMsc, 30 kUSB_DeviceClassTypeMtp, 31 kUSB_DeviceClassTypeAudio, 32 kUSB_DeviceClassTypePhdc, 33 kUSB_DeviceClassTypeVideo, 34 kUSB_DeviceClassTypePrinter, 35 kUSB_DeviceClassTypeDfu, 36 kUSB_DeviceClassTypeCcid, 37 } usb_device_class_type_t; 38 39 /*! @brief Available common class events. */ 40 typedef enum _usb_device_class_event 41 { 42 kUSB_DeviceClassEventClassRequest = 1U, 43 kUSB_DeviceClassEventDeviceReset, 44 kUSB_DeviceClassEventSetConfiguration, 45 kUSB_DeviceClassEventSetInterface, 46 kUSB_DeviceClassEventSetEndpointHalt, 47 kUSB_DeviceClassEventClearEndpointHalt, 48 } usb_device_class_event_t; 49 50 /*! 51 * @brief Obtains the endpoint data structure. 52 * 53 * Define the endpoint data structure. 54 * 55 */ 56 typedef struct _usb_device_endpoint_struct 57 { 58 uint8_t endpointAddress; /*!< Endpoint address*/ 59 uint8_t transferType; /*!< Endpoint transfer type*/ 60 uint16_t maxPacketSize; /*!< Endpoint maximum packet size */ 61 uint8_t interval; /*!< Endpoint interval*/ 62 } usb_device_endpoint_struct_t; 63 64 /*! 65 * @brief Obtains the endpoint group. 66 * 67 * Structure representing endpoints and the number of endpoints that the user wants. 68 * 69 */ 70 typedef struct _usb_device_endpoint_list 71 { 72 uint8_t count; /*!< How many endpoints in current interface*/ 73 usb_device_endpoint_struct_t *endpoint; /*!< Endpoint structure list*/ 74 } usb_device_endpoint_list_t; 75 76 /*! 77 * @brief Obtains the interface list data structure. 78 * 79 * Structure representing an interface. 80 * 81 */ 82 typedef struct _usb_device_interface_struct 83 { 84 uint8_t alternateSetting; /*!< Alternate setting number*/ 85 usb_device_endpoint_list_t endpointList; /*!< Endpoints of the interface*/ 86 void *classSpecific; /*!< Class specific structure handle*/ 87 } usb_device_interface_struct_t; 88 89 /*! 90 * @brief Obtains the interface data structure. 91 * 92 * Structure representing interface. 93 * 94 */ 95 typedef struct _usb_device_interfaces_struct 96 { 97 uint8_t classCode; /*!< Class code of the interface*/ 98 uint8_t subclassCode; /*!< Subclass code of the interface*/ 99 uint8_t protocolCode; /*!< Protocol code of the interface*/ 100 uint8_t interfaceNumber; /*!< Interface number*/ 101 usb_device_interface_struct_t *interface; /*!< Interface structure list*/ 102 uint8_t count; /*!< Number of interfaces in the current interface*/ 103 } usb_device_interfaces_struct_t; 104 105 /*! 106 * @brief Obtains the interface group. 107 * 108 * Structure representing how many interfaces in one class type. 109 * 110 */ 111 typedef struct _usb_device_interface_list 112 { 113 uint8_t count; /*!< Number of interfaces of the class*/ 114 usb_device_interfaces_struct_t *interfaces; /*!< All interfaces*/ 115 } usb_device_interface_list_t; 116 117 /*! 118 * @brief Obtains the class data structure. 119 * 120 * Structure representing how many configurations in one class type. 121 * 122 */ 123 typedef struct _usb_device_class_struct 124 { 125 usb_device_interface_list_t *interfaceList; /*!< Interfaces of the class*/ 126 usb_device_class_type_t type; /*!< Class type*/ 127 uint8_t configurations; /*!< Number of configurations of the class*/ 128 } usb_device_class_struct_t; 129 130 /*callback function pointer structure for application to provide class parameters*/ 131 typedef usb_status_t (*usb_device_class_callback_t)(class_handle_t classHandle, 132 uint32_t callbackEvent, 133 void *eventParam); 134 135 /*! 136 * @brief Obtains the device class information structure. 137 * 138 * Structure representing the device class information. This structure only can be stored in RAM space. 139 * 140 */ 141 typedef struct _usb_device_class_config_struct 142 { 143 usb_device_class_callback_t classCallback; /*!< Class callback function to handle the device status-related event 144 for the specified type of class*/ 145 class_handle_t classHandle; /*!< The class handle of the class, filled by the common driver.*/ 146 usb_device_class_struct_t *classInfomation; /*!< Detailed information of the class*/ 147 } usb_device_class_config_struct_t; 148 149 /*! 150 * @brief Obtains the device class configuration structure. 151 * 152 * Structure representing the device class configuration information. 153 * 154 */ 155 typedef struct _usb_device_class_config_list_struct 156 { 157 usb_device_class_config_struct_t *config; /*!< Array of class configuration structures */ 158 usb_device_callback_t deviceCallback; /*!< Device callback function */ 159 uint8_t count; /*!< Number of class supported */ 160 } usb_device_class_config_list_struct_t; 161 162 /*! 163 * @brief Obtains the control request structure. 164 * 165 * This structure is used to pass the control request information. 166 * The structure is used in following two cases. 167 * 1. Case one, the host wants to send data to the device in the control data stage: @n 168 * a. If a setup packet is received, the structure is used to pass the setup packet data and wants to get the 169 * buffer to receive data sent from the host. 170 * The field isSetup is 1. 171 * The length is the requested buffer length. 172 * The buffer is filled by the class or application by using the valid buffer address. 173 * The setup is the setup packet address. 174 * b. If the data received is sent by the host, the structure is used to pass the data buffer address and the 175 * data 176 * length sent by the host. 177 * In this way, the field isSetup is 0. 178 * The buffer is the address of the data sent from the host. 179 * The length is the received data length. 180 * The setup is the setup packet address. @n 181 * 2. Case two, the host wants to get data from the device in control data stage: @n 182 * If the setup packet is received, the structure is used to pass the setup packet data and wants to get the 183 * data buffer address to send data to the host. 184 * The field isSetup is 1. 185 * The length is the requested data length. 186 * The buffer is filled by the class or application by using the valid buffer address. 187 * The setup is the setup packet address. 188 * 189 */ 190 typedef struct _usb_device_control_request_struct 191 { 192 usb_setup_struct_t *setup; /*!< The pointer of the setup packet data. */ 193 uint8_t *buffer; /*!< Pass the buffer address. */ 194 uint32_t length; /*!< Pass the buffer length or requested length. */ 195 uint8_t isSetup; /*!< Indicates whether a setup packet is received. */ 196 } usb_device_control_request_struct_t; 197 198 /*! @brief Obtains the control get descriptor request common structure. */ 199 typedef struct _usb_device_get_descriptor_common_struct 200 { 201 uint8_t *buffer; /*!< Pass the buffer address. */ 202 uint32_t length; /*!< Pass the buffer length. */ 203 } usb_device_get_descriptor_common_struct_t; 204 205 /*! @brief Obtains the control get device descriptor request structure. */ 206 typedef struct _usb_device_get_device_descriptor_struct 207 { 208 uint8_t *buffer; /*!< Pass the buffer address. */ 209 uint32_t length; /*!< Pass the buffer length. */ 210 } usb_device_get_device_descriptor_struct_t; 211 212 /*! @brief Obtains the control get device qualifier descriptor request structure. */ 213 typedef struct _usb_device_get_device_qualifier_descriptor_struct 214 { 215 uint8_t *buffer; /*!< Pass the buffer address. */ 216 uint32_t length; /*!< Pass the buffer length. */ 217 } usb_device_get_device_qualifier_descriptor_struct_t; 218 219 /*! @brief Obtains the control get configuration descriptor request structure. */ 220 typedef struct _usb_device_get_configuration_descriptor_struct 221 { 222 uint8_t *buffer; /*!< Pass the buffer address. */ 223 uint32_t length; /*!< Pass the buffer length. */ 224 uint8_t configuration; /*!< The configuration number. */ 225 } usb_device_get_configuration_descriptor_struct_t; 226 227 /*! @brief Obtains the control get bos descriptor request structure. */ 228 typedef struct _usb_device_get_bos_descriptor_struct 229 { 230 uint8_t *buffer; /*!< Pass the buffer address. */ 231 uint32_t length; /*!< Pass the buffer length. */ 232 } usb_device_get_bos_descriptor_struct_t; 233 234 /*! @brief Obtains the control get string descriptor request structure. */ 235 typedef struct _usb_device_get_string_descriptor_struct 236 { 237 uint8_t *buffer; /*!< Pass the buffer address. */ 238 uint32_t length; /*!< Pass the buffer length. */ 239 uint16_t languageId; /*!< Language ID. */ 240 uint8_t stringIndex; /*!< String index. */ 241 } usb_device_get_string_descriptor_struct_t; 242 243 /*! @brief Obtains the control get HID descriptor request structure. */ 244 typedef struct _usb_device_get_hid_descriptor_struct 245 { 246 uint8_t *buffer; /*!< Pass the buffer address. */ 247 uint32_t length; /*!< Pass the buffer length. */ 248 uint8_t interfaceNumber; /*!< The interface number. */ 249 } usb_device_get_hid_descriptor_struct_t; 250 251 /*! @brief Obtains the control get HID report descriptor request structure. */ 252 typedef struct _usb_device_get_hid_report_descriptor_struct 253 { 254 uint8_t *buffer; /*!< Pass the buffer address. */ 255 uint32_t length; /*!< Pass the buffer length. */ 256 uint8_t interfaceNumber; /*!< The interface number. */ 257 } usb_device_get_hid_report_descriptor_struct_t; 258 259 /*! @brief Obtains the control get HID physical descriptor request structure. */ 260 typedef struct _usb_device_get_hid_physical_descriptor_struct 261 { 262 uint8_t *buffer; /*!< Pass the buffer address. */ 263 uint32_t length; /*!< Pass the buffer length. */ 264 uint8_t index; /*!< Physical index */ 265 uint8_t interfaceNumber; /*!< The interface number. */ 266 } usb_device_get_hid_physical_descriptor_struct_t; 267 268 /*! @brief Obtains the control get descriptor request common union. */ 269 typedef union _usb_device_get_descriptor_common_union 270 { 271 usb_device_get_descriptor_common_struct_t commonDescriptor; /*!< Common structure. */ 272 usb_device_get_device_descriptor_struct_t deviceDescriptor; /*!< The structure to get device descriptor. */ 273 usb_device_get_device_qualifier_descriptor_struct_t 274 deviceQualifierDescriptor; /*!< The structure to get device qualifier descriptor. */ 275 usb_device_get_configuration_descriptor_struct_t 276 configurationDescriptor; /*!< The structure to get configuration descriptor. */ 277 usb_device_get_string_descriptor_struct_t stringDescriptor; /*!< The structure to get string descriptor. */ 278 usb_device_get_hid_descriptor_struct_t hidDescriptor; /*!< The structure to get HID descriptor. */ 279 usb_device_get_hid_report_descriptor_struct_t 280 hidReportDescriptor; /*!< The structure to get HID report descriptor. */ 281 usb_device_get_hid_physical_descriptor_struct_t 282 hidPhysicalDescriptor; /*!< The structure to get HID physical descriptor. */ 283 } usb_device_get_descriptor_common_union_t; 284 285 /*! @brief Define function type for class device instance initialization */ 286 typedef usb_status_t (*usb_device_class_init_call_t)(uint8_t controllerId, 287 usb_device_class_config_struct_t *classConfig, 288 class_handle_t *classHandle); 289 /*! @brief Define function type for class device instance deinitialization, internal */ 290 typedef usb_status_t (*usb_device_class_deinit_call_t)(class_handle_t handle); 291 /*! @brief Define function type for class device instance Event change */ 292 typedef usb_status_t (*usb_device_class_event_callback_t)(void *classHandle, uint32_t event, void *param); 293 294 /*! @brief Define class driver interface structure. */ 295 typedef struct _usb_device_class_map 296 { 297 usb_device_class_init_call_t classInit; /*!< Class driver initialization- entry of the class driver */ 298 usb_device_class_deinit_call_t classDeinit; /*!< Class driver de-initialization*/ 299 usb_device_class_event_callback_t classEventCallback; /*!< Class driver event callback*/ 300 usb_device_class_type_t type; /*!< Class type*/ 301 } usb_device_class_map_t; 302 303 /*! @brief Structure holding common class state information */ 304 typedef struct _usb_device_common_class_struct 305 { 306 usb_device_handle handle; /*!< USB device handle*/ 307 usb_device_class_config_list_struct_t *configList; /*!< USB device configure list*/ 308 uint8_t *setupBuffer; /*!< Setup packet data buffer*/ 309 uint16_t standardTranscationBuffer; /*!< 310 * This variable is used in: 311 * get status request 312 * get configuration request 313 * get interface request 314 * set interface request 315 * get sync frame request 316 */ 317 uint8_t controllerId; /*!< Controller ID*/ 318 } usb_device_common_class_struct_t; 319 320 /******************************************************************************* 321 * API 322 ******************************************************************************/ 323 324 #if defined(__cplusplus) 325 extern "C" { 326 #endif 327 328 /*! 329 * @brief Initializes the common class and the supported classes. 330 * 331 * This function is used to initialize the common class and the supported classes. 332 * 333 * @param[in] controllerId The controller ID of the USB IP. See the enumeration #usb_controller_index_t. 334 * @param[in] configList The class configurations. The pointer must point to the global variable. 335 * See the structure #usb_device_class_config_list_struct_t. 336 * @param[out] handle A parameter used to return pointer of the device handle to the caller. 337 * The value of the parameter is a pointer to the device handle. This design is used to 338 * make a simple device align with the composite device. For the composite device, there are 339 * many 340 * kinds of class handles. However, there is only one device handle. Therefore, the handle 341 * points to 342 * a device instead of a class. The class handle can be received from the 343 * #usb_device_class_config_struct_t::classHandle after the function successfully. 344 * 345 * @return A USB error code or kStatus_USB_Success. 346 */ 347 usb_status_t USB_DeviceClassInit(uint8_t controllerId, 348 usb_device_class_config_list_struct_t *configList, 349 usb_device_handle *handle); 350 351 /*! 352 * @brief Deinitializes the common class and the supported classes. 353 * 354 * This function is used to deinitialize the common class and the supported classes. 355 * 356 * @param[in] controllerId The controller ID of the USB IP. See the enumeration #usb_controller_index_t. 357 * 358 * @return A USB error code or kStatus_USB_Success. 359 */ 360 usb_status_t USB_DeviceClassDeinit(uint8_t controllerId); 361 362 /*! 363 * @brief Gets the USB bus speed. 364 * 365 * This function is used to get the USB bus speed. 366 * 367 * @param[in] controllerId The controller ID of the USB IP. See the enumeration #usb_controller_index_t. 368 * @param[out] speed It is an OUT parameter, which returns the current speed of the controller. 369 * 370 * @return A USB error code or kStatus_USB_Success. 371 */ 372 usb_status_t USB_DeviceClassGetSpeed(uint8_t controllerId, uint8_t *speed); 373 374 /*! 375 * @brief Handles the event passed to the class drivers. 376 * 377 * This function handles the event passed to the class drivers. 378 * 379 * @param[in] handle The device handle received from the #USB_DeviceInit. 380 * @param[in] event The event codes. See the enumeration #usb_device_class_event_t. 381 * @param[in,out] param The parameter type is determined by the event code. 382 * 383 * @return A USB error code or kStatus_USB_Success. 384 * @retval kStatus_USB_Success A valid request has been handled. 385 * @retval kStatus_USB_InvalidParameter The device handle not be found. 386 * @retval kStatus_USB_InvalidRequest The request is invalid, and the control pipe is stalled by the caller. 387 */ 388 usb_status_t USB_DeviceClassEvent(usb_device_handle handle, usb_device_class_event_t event, void *param); 389 390 /*! 391 * @brief Handles the common class callback. 392 * 393 * This function handles the common class callback. 394 * 395 * @param[in] handle The device handle received from the #USB_DeviceInit. 396 * @param[in] event The event codes. See the enumeration #usb_device_event_t. 397 * @param[in,out] param The parameter type is determined by the event code. 398 * 399 * @return A USB error code or kStatus_USB_Success. 400 */ 401 usb_status_t USB_DeviceClassCallback(usb_device_handle handle, uint32_t event, void *param); 402 403 /*! 404 * @brief Gets the device handle according to the controller ID. 405 * 406 * This function gets the device handle according to the controller ID. 407 * 408 * @param[in] controllerId The controller ID of the USB IP. See the enumeration #usb_controller_index_t. 409 * @param[out] handle An out parameter used to return the pointer of the device handle to the caller. 410 * 411 * @retval kStatus_USB_Success Get device handle successfully. 412 * @retval kStatus_USB_InvalidParameter The device handle can't be found. 413 */ 414 usb_status_t USB_DeviceClassGetDeviceHandle(uint8_t controllerId, usb_device_handle *handle); 415 416 #if defined(USB_DEVICE_CONFIG_GET_SOF_COUNT) && (USB_DEVICE_CONFIG_GET_SOF_COUNT > 0U) 417 /*! 418 * @brief Get the USB SOF count. 419 * 420 * This function is used to get the USB SOF count. 421 * 422 * @param controllerId The controller id of the USB IP. Please refer to the enumeration usb_controller_index_t. 423 * @param currentFrameCount It is an OUT parameter, return current sof count of the controller. 424 * HS: micro frame count, FS: frame count 425 * 426 * @return A USB error code or kStatus_USB_Success. 427 */ 428 usb_status_t USB_DeviceClassGetCurrentFrameCount(uint8_t controllerId, /*!< [IN] Controller ID */ 429 uint32_t *currentFrameCount /*!< [OUT] Current frame count */ 430 ); 431 #endif 432 433 #if defined(__cplusplus) 434 } 435 #endif 436 437 /*! @}*/ 438 439 #endif /* __USB_DEVICE_CLASS_H__ */ 440
