4 * \brief SAM USB Driver
6 * Copyright (C) 2014-2016 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>
46 #ifndef USB_H_INCLUDED
47 #define USB_H_INCLUDED
54 * \defgroup asfdoc_sam0_usb_group SAM Universal Serial Bus (USB)
56 * The Universal Serial Bus (USB) module complies with the USB 2.1 specification.
58 * The following peripherals are used by this module:
59 * - USB (Universal Serial Bus)
61 * The following devices can use this module:
62 * - Atmel | SMART SAM D51
64 * The USB module covers following mode:
72 * The USB module covers following speed:
74 * - USB High Speed (480Mbit/s)
76 * - USB Full Speed (12Mbit/s)
78 * - USB Low Speed (1.5Mbit/s)
82 * The USB module supports Link Power Management (LPM-L1) protocol.
85 * USB support needs whole set of enumeration process, to make the device
86 * recognizable and usable. The USB driver is designed to interface to the
87 * USB Stack in Atmel Software Framework (ASF).
90 * \section asfdoc_sam0_usb_device USB Device Mode
91 * The ASF USB Device Stack has defined the USB Device Driver (UDD) interface,
92 * to support USB device operations. The USB module device driver complies with
93 * this interface, so that the USB Device Stack can work based on the
96 * Refer to <a href="http://www.atmel.com/images/doc8360.pdf">
97 * "ASF - USB Device Stack"</a> for more details.
101 * \section adfdoc_sam0_usb_host USB Host Mode
102 * The ASF USB Host Stack has defined the USB Host Driver (UHD) interface,
103 * to support USB host operations. The USB module host driver complies with
104 * this interface, so that the USB Host Stack can work based on the USB module.
106 * Refer to <a href="http://www.atmel.com/images/doc8486.pdf">
107 * "ASF - USB Host Stack"</a> for more details.
111 /** Enum for the speed status for the USB module */
117 /** Enum for the possible callback types for the USB in host module */
118 enum usb_host_callback {
119 USB_HOST_CALLBACK_SOF,
120 USB_HOST_CALLBACK_RESET,
121 USB_HOST_CALLBACK_WAKEUP,
122 USB_HOST_CALLBACK_DNRSM,
123 USB_HOST_CALLBACK_UPRSM,
124 USB_HOST_CALLBACK_RAMACER,
125 USB_HOST_CALLBACK_CONNECT,
126 USB_HOST_CALLBACK_DISCONNECT,
130 /** Enum for the possible callback types for the USB pipe in host module */
131 enum usb_host_pipe_callback {
132 USB_HOST_PIPE_CALLBACK_TRANSFER_COMPLETE,
133 USB_HOST_PIPE_CALLBACK_ERROR,
134 USB_HOST_PIPE_CALLBACK_SETUP,
135 USB_HOST_PIPE_CALLBACK_STALL,
136 USB_HOST_PIPE_CALLBACK_N,
140 * \brief Host pipe types.
142 enum usb_host_pipe_type {
143 USB_HOST_PIPE_TYPE_DISABLE,
144 USB_HOST_PIPE_TYPE_CONTROL,
145 USB_HOST_PIPE_TYPE_ISO,
146 USB_HOST_PIPE_TYPE_BULK,
147 USB_HOST_PIPE_TYPE_INTERRUPT,
148 USB_HOST_PIPE_TYPE_EXTENDED,
152 * \brief Host pipe token types.
154 enum usb_host_pipe_token {
155 USB_HOST_PIPE_TOKEN_SETUP,
156 USB_HOST_PIPE_TOKEN_IN,
157 USB_HOST_PIPE_TOKEN_OUT,
161 * \brief Enumeration for the possible callback types for the USB in device module
163 enum usb_device_callback {
164 USB_DEVICE_CALLBACK_SOF,
165 USB_DEVICE_CALLBACK_RESET,
166 USB_DEVICE_CALLBACK_WAKEUP,
167 USB_DEVICE_CALLBACK_RAMACER,
168 USB_DEVICE_CALLBACK_SUSPEND,
169 USB_DEVICE_CALLBACK_LPMNYET,
170 USB_DEVICE_CALLBACK_LPMSUSP,
171 USB_DEVICE_CALLBACK_N,
175 * \brief Enumeration for the possible callback types for the USB endpoint in device module
177 enum usb_device_endpoint_callback {
178 USB_DEVICE_ENDPOINT_CALLBACK_TRCPT,
179 USB_DEVICE_ENDPOINT_CALLBACK_TRFAIL,
180 USB_DEVICE_ENDPOINT_CALLBACK_RXSTP,
181 USB_DEVICE_ENDPOINT_CALLBACK_STALL,
182 USB_DEVICE_EP_CALLBACK_N,
186 * \brief Device Endpoint types.
188 enum usb_device_endpoint_type {
189 USB_DEVICE_ENDPOINT_TYPE_DISABLE,
190 USB_DEVICE_ENDPOINT_TYPE_CONTROL,
191 USB_DEVICE_ENDPOINT_TYPE_ISOCHRONOUS,
192 USB_DEVICE_ENDPOINT_TYPE_BULK,
193 USB_DEVICE_ENDPOINT_TYPE_INTERRUPT,
197 * \brief Endpoint Size
199 enum usb_endpoint_size {
201 USB_ENDPOINT_16_BYTE,
202 USB_ENDPOINT_32_BYTE,
203 USB_ENDPOINT_64_BYTE,
204 USB_ENDPOINT_128_BYTE,
205 USB_ENDPOINT_256_BYTE,
206 USB_ENDPOINT_512_BYTE,
207 USB_ENDPOINT_1023_BYTE,
211 * \brief Link Power Management Handshake.
213 enum usb_device_lpm_mode {
214 USB_DEVICE_LPM_NOT_SUPPORT,
220 * \brief Module structure
225 * \name Host Callback Functions Types
228 typedef void (*usb_host_callback_t)(struct usb_module *module_inst);
229 typedef void (*usb_host_pipe_callback_t)(struct usb_module *module_inst, void *);
233 * \name Device Callback Functions Types
236 typedef void (*usb_device_callback_t)(struct usb_module *module_inst, void* pointer);
237 typedef void (*usb_device_endpoint_callback_t)(struct usb_module *module_inst, void* pointer);
240 /** USB configurations */
242 /** \c true for host, \c false for device. */
243 bool select_host_mode;
244 /** When \c true the module is enabled during standby. */
246 /** Generic Clock Generator source channel. */
247 // enum gclk_generator source_generator;
248 uint8_t source_generator;
250 //enum usb_speed speed_mode;
255 * \brief USB software module instance structure.
257 * USB software module instance structure, used to retain software state
258 * information of an associated hardware module instance.
262 /** Hardware module pointer of the associated USB peripheral. */
265 /** Array to store device related callback functions */
266 usb_device_callback_t device_callback[USB_DEVICE_CALLBACK_N];
267 usb_device_endpoint_callback_t device_endpoint_callback[USB_EPT_NUM][USB_DEVICE_EP_CALLBACK_N];
268 /** Bit mask for device callbacks registered */
269 uint16_t device_registered_callback_mask;
270 /** Bit mask for device callbacks enabled */
271 uint16_t device_enabled_callback_mask;
272 /** Bit mask for device endpoint callbacks registered */
273 uint8_t device_endpoint_registered_callback_mask[USB_EPT_NUM];
274 /** Bit mask for device endpoint callbacks enabled */
275 uint8_t device_endpoint_enabled_callback_mask[USB_EPT_NUM];
278 /** USB device endpoint configurations */
279 struct usb_device_endpoint_config {
280 /** device address */
283 enum usb_endpoint_size ep_size;
284 /** automatic zero length packet mode, \c true to enable */
286 /** type of endpoint with Bank */
287 enum usb_device_endpoint_type ep_type;
290 /** USB device endpoint callback status parameter structure */
291 struct usb_endpoint_callback_parameter {
292 uint16_t received_bytes;
294 uint16_t out_buffer_size;
295 uint8_t endpoint_address;
298 void usb_enable(struct usb_module *module_inst);
299 void usb_disable(struct usb_module *module_inst);
302 * \brief Get the status of USB module's state machine
304 * \param module_inst Pointer to USB module instance
306 static inline uint8_t usb_get_state_machine_status(struct usb_module *module_inst)
308 /* Sanity check arguments */
310 Assert(module_inst->hw);
312 return module_inst->hw->DEVICE.FSMSTATUS.reg;
315 void usb_get_config_defaults(struct usb_config *module_config);
316 enum status_code usb_init(struct usb_module *module_inst, Usb *const hw,
317 struct usb_config *module_config);
320 * \brief Attach USB device to the bus
322 * \param module_inst Pointer to USB device module instance
324 static inline void usb_device_attach(struct usb_module *module_inst)
326 module_inst->hw->DEVICE.CTRLB.reg &= ~USB_DEVICE_CTRLB_DETACH;
330 * \brief Detach USB device from the bus
332 * \param module_inst Pointer to USB device module instance
334 static inline void usb_device_detach(struct usb_module *module_inst)
336 module_inst->hw->DEVICE.CTRLB.reg |= USB_DEVICE_CTRLB_DETACH;
340 * \brief Get the speed mode of USB device
342 * \param module_inst Pointer to USB device module instance
343 * \return USB Speed mode (\ref usb_speed).
345 static inline enum usb_speed usb_device_get_speed(struct usb_module *module_inst)
347 if (!(module_inst->hw->DEVICE.STATUS.reg & USB_DEVICE_STATUS_SPEED_Msk)) {
348 return USB_SPEED_FULL;
350 return USB_SPEED_LOW;
355 * \brief Get the address of USB device
357 * \param module_inst Pointer to USB device module instance
358 * \return USB device address value.
360 static inline uint8_t usb_device_get_address(struct usb_module *module_inst)
362 return ((uint8_t)(module_inst->hw->DEVICE.DADD.bit.DADD));
366 * \brief Set the speed mode of USB device
368 * \param module_inst Pointer to USB device module instance
369 * \param address USB device address value
371 static inline void usb_device_set_address(struct usb_module *module_inst, uint8_t address)
373 module_inst->hw->DEVICE.DADD.reg = USB_DEVICE_DADD_ADDEN | address;
377 * \brief Get the frame number of USB device
379 * \param module_inst Pointer to USB device module instance
380 * \return USB device frame number value.
382 static inline uint16_t usb_device_get_frame_number(struct usb_module *module_inst)
384 return ((uint16_t)(module_inst->hw->DEVICE.FNUM.bit.FNUM));
388 * \brief Get the micro-frame number of USB device
390 * \param module_inst Pointer to USB device module instance
391 * \return USB device micro-frame number value.
393 static inline uint16_t usb_device_get_micro_frame_number(struct usb_module *module_inst)
395 return ((uint16_t)(module_inst->hw->DEVICE.FNUM.reg));
399 * \brief USB device send the resume wakeup
401 * \param module_inst Pointer to USB device module instance
403 static inline void usb_device_send_remote_wake_up(struct usb_module *module_inst)
405 module_inst->hw->DEVICE.CTRLB.reg |= USB_DEVICE_CTRLB_UPRSM;
409 * \brief USB device set the LPM mode
411 * \param module_inst Pointer to USB device module instance
412 * \param lpm_mode LPM mode
414 static inline void usb_device_set_lpm_mode(struct usb_module *module_inst,
415 enum usb_device_lpm_mode lpm_mode)
417 module_inst->hw->DEVICE.CTRLB.bit.LPMHDSK = lpm_mode;
421 * \name USB Device Callback Management
424 enum status_code usb_device_register_callback(struct usb_module *module_inst,
425 enum usb_device_callback callback_type,
426 usb_device_callback_t callback_func);
427 enum status_code usb_device_unregister_callback(struct usb_module *module_inst,
428 enum usb_device_callback callback_type);
429 enum status_code usb_device_enable_callback(struct usb_module *module_inst,
430 enum usb_device_callback callback_type);
431 enum status_code usb_device_disable_callback(struct usb_module *module_inst,
432 enum usb_device_callback callback_type);
436 * \name USB Device Endpoint Configuration
439 void usb_device_endpoint_get_config_defaults(struct usb_device_endpoint_config *ep_config);
440 enum status_code usb_device_endpoint_set_config(struct usb_module *module_inst,
441 struct usb_device_endpoint_config *ep_config);
442 bool usb_device_endpoint_is_configured(struct usb_module *module_inst, uint8_t ep);
446 * \name USB Device Endpoint Callback Management
449 enum status_code usb_device_endpoint_register_callback(
450 struct usb_module *module_inst, uint8_t ep_num,
451 enum usb_device_endpoint_callback callback_type,
452 usb_device_endpoint_callback_t callback_func);
453 enum status_code usb_device_endpoint_unregister_callback(
454 struct usb_module *module_inst, uint8_t ep_num,
455 enum usb_device_endpoint_callback callback_type);
456 enum status_code usb_device_endpoint_enable_callback(
457 struct usb_module *module_inst, uint8_t ep,
458 enum usb_device_endpoint_callback callback_type);
459 enum status_code usb_device_endpoint_disable_callback(
460 struct usb_module *module_inst, uint8_t ep,
461 enum usb_device_endpoint_callback callback_type);
465 * \name USB Device Endpoint Job Management
468 enum status_code usb_device_endpoint_write_buffer_job(struct usb_module *module_inst,uint8_t ep_num,
469 uint8_t* pbuf, uint32_t buf_size);
470 enum status_code usb_device_endpoint_read_buffer_job(struct usb_module *module_inst,uint8_t ep_num,
471 uint8_t* pbuf, uint32_t buf_size);
472 enum status_code usb_device_endpoint_setup_buffer_job(struct usb_module *module_inst,
474 void usb_device_endpoint_abort_job(struct usb_module *module_inst, uint8_t ep);
478 * \name USB Device Endpoint Operations
482 bool usb_device_endpoint_is_halted(struct usb_module *module_inst, uint8_t ep);
483 void usb_device_endpoint_set_halt(struct usb_module *module_inst, uint8_t ep);
484 void usb_device_endpoint_clear_halt(struct usb_module *module_inst, uint8_t ep);
492 #endif /* USB_H_INCLUDED */