1 /**
2 \defgroup usbd_interface_gr USB Device Interface
3 \ingroup usb_interface_gr
4 \brief Driver API for USB Device Peripheral (%Driver_USBD.h)
5 @{
6 */
7
8 /**
9 \struct ARM_DRIVER_USBD
10 \details
11 The functions of the USB Device driver are accessed by function pointers. Refer to \ref DriverFunctions for
12 overview information.
13
14 Each instance of an USBD provides such an access struct. The instance is indicated by
15 a postfix in the symbol name of the access struct, for example:
16 - \b Driver_USBD0 is the name of the access struct of the first instance (no. 0).
17 - \b Driver_USBD1 is the name of the access struct of the second instance (no. 1).
18
19
20 A configuration setting in the middleware allows connecting the middleware to a specific driver instance <b>Driver_USBD<i>n</i></b>.
21 The default is \token{0}, which connects a middleware to the first instance of a driver.
22
23 \note The struct must remain unchanged.
24 *****************************************************************************************************************/
25
26 /**
27 \struct ARM_USBD_CAPABILITIES
28 \details
29 A USB Device driver can be implemented with different capabilities.
30 The data fields of this structure encode the capabilities implemented by this driver.
31
32 <b>Returned by:</b>
33 - \ref ARM_USBD_GetCapabilities
34
35 \note The struct must remain unchanged.
36 *****************************************************************************************************************/
37
38 /**
39 \struct ARM_USBD_STATE
40 \details
41 This structure stores information about the state of the USB Device. The data fields encode the established speed,
42 whether the device is powered and active.
43
44 <b>Returned by:</b>
45 - \ref ARM_USBD_DeviceGetState
46 *****************************************************************************************************************/
47
48 /**
49 \typedef ARM_USBD_SignalDeviceEvent_t
50 \details
51 Provides the typedef for the callback function \ref ARM_USBD_SignalDeviceEvent.
52
53 <b>Parameter for:</b>
54 - \ref ARM_USBD_Initialize
55 *******************************************************************************************************************/
56
57 /**
58 \typedef ARM_USBD_SignalEndpointEvent_t
59 \details
60 Provides the typedef for the callback function \ref ARM_USBD_SignalEndpointEvent.
61
62 <b>Parameter for:</b>
63 - \ref ARM_USBD_Initialize
64 *******************************************************************************************************************/
65
66 /**
67 \defgroup USBD_dev_events USBD Device Events
68 \ingroup usbd_interface_gr
69 \brief The USB Device driver generates Device call back events that are notified via the function \ref ARM_USBD_SignalDeviceEvent.
70 \details
71 This section provides the event values for the \ref ARM_USBD_SignalDeviceEvent callback function.
72
73 The following call back notification events are generated:
74 @{
75 \def ARM_USBD_EVENT_VBUS_ON
76 \def ARM_USBD_EVENT_VBUS_OFF
77 \def ARM_USBD_EVENT_RESET
78 \def ARM_USBD_EVENT_HIGH_SPEED
79 \def ARM_USBD_EVENT_SUSPEND
80 \def ARM_USBD_EVENT_RESUME
81 @}
82 */
83
84 /**
85 \defgroup USBD_ep_events USBD Endpoint Events
86 \ingroup usbd_interface_gr
87 \brief The USB Device driver generates Endpoint call back events that are notified via the function \ref ARM_USBD_SignalEndpointEvent.
88 \details
89 This section provides the event values for the \ref ARM_USBD_SignalEndpointEvent callback function.
90
91 The following call back notification events are generated:
92 @{
93 \def ARM_USBD_EVENT_SETUP
94 \def ARM_USBD_EVENT_OUT
95 \def ARM_USBD_EVENT_IN
96 @}
97 */
98
99
100 //
101 // Functions
102 //
103
ARM_USBD_GetVersion(void)104 ARM_DRIVER_VERSION ARM_USBD_GetVersion (void) {
105 return { 0, 0 };
106 }
107 /**
108 \fn ARM_DRIVER_VERSION ARM_USBD_GetVersion (void)
109 \details
110 The function \b ARM_USBD_GetVersion returns version information of the driver implementation in \ref ARM_DRIVER_VERSION
111 - API version is the version of the CMSIS-Driver specification used to implement this driver.
112 - Driver version is source code version of the actual driver implementation.
113
114 Example:
115 \code
116 extern ARM_DRIVER_USBD Driver_USBD0;
117 ARM_DRIVER_USBD *drv_info;
118
119 void setup_usbd (void) {
120 ARM_DRIVER_VERSION version;
121
122 drv_info = &Driver_USBD0;
123 version = drv_info->GetVersion ();
124 if (version.api < 0x10A) { // requires at minimum API version 1.10 or higher
125 // error handling
126 return;
127 }
128 }
129 \endcode
130 *****************************************************************************************************************/
131
ARM_USBD_GetCapabilities(void)132 ARM_USBD_CAPABILITIES ARM_USBD_GetCapabilities (void) {
133 return { 0 };
134 }
135 /**
136 \fn ARM_USBD_CAPABILITIES ARM_USBD_GetCapabilities (void)
137 \details
138 The function \b ARM_USBD_GetCapabilities returns information about capabilities in this driver implementation.
139 The data fields of the structure \ref ARM_USBD_CAPABILITIES encode various capabilities, for example
140 if the hardware can create signal events using the \ref ARM_USBD_SignalDeviceEvent callback function.
141
142 Example:
143 \code
144 extern ARM_DRIVER_USBD Driver_USBD0;
145 ARM_DRIVER_USBD *drv_info;
146
147 void read_capabilities (void) {
148 ARM_USBD_CAPABILITIES drv_capabilities;
149
150 drv_info = &Driver_USBD0;
151 drv_capabilities = drv_info->GetCapabilities ();
152 // interrogate capabilities
153
154 }
155 \endcode
156 *****************************************************************************************************************/
157
ARM_USBD_Initialize(ARM_USBD_SignalDeviceEvent_t cb_device_event,ARM_USBD_SignalEndpointEvent_t cb_endpoint_event)158 int32_t ARM_USBD_Initialize (ARM_USBD_SignalDeviceEvent_t cb_device_event,
159 ARM_USBD_SignalEndpointEvent_t cb_endpoint_event) {
160 return ARM_DRIVER_OK;
161 }
162 /**
163 \fn int32_t ARM_USBD_Initialize (ARM_USBD_SignalDeviceEvent_t cb_device_event, ARM_USBD_SignalEndpointEvent_t cb_endpoint_event)
164 \details
165 The function \b ARM_USBD_Initialize initializes the USB Device interface.
166 It is called when the middleware component starts operation.
167
168 The function performs the following operations:
169 - Initializes the resources needed for the USBD interface.
170 - Registers the \ref ARM_USBD_SignalDeviceEvent callback function.
171 - Registers the \ref ARM_USBD_SignalEndpointEvent callback function.
172
173 The parameter \em cb_device_event is a pointer to the \ref ARM_USBD_SignalDeviceEvent callback function; use a NULL pointer
174 when no device callback signals are required. \n
175 The parameter \em cb_endpoint_event is a pointer to the \ref ARM_USBD_SignalEndpointEvent callback function.
176
177 \b Example:
178 - see \ref usbd_interface_gr - Driver Functions
179
180 *****************************************************************************************************************/
181
ARM_USBD_Uninitialize(void)182 int32_t ARM_USBD_Uninitialize (void) {
183 return ARM_DRIVER_OK;
184 }
185 /**
186 \fn int32_t ARM_USBD_Uninitialize (void)
187 \details
188 The function \b ARM_USBD_Uninitialize de-initializes the resources of USBD interface.
189
190 It is called when the middleware component stops operation and releases the software resources used by the interface.
191 *****************************************************************************************************************/
192
ARM_USBD_PowerControl(ARM_POWER_STATE state)193 int32_t ARM_USBD_PowerControl (ARM_POWER_STATE state) {
194 return ARM_DRIVER_OK;
195 }
196 /**
197 \fn int32_t ARM_USBD_PowerControl (ARM_POWER_STATE state)
198 \details
199 The function \b ARM_USBD_PowerControl operates the power modes of the USB Device interface.
200
201 The parameter \em state sets the operation and can have the following values:
202 - \ref ARM_POWER_FULL : set-up peripheral for data transfers, enable interrupts (NVIC) and optionally DMA.
203 Can be called multiple times. If the peripheral is already in this mode the function performs
204 no operation and returns with \ref ARM_DRIVER_OK.
205 - \ref ARM_POWER_LOW : may use power saving. Returns \ref ARM_DRIVER_ERROR_UNSUPPORTED when not implemented.
206 - \ref ARM_POWER_OFF : terminates any pending data transfers, disables peripheral, disables related interrupts and DMA.
207
208 Refer to \ref CallSequence for more information.
209 *****************************************************************************************************************/
210
ARM_USBD_DeviceConnect(void)211 int32_t ARM_USBD_DeviceConnect (void) {
212 return ARM_DRIVER_OK;
213 }
214 /**
215 \fn int32_t ARM_USBD_DeviceConnect (void)
216 \details
217 The function \b ARM_USBD_DeviceConnect signals to the host that the device is connected.
218 *****************************************************************************************************************/
219
ARM_USBD_DeviceDisconnect(void)220 int32_t ARM_USBD_DeviceDisconnect (void) {
221 return ARM_DRIVER_OK;
222 }
223 /**
224 \fn int32_t ARM_USBD_DeviceDisconnect (void)
225 \details
226 The function \b ARM_USBD_DeviceDisconnect signals to the host that the device is disconnected.
227 *****************************************************************************************************************/
228
ARM_USBD_DeviceGetState(void)229 ARM_USBD_STATE ARM_USBD_DeviceGetState (void) {
230 return ARM_DRIVER_OK;
231 }
232 /**
233 \fn ARM_USBD_STATE ARM_USBD_DeviceGetState (void)
234 \details
235 Retrieves the current USB device state.
236 *****************************************************************************************************************/
237
ARM_USBD_DeviceRemoteWakeup(void)238 int32_t ARM_USBD_DeviceRemoteWakeup (void) {
239 return ARM_DRIVER_OK;
240 }
241 /**
242 \fn int32_t ARM_USBD_DeviceRemoteWakeup (void)
243 \details
244 The function \b ARM_USBD_DeviceRemoteWakeup signals remote wakeup to the host.
245 *****************************************************************************************************************/
246
ARM_USBD_DeviceSetAddress(uint8_t dev_addr)247 int32_t ARM_USBD_DeviceSetAddress (uint8_t dev_addr) {
248 return ARM_DRIVER_OK;
249 }
250 /**
251 \fn int32_t ARM_USBD_DeviceSetAddress (uint8_t dev_addr)
252 \details
253 Assigns an address to the device.
254 \note This function is called after status stage of the Set Address request (after IN packet in status stage was sent with the old address).
255
256 *****************************************************************************************************************/
257
ARM_USBD_ReadSetupPacket(uint8_t * setup)258 int32_t ARM_USBD_ReadSetupPacket (uint8_t *setup) {
259 return ARM_DRIVER_OK;
260 }
261 /**
262 \fn int32_t ARM_USBD_ReadSetupPacket (uint8_t *setup)
263 \details
264 The function \b ARM_USBD_ReadSetupPacket reads the last SETUP packet (8 bytes) that was received over Control Endpoint (Endpoint 0)
265 which is indicated by \ref ARM_USBD_EVENT_SETUP event.
266
267 <b>See also:</b>
268 - \ref ARM_USBD_SignalEndpointEvent
269 *****************************************************************************************************************/
270
ARM_USBD_EndpointConfigure(uint8_t ep_addr,uint8_t ep_type,uint16_t ep_max_packet_size)271 int32_t ARM_USBD_EndpointConfigure (uint8_t ep_addr,
272 uint8_t ep_type,
273 uint16_t ep_max_packet_size) {
274 return ARM_DRIVER_OK;
275 }
276 /**
277 \fn int32_t ARM_USBD_EndpointConfigure (uint8_t ep_addr, uint8_t ep_type, uint16_t ep_max_packet_size)
278 \details
279 The function \b ARM_USBD_EndpointConfigure configures an endpoint for transfers.
280
281
282 *****************************************************************************************************************/
283
ARM_USBD_EndpointUnconfigure(uint8_t ep_addr)284 int32_t ARM_USBD_EndpointUnconfigure (uint8_t ep_addr) {
285 return ARM_DRIVER_OK;
286 }
287 /**
288 \fn int32_t ARM_USBD_EndpointUnconfigure (uint8_t ep_addr)
289 \details
290 The function \b ARM_USBD_EndpointUnconfigure de-configures the specified endpoint.
291
292 The parameter \em ep_addr specifies the endpoint address.
293 *****************************************************************************************************************/
294
ARM_USBD_EndpointStall(uint8_t ep_addr,bool stall)295 int32_t ARM_USBD_EndpointStall (uint8_t ep_addr, bool stall) {
296 return ARM_DRIVER_OK;
297 }
298 /**
299 \fn int32_t ARM_USBD_EndpointStall (uint8_t ep_addr, bool stall)
300 \details
301 The function \b ARM_USBD_EndpointStall sets or clears stall condition for the specified endpoint.
302
303 The parameter \em ep_addr specifies the endpoint address. \n
304 The parameter \em stall is a boolean parameter.
305 *****************************************************************************************************************/
306
ARM_USBD_EndpointTransfer(uint8_t ep_addr,uint8_t * data,uint32_t num)307 int32_t ARM_USBD_EndpointTransfer (uint8_t ep_addr, uint8_t *data, uint32_t num) {
308 return ARM_DRIVER_OK;
309 }
310 /**
311 \fn int32_t ARM_USBD_EndpointTransfer (uint8_t ep_addr, uint8_t *data, uint32_t num)
312 \details
313
314 The function \b ARM_USBD_EndpointTransfer reads from or writes data to an USB Endpoint.
315
316 The parameter \em ep_addr specifies the endpoint address. \n
317 The parameter \em data is a buffer for data to read or data to write. \n
318 The parameter \em num is the number of bytes to transfer (must be multiple of endpoint maximum packet size for Read transfers).
319
320 The function is non-blocking and returns as soon as the driver starts the operation on the specified endpoint.
321 During the operation it is not allowed to call this function again on the same endpoint.
322 Also the data buffer must stay allocated and the contents of data must not be modified.
323
324 Direction in the endpoint address specifies the type of transfer:
325 - Endpoint Read for OUT endpoint (direction = 0)
326 - Endpoint Write for IN endpoint (direction = 1)
327
328 Endpoint Read is finished when the requested number of data bytes have been received or when a short packet or ZLP (Zero-Length Packet) has been received.
329 Completion of operation is indicated by \ref ARM_USBD_EVENT_OUT event. Number of successfully received data bytes can be retrieved
330 by calling \ref ARM_USBD_EndpointTransferGetResult.
331
332 Endpoint Write is finished when the requested number of data bytes have been sent.
333 Completion of operation is indicated by \ref ARM_USBD_EVENT_IN event. Number of successfully sent data bytes can be retrieved
334 by calling \ref ARM_USBD_EndpointTransferGetResult.
335
336 Transfer operation can be aborted by calling \ref ARM_USBD_EndpointTransferAbort.
337 *****************************************************************************************************************/
338
ARM_USBD_EndpointTransferGetResult(uint8_t ep_addr)339 uint32_t ARM_USBD_EndpointTransferGetResult (uint8_t ep_addr) {
340 return 0;
341 }
342 /**
343 \fn uint32_t ARM_USBD_EndpointTransferGetResult (uint8_t ep_addr)
344 \details
345 The function \b ARM_USBD_EndpointTransferGetResult returns the number of successfully transferred data bytes started by \ref ARM_USBD_EndpointTransfer.
346
347 The parameter \em ep_addr specifies the endpoint address.
348 *****************************************************************************************************************/
349
ARM_USBD_EndpointTransferAbort(uint8_t ep_addr)350 int32_t ARM_USBD_EndpointTransferAbort (uint8_t ep_addr) {
351 return ARM_DRIVER_OK;
352 }
353 /**
354 \fn int32_t ARM_USBD_EndpointTransferAbort (uint8_t ep_addr)
355 \details
356 The function \b ARM_USBD_EndpointTransferAbort aborts the transfer to an endpoint started by \ref ARM_USBD_EndpointTransfer.
357
358 The parameter \em ep_addr specifies the endpoint address.
359 *****************************************************************************************************************/
360
ARM_USBD_GetFrameNumber(void)361 uint16_t ARM_USBD_GetFrameNumber (void) {
362 return 0;
363 }
364 /**
365 \fn uint16_t ARM_USBD_GetFrameNumber (void)
366 \details
367 Retrieves the sequential 11-bit frame number of the last Start of Frame (SOF) packet.
368 *****************************************************************************************************************/
369
ARM_USBD_SignalDeviceEvent(uint32_t event)370 void ARM_USBD_SignalDeviceEvent (uint32_t event) {
371 // function body
372 }
373 /**
374 \fn void ARM_USBD_SignalDeviceEvent (uint32_t event)
375 \details
376 The function \b ARM_USBD_SignalDeviceEvent is a callback function registered by the function \ref ARM_USBD_Initialize.
377
378 The parameter \em event indicates one or more events that occurred during driver operation.
379 Each event is encoded in a separate bit and therefore it is possible to signal multiple events within the same call.
380
381 Not every event is necessarily generated by the driver. This depends on the implemented capabilities stored in the
382 data fields of the structure \ref ARM_USBD_CAPABILITIES, which can be retrieved with the function \ref ARM_USBD_GetCapabilities.
383
384 The following events can be generated:
385
386 Event | Bit| Description | supported when \ref ARM_USBD_CAPABILITIES
387 :-------------------------------|---:|:---------------------------------------------------|----------------------------------------------
388 \ref ARM_USBD_EVENT_VBUS_ON | 0 | Occurs when valid VBUS voltage is detected. | data field \em event_vbus_on = \token{1}
389 \ref ARM_USBD_EVENT_VBUS_OFF | 1 | Occurs when VBUS voltage is turned off. | data field \em event_vbus_off = \token{1}
390 \ref ARM_USBD_EVENT_RESET | 2 | Occurs when USB Reset is detected. | <i>always supported</i>
391 \ref ARM_USBD_EVENT_HIGH_SPEED | 3 | Occurs when USB Device is switched to High-speed. | <i>always supported</i>
392 \ref ARM_USBD_EVENT_SUSPEND | 4 | Occurs when USB Suspend is detected. | <i>always supported</i>
393 \ref ARM_USBD_EVENT_RESUME | 5 | Occurs when USB Resume is detected. | <i>always supported</i>
394 *****************************************************************************************************************/
395
ARM_USBD_SignalEndpointEvent(uint8_t ep_addr,uint32_t ep_event)396 void ARM_USBD_SignalEndpointEvent (uint8_t ep_addr, uint32_t ep_event) {
397 // function body
398 }
399 /**
400 \fn void ARM_USBD_SignalEndpointEvent (uint8_t ep_addr, uint32_t event)
401 \details
402 The function \b ARM_USBD_SignalEndpointEvent is a callback function registered by the function \ref ARM_USBD_Initialize.
403
404 The argument \a ep_addr specifies the endpoint. \n
405 The parameter \em event indicates one or more events that occurred during driver operation.
406 Each event is encoded in a separate bit and therefore it is possible to signal multiple events within the same call.
407
408 The following events can be generated:
409
410 Event | Bit | Description
411 :----------------------------------------|----:|:-----------
412 \ref ARM_USBD_EVENT_SETUP | 0 | Occurs when SETUP packet is received over Control Endpoint.
413 \ref ARM_USBD_EVENT_OUT | 1 | Occurs when data is received over OUT Endpoint.
414 \ref ARM_USBD_EVENT_IN | 2 | Occurs when data is sent over IN Endpoint.
415 *****************************************************************************************************************/
416
417 /**
418 @}
419 */
420 // End USBD Interface
421
