1 /* 2 * Copyright (c) 2015, Freescale Semiconductor, Inc. 3 * Copyright 2016 NXP 4 * All rights reserved. 5 * 6 * SPDX-License-Identifier: BSD-3-Clause 7 */ 8 9 #ifndef __USB_HOST_PHDC_H__ 10 #define __USB_HOST_PHDC_H__ 11 12 /******************************************************************************* 13 * PHDC class public structure, enumeration, macro, function 14 ******************************************************************************/ 15 /*! 16 * @addtogroup usb_host_phdc_drv 17 * @{ 18 */ 19 20 /******************************************************************************* 21 * Definitions 22 ******************************************************************************/ 23 24 /*! @brief PHDC class code */ 25 #define USB_HOST_PHDC_CLASS_CODE (0x0FU) 26 /*! @brief PHDC sub class code */ 27 #define USB_HOST_PHDC_SUBCLASS_CODE (0x00U) 28 /*! @brief PHDC protocol */ 29 #define USB_HOST_PHDC_PROTOCOL (0x00U) 30 /*! @brief PHDC get status request */ 31 #define USB_HOST_PHDC_GET_STATUS_REQUEST (0x00U) 32 /*! @brief PHDC set feature request */ 33 #define USB_HOST_PHDC_SET_FEATURE_REQUEST (0x03U) 34 /*! @brief PHDC clear feature request */ 35 #define USB_HOST_PHDC_CLEAR_FEATURE_REQUEST (0x01U) 36 /*! @brief PHDC meta-data feature */ 37 #define USB_HOST_PHDC_FEATURE_METADATA (0x01U) 38 /*! @brief PHDC QoS information encoding feature */ 39 #define USB_HOST_PHDC_QOS_ENCODING_VERSION (0x01U) 40 41 /*! @brief meta-data message preamble signature size */ 42 #define USB_HOST_PHDC_MESSAGE_PREAMBLE_SIGNATURE_SIZE (0x10U) 43 44 /*! @brief PHDC class function descriptor type */ 45 #define USB_HOST_PHDC_CLASSFUNCTION_DESCRIPTOR (0x20U) 46 /*! @brief PHDC QoS descriptor type */ 47 #define USB_HOST_PHDC_QOS_DESCRIPTOR (0x21U) 48 /*! @brief PHDC function extension descriptor type */ 49 #define USB_HOST_PHDC_11073PHD_FUNCTION_DESCRIPTOR (0x30U) 50 /*! @brief PHDC meta-data descriptor type */ 51 #define USB_HOST_PHDC_METADATA_DESCRIPTOR (0x22U) 52 53 /*! @brief PHDC class function descriptor structure as defined by the PHDC class specification */ 54 typedef struct _usb_host_phdc_class_function_desciptor 55 { 56 uint8_t bLength; /*!< Class function descriptor length */ 57 uint8_t bDescriptortype; /*!< PHDC_CLASSFUNCTION_DESCRIPTOR type */ 58 uint8_t bPhdcDataCode; /*!< Data/Messaging format code */ 59 uint8_t bmCapability; /*!< If bit 0 is 1 the meta-data message preamble is implemented and 0 if it is not */ 60 } usb_host_phdc_class_function_desciptor_t; 61 62 /*! @brief Function extension descriptor (device specialization) structure as defined by the PHDC class specification. 63 */ 64 typedef struct _usb_host_phdc_function_extension_descriptor 65 { 66 uint8_t bLength; /*!< Function extension descriptor length */ 67 uint8_t bDescriptortype; /*!< PHDC_CLASSFUNCTION_DESCRIPTOR type */ 68 uint8_t bReserved; /*!< Reserved for future use */ 69 uint8_t bNumDevSpecs; /*!< Number of wDevSpecializations */ 70 uint16_t *wDevSpecializations; /*!< Variable length list that defines the device specialization */ 71 } usb_host_phdc_function_extension_descriptor_t; 72 73 /*! @brief QoS descriptor structure as defined by the PHDC class specification. */ 74 typedef struct _usb_host_phdc_qos_descriptor 75 { 76 uint8_t bLength; /*!< QoS descriptor length */ 77 uint8_t bDescriptortype; /*!< PHDC_QOS_DESCRIPTOR type */ 78 uint8_t bQosEncodingVersion; /*!< Version of QoS information encoding */ 79 uint8_t bmLatencyReliability; /*!< Latency/reliability bin for the QoS data */ 80 } usb_host_phdc_qos_descriptor_t; 81 82 /*! @brief Metadata descriptor structure as defined by the PHDC class specification. */ 83 typedef struct _usb_host_phdc_metadata_descriptor 84 { 85 uint8_t bLength; /*!< Metadata descriptor length */ 86 uint8_t bDescriptortype; /*!< Descriptor type */ 87 uint8_t *bOpaqueData; /*!< Opaque metadata */ 88 } usb_host_phdc_metadata_descriptor_t; 89 90 /*! @brief Metadata message preamble structure as defined by the PHDC class specification. */ 91 typedef struct _usb_host_phdc_metadata_preamble 92 { 93 uint8_t 94 aSignature[USB_HOST_PHDC_MESSAGE_PREAMBLE_SIGNATURE_SIZE]; /*!< Constant used to give preamble verifiability */ 95 uint8_t bNumberTransfers; /*!< Count of following transfer to which the QoS setting applies */ 96 uint8_t bQosEncodingVersion; /*!< Version of QoS information encoding */ 97 uint8_t bmLatencyReliability; /*!< See latency/reliability bin for the QoS data */ 98 uint8_t bOpaqueDataSize; /*!< Opaque QoS data or meta-data size */ 99 uint8_t *bOpaqueData; /*!< Opaque metadata */ 100 } usb_host_phdc_metadata_preamble_t; 101 102 /*! @brief PHDC instance structure */ 103 typedef struct _usb_host_phdc_instance 104 { 105 usb_host_handle hostHandle; /*!< The host handle */ 106 usb_device_handle deviceHandle; /*!< The device handle */ 107 usb_host_interface_handle interfaceHandle; /*!< The interface handle */ 108 usb_host_pipe_handle controlPipe; /*!< The control pipe */ 109 usb_host_pipe_handle interruptPipe; /*!< The interrupt pipe */ 110 usb_host_pipe_handle bulkInPipe; /*!< The bulk in pipe */ 111 usb_host_pipe_handle bulkOutPipe; /*!< The bulk out pipe */ 112 transfer_callback_t inCallbackFn; /*!< The callback function is called when the PHDC receives complete */ 113 void *inCallbackParam; /*!< The first parameter of the in callback function */ 114 transfer_callback_t outCallbackFn; /*!< The callback function is called when the PHDC sends complete */ 115 void *outCallbackParam; /*!< The first parameter of the out callback function */ 116 transfer_callback_t controlCallbackFn; /*!< The control callback function */ 117 void *controlCallbackParam; /*!< The first parameter of the control callback function */ 118 usb_host_transfer_t *controlTransfer; /*!< The control transfer pointer */ 119 120 #if ((defined USB_HOST_CONFIG_CLASS_AUTO_CLEAR_STALL) && USB_HOST_CONFIG_CLASS_AUTO_CLEAR_STALL) 121 uint8_t *stallDataBuffer; /*!< keep the data buffer for stall transfer's data*/ 122 uint32_t stallDataLength; /*!< keep the data length for stall transfer's data*/ 123 #endif 124 125 usb_host_ep_t interruptInEndpointInformation; /*!< The interrupt in information */ 126 usb_host_ep_t bulkInEndpointInformation; /*!< The bulk in information */ 127 usb_host_ep_t bulkOutEndpointInformation; /*!< The bulk out information */ 128 uint8_t isMessagePreambleEnabled; /*!< The flag is used to check the message preamble feature is enabled or not */ 129 uint8_t numberTransferBulkOut; /*!< The number of transfer that follow Meta-data Message Preamble */ 130 uint8_t numberTransferBulkIn; /*!< The number of transfer that follow Meta-data Message Preamble */ 131 } usb_host_phdc_instance_t; 132 133 /******************************************************************************* 134 * API 135 ******************************************************************************/ 136 #ifdef __cplusplus 137 extern "C" { 138 #endif 139 140 /*! 141 * @name USB host PHDC class APIs 142 * @{ 143 */ 144 145 /*! 146 * @brief Initializes the PHDC instance. 147 * 148 * This function allocates the resource for PHDC instance. 149 * 150 * @param deviceHandle The device handle. 151 * @param classHandle Return class handle. 152 * 153 * @retval kStatus_USB_Success The device is initialized successfully. 154 * @retval kStatus_USB_AllocFail Allocate memory fail. 155 */ 156 extern usb_status_t USB_HostPhdcInit(usb_host_handle deviceHandle, usb_host_class_handle *classHandle); 157 158 /*! 159 * @brief Sets an interface. 160 * 161 * This function binds the interface with the PHDC instance. 162 * 163 * @param classHandle The class handle. 164 * @param interfaceHandle The interface handle. 165 * @param alternateSetting The alternate setting value. 166 * @param callbackFn This callback is called after this function completes. 167 * @param callbackParam The first parameter in the callback function. 168 * 169 * @retval kStatus_USB_Success The device is initialized successfully. 170 * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. 171 * @retval kStatus_USB_Busy There is no idle transfer. 172 * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSendSetup. 173 * @retval kStatus_USB_Busy Callback return status, there is no idle pipe. 174 * @retval kStatus_USB_TransferStall Callback return status, the transfer is stalled by the device. 175 * @retval kStatus_USB_Error Callback return status, open pipe fail. See the USB_HostOpenPipe. 176 */ 177 extern usb_status_t USB_HostPhdcSetInterface(usb_host_class_handle classHandle, 178 usb_host_interface_handle interfaceHandle, 179 uint8_t alternateSetting, 180 transfer_callback_t callbackFn, 181 void *callbackParam); 182 183 /*! 184 * @brief Deinitializes the PHDC instance. 185 * 186 * This function frees the resource for the PHDC instance. 187 * 188 * @param deviceHandle The device handle. 189 * @param classHandle The class handle. 190 * 191 * @retval kStatus_USB_Success The device is deinitialized successfully. 192 */ 193 extern usb_status_t USB_HostPhdcDeinit(usb_host_handle deviceHandle, usb_host_class_handle classHandle); 194 195 /*! 196 * @brief Receives data. 197 * 198 * This function implements the PHDC receiving data. 199 * 200 * @param classHandle The class handle. 201 * @param qos QoS of the data being received. 202 * @param buffer The buffer pointer. 203 * @param bufferLength The buffer length. 204 * @param callbackFn This callback is called after this function completes. 205 * @param callbackParam The first parameter in the callback function. 206 * 207 * @retval kStatus_USB_Success Receive request successfully. 208 * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. 209 * @retval kStatus_USB_Busy There is no idle transfer. 210 * @retval kStatus_USB_Error Pipe is not initialized. 211 * Or, send transfer fail. See the USB_HostRecv. 212 */ 213 extern usb_status_t USB_HostPhdcRecv(usb_host_class_handle classHandle, 214 uint8_t qos, 215 uint8_t *buffer, 216 uint32_t bufferLength, 217 transfer_callback_t callbackFn, 218 void *callbackParam); 219 220 /*! 221 * @brief Sends data. 222 * 223 * This function implements the PHDC sending data. 224 * 225 * @param classHandle The class handle. 226 * @param buffer The buffer pointer. 227 * @param bufferLength The buffer length. 228 * @param callbackFn This callback is called after this function completes. 229 * @param callbackParam The first parameter in the callback function. 230 * 231 * @retval kStatus_USB_Success Send request successfully. 232 * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. 233 * @retval kStatus_USB_Busy There is no idle transfer. 234 * @retval kStatus_USB_Error Pipe is not initialized. 235 * Or, send transfer fail. See the USB_HostSend. 236 */ 237 extern usb_status_t USB_HostPhdcSend(usb_host_class_handle classHandle, 238 uint8_t *buffer, 239 uint32_t bufferLength, 240 transfer_callback_t callbackFn, 241 void *callbackParam); 242 243 /*! 244 * @brief PHDC sends the control request. 245 * 246 * @param classHandle The class handle. 247 * @param request Setup packet request. 248 * @param callbackFn This callback is called after this function completes. 249 * @param callbackParam The first parameter in the callback function. 250 * 251 * @retval kStatus_USB_Success Send request successfully. 252 * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. 253 * @retval kStatus_USB_Busy There is no idle transfer. 254 * @retval kStatus_USB_Error Pipe is not initialized. 255 * Or, send transfer fail. See the USB_HostSend. 256 */ 257 extern usb_status_t USB_HostPhdcSendControlRequest(usb_host_class_handle classHandle, 258 uint8_t request, 259 transfer_callback_t callbackFn, 260 void *callbackParam); 261 262 /*! 263 * @brief PHDC set and clear feature endpoint halt request. 264 * 265 * @param classHandle The class handle. 266 * @param request Setup packet request. 267 * @param param Request parameter 268 * @param callbackFn This callback is called after this function completes. 269 * @param callbackParam The first parameter in the callback function. 270 * 271 * @retval kStatus_USB_Success Send request successfully. 272 * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. 273 * @retval kStatus_USB_Busy There is no idle transfer. 274 * @retval kStatus_USB_Error Pipe is not initialized. 275 * Or, send transfer fail. See the USB_HostSend. 276 */ 277 extern usb_status_t USB_HostPhdcSetClearFeatureEndpointHalt(usb_host_class_handle classHandle, 278 uint8_t request, 279 void *param, 280 transfer_callback_t callbackFn, 281 void *callbackParam); 282 283 /*! 284 * @brief USB_HostPhdcGetEndpointInformation. 285 * This function returns the PHDC endpoint information structure, which contains an endpoint 286 * descriptor and an endpoint extended descriptor. 287 * 288 * @param classHandle The class handle. 289 * @param pipeType Pipe type. 290 * @param direction Pipe direction. 291 * 292 * @retval endpointReturn All input parameters are valid. 293 * @retval NULL One or more input parameters are invalid. 294 */ 295 usb_host_ep_t *USB_HostPhdcGetEndpointInformation(usb_host_class_handle classHandle, 296 uint8_t pipeType, 297 uint8_t direction); 298 299 /*! @}*/ 300 301 #ifdef __cplusplus 302 } 303 #endif 304 305 /*! @}*/ 306 307 #endif /* _USB_HOST_PHDC_H_ */ 308
