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