4 * \brief Common API for USB Device Drivers (UDD)
6 * Copyright (c) 2009-2015 Atmel Corporation. All rights reserved.
12 * Redistribution and use in source and binary forms, with or without
13 * modification, are permitted provided that the following conditions are met:
15 * 1. Redistributions of source code must retain the above copyright notice,
16 * this list of conditions and the following disclaimer.
18 * 2. Redistributions in binary form must reproduce the above copyright notice,
19 * this list of conditions and the following disclaimer in the documentation
20 * and/or other materials provided with the distribution.
22 * 3. The name of Atmel may not be used to endorse or promote products derived
23 * from this software without specific prior written permission.
25 * 4. This software may only be redistributed and used in connection with an
26 * Atmel microcontroller product.
28 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
29 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
30 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
31 * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
32 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
33 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
34 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
35 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
36 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
37 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
38 * POSSIBILITY OF SUCH DAMAGE.
44 * Support and FAQ: visit <a href="http://www.atmel.com/design-support/">Atmel Support</a>
50 #include "usb_protocol.h"
58 * \ingroup usb_device_group
59 * \defgroup udd_group USB Device Driver (UDD)
61 * The UDD driver provides a low-level abstraction of the device
62 * controller hardware. Most events coming from the hardware such as
63 * interrupts, which may cause the UDD to call into the UDC and UDI.
68 //! \brief Endpoint identifier
69 typedef uint8_t udd_ep_id_t;
71 //! \brief Endpoint transfer status
72 //! Returned in parameters of callback register via udd_ep_run routine.
74 UDD_EP_TRANSFER_OK = 0,
75 UDD_EP_TRANSFER_ABORT = 1,
79 * \brief Global variable to give and record information of the setup request management
81 * This global variable allows to decode and response a setup request.
82 * It can be updated by udc_process_setup() from UDC or *setup() from UDIs.
85 //! Data received in USB SETUP packet
86 //! Note: The swap of "req.wValues" from uin16_t to le16_t is done by UDD.
89 //! Point to buffer to send or fill with data following SETUP packet
90 //! This buffer must be word align for DATA IN phase (use prefix COMPILER_WORD_ALIGNED for buffer)
93 //! Size of buffer to send or fill, and content the number of byte transfered
94 uint16_t payload_size;
96 //! Callback called after reception of ZLP from setup request
97 void (*callback) (void);
99 //! Callback called when the buffer given (.payload) is full or empty.
100 //! This one return false to abort data transfer, or true with a new buffer in .payload.
101 bool(*over_under_run) (void);
102 } udd_ctrl_request_t;
103 extern udd_ctrl_request_t udd_g_ctrlreq;
105 //! Return true if the setup request \a udd_g_ctrlreq indicates IN data transfer
106 #define Udd_setup_is_in() \
107 (USB_REQ_DIR_IN == (udd_g_ctrlreq.req.bmRequestType & USB_REQ_DIR_MASK))
109 //! Return true if the setup request \a udd_g_ctrlreq indicates OUT data transfer
110 #define Udd_setup_is_out() \
111 (USB_REQ_DIR_OUT == (udd_g_ctrlreq.req.bmRequestType & USB_REQ_DIR_MASK))
113 //! Return the type of the SETUP request \a udd_g_ctrlreq. \see usb_reqtype.
114 #define Udd_setup_type() \
115 (udd_g_ctrlreq.req.bmRequestType & USB_REQ_TYPE_MASK)
117 //! Return the recipient of the SETUP request \a udd_g_ctrlreq. \see usb_recipient
118 #define Udd_setup_recipient() \
119 (udd_g_ctrlreq.req.bmRequestType & USB_REQ_RECIP_MASK)
122 * \brief End of halt callback function type.
123 * Registered by routine udd_ep_wait_stall_clear()
124 * Callback called when endpoint stall is cleared.
126 typedef void (*udd_callback_halt_cleared_t) (void);
129 * \brief End of transfer callback function type.
130 * Registered by routine udd_ep_run()
131 * Callback called by USB interrupt after data transfer or abort (reset,...).
133 * \param status UDD_EP_TRANSFER_OK, if transfer is complete
134 * \param status UDD_EP_TRANSFER_ABORT, if transfer is aborted
135 * \param n number of data transfered
137 typedef void (*udd_callback_trans_t) (udd_ep_status_t status,
138 iram_size_t nb_transfered, udd_ep_id_t ep);
141 * \brief Authorizes the VBUS event
143 * \return true, if the VBUS monitoring is possible.
145 bool udd_include_vbus_monitoring(void);
148 * \brief Enables the USB Device mode
150 void udd_enable(void);
153 * \brief Disables the USB Device mode
155 void udd_disable(void);
158 * \brief Attach device to the bus when possible
160 * \warning If a VBus control is included in driver,
161 * then it will attach device when an acceptable Vbus
162 * level from the host is detected.
164 void udd_attach(void);
167 * \brief Detaches the device from the bus
169 * The driver must remove pull-up on USB line D- or D+.
171 void udd_detach(void);
174 * \brief Test whether the USB Device Controller is running at high
177 * \return \c true if the Device is running at high speed mode, otherwise \c false.
179 bool udd_is_high_speed(void);
182 * \brief Changes the USB address of device
184 * \param address New USB address
186 void udd_set_address(uint8_t address);
189 * \brief Returns the USB address of device
191 * \return USB address
193 uint8_t udd_getaddress(void);
196 * \brief Returns the current start of frame number
198 * \return current start of frame number.
200 uint16_t udd_get_frame_number(void);
203 * \brief Returns the current micro start of frame number
205 * \return current micro start of frame number required in high speed mode.
207 uint16_t udd_get_micro_frame_number(void);
209 /*! \brief The USB driver sends a resume signal called Upstream Resume
211 void udd_send_remotewakeup(void);
214 * \brief Load setup payload
216 * \param payload Pointer on payload
217 * \param payload_size Size of payload
219 void udd_set_setup_payload( uint8_t *payload, uint16_t payload_size );
223 * \name Endpoint Management
225 * The following functions allow drivers to create and remove
226 * endpoints, as well as set, clear and query their "halted" and
231 #if (USB_DEVICE_MAX_EP != 0)
234 * \brief Configures and enables an endpoint
236 * \param ep Endpoint number including direction (USB_EP_DIR_IN/USB_EP_DIR_OUT).
237 * \param bmAttributes Attributes of endpoint declared in the descriptor.
238 * \param MaxEndpointSize Endpoint maximum size
240 * \return \c 1 if the endpoint is enabled, otherwise \c 0.
242 bool udd_ep_alloc(udd_ep_id_t ep, uint8_t bmAttributes,
243 uint16_t MaxEndpointSize);
246 * \brief Disables an endpoint
248 * \param ep Endpoint number including direction (USB_EP_DIR_IN/USB_EP_DIR_OUT).
250 void udd_ep_free(udd_ep_id_t ep);
253 * \brief Check if the endpoint \a ep is halted.
255 * \param ep The ID of the endpoint to check.
257 * \return \c 1 if \a ep is halted, otherwise \c 0.
259 bool udd_ep_is_halted(udd_ep_id_t ep);
262 * \brief Set the halted state of the endpoint \a ep
264 * After calling this function, any transaction on \a ep will result
265 * in a STALL handshake being sent. Any pending transactions will be
266 * performed first, however.
268 * \param ep The ID of the endpoint to be halted
270 * \return \c 1 if \a ep is halted, otherwise \c 0.
272 bool udd_ep_set_halt(udd_ep_id_t ep);
275 * \brief Clear the halted state of the endpoint \a ep
277 * After calling this function, any transaction on \a ep will
278 * be handled normally, i.e. a STALL handshake will not be sent, and
279 * the data toggle sequence will start at DATA0.
281 * \param ep The ID of the endpoint to be un-halted
283 * \return \c 1 if function was successfully done, otherwise \c 0.
285 bool udd_ep_clear_halt(udd_ep_id_t ep);
288 * \brief Registers a callback to call when endpoint halt is cleared
290 * \param ep The ID of the endpoint to use
291 * \param callback NULL or function to call when endpoint halt is cleared
293 * \warning if the endpoint is not halted then the \a callback is called immediately.
295 * \return \c 1 if the register is accepted, otherwise \c 0.
297 bool udd_ep_wait_stall_clear(udd_ep_id_t ep,
298 udd_callback_halt_cleared_t callback);
301 * \brief Allows to receive or send data on an endpoint
303 * The driver uses a specific DMA USB to transfer data
304 * from internal RAM to endpoint, if this one is available.
305 * When the transfer is finished or aborted (stall, reset, ...), the \a callback is called.
306 * The \a callback returns the transfer status and eventually the number of byte transfered.
307 * Note: The control endpoint is not authorized.
309 * \param ep The ID of the endpoint to use
310 * \param b_shortpacket Enabled automatic short packet
311 * \param buf Buffer on Internal RAM to send or fill.
312 * It must be align, then use COMPILER_WORD_ALIGNED.
313 * \param buf_size Buffer size to send or fill
314 * \param callback NULL or function to call at the end of transfer
316 * \warning About \a b_shortpacket, for IN endpoint it means that a short packet
317 * (or a Zero Length Packet) will be sent to the USB line to properly close the usb
318 * transfer at the end of the data transfer.
319 * For Bulk and Interrupt OUT endpoint, it will automatically stop the transfer
320 * at the end of the data transfer (received short packet).
322 * \return \c 1 if function was successfully done, otherwise \c 0.
324 bool udd_ep_run(udd_ep_id_t ep, bool b_shortpacket,
325 uint8_t *buf, iram_size_t buf_size,
326 udd_callback_trans_t callback);
328 * \brief Aborts transfer on going on endpoint
330 * If a transfer is on going, then it is stopped and
331 * the callback registered is called to signal the end of transfer.
332 * Note: The control endpoint is not authorized.
334 * \param ep Endpoint to abort
336 void udd_ep_abort(udd_ep_id_t ep);
344 * \name High speed test mode management
346 * The following functions allow the device to jump to a specific test mode required in high speed mode.
349 void udd_test_mode_j(void);
350 void udd_test_mode_k(void);
351 void udd_test_mode_se0_nak(void);
352 void udd_test_mode_packet(void);
357 * \name UDC callbacks to provide for UDD
359 * The following callbacks are used by UDD.
364 * \brief Decodes and manages a setup request
366 * The driver call it when a SETUP packet is received.
367 * The \c udd_g_ctrlreq contains the data of SETUP packet.
368 * If this callback accepts the setup request then it must
369 * return \c 1 and eventually update \c udd_g_ctrlreq to send or receive data.
371 * \return \c 1 if the request is accepted, otherwise \c 0.
373 extern bool udc_process_setup(void);
376 * \brief Reset the UDC
378 * The UDC must reset all configuration.
380 extern void udc_reset(void);
383 * \brief To signal that a SOF is occurred
385 * The UDC must send the signal to all UDIs enabled
387 extern void udc_sof_notify(void);