tmk_core/protocol/arm_atsam/usb/usb.h

   1 /**
   2  * \file
   3  *
   4  * \brief SAM USB Driver
   5  *
   6  * Copyright (C) 2014-2016 Atmel Corporation. All rights reserved.
   7  *
   8  * \asf_license_start
   9  *
  10  * \page License
  11  *
  12  * Redistribution and use in source and binary forms, with or without
  13  * modification, are permitted provided that the following conditions are met:
  14  *
  15  * 1. Redistributions of source code must retain the above copyright notice,
  16  *    this list of conditions and the following disclaimer.
  17  *
  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.
  21  *
  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.
  24  *
  25  * 4. This software may only be redistributed and used in connection with an
  26  *    Atmel microcontroller product.
  27  *
  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.
  39  *
  40  * \asf_license_stop
  41  *
  42  */
  43 /*
  44  * Support and FAQ: visit <a href="http://www.atmel.com/design-support/">Atmel Support</a>
  45  */
  46 #ifndef USB_H_INCLUDED
  47 #define USB_H_INCLUDED
  48
  49 #ifdef __cplusplus
  50 extern "C" {
  51 #endif
  52
  53 /**
  54  * \defgroup asfdoc_sam0_usb_group SAM Universal Serial Bus (USB)
  55  *
  56  * The Universal Serial Bus (USB) module complies with the USB 2.1 specification.
  57  *
  58  * The following peripherals are used by this module:
  59  *  - USB (Universal Serial Bus)
  60  *
  61  * The following devices can use this module:
  62  *  - Atmel | SMART SAM D51
  63  *
  64  * The USB module covers following mode:
  65  * \if USB_DEVICE_MODE
  66  *  - USB Device Mode
  67  * \endif
  68  * \if USB_HOST_MODE
  69  *  - USB Host Mode
  70  * \endif
  71  *
  72  * The USB module covers following speed:
  73  * \if USB_HS_MODE
  74  *  - USB High Speed (480Mbit/s)
  75  * \endif
  76  *  - USB Full Speed (12Mbit/s)
  77  * \if USB_LS_MODE
  78  *  - USB Low Speed (1.5Mbit/s)
  79  * \endif
  80  *
  81  * \if USB_LPM_MODE
  82  * The USB module supports Link Power Management (LPM-L1) protocol.
  83  * \endif
  84  *
  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).
  88  *
  89  * \if USB_DEVICE_MODE
  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
  94  * USB module.
  95  *
  96  * Refer to <a href="http://www.atmel.com/images/doc8360.pdf">
  97  * "ASF - USB Device Stack"</a> for more details.
  98  * \endif
  99  *
 100  * \if USB_HOST_MODE
 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.
 105  *
 106  * Refer to <a href="http://www.atmel.com/images/doc8486.pdf">
 107  * "ASF - USB Host Stack"</a> for more details.
 108  * \endif
 109  */
 110
 111 /** Enum for the speed status for the USB module */
 112 enum usb_speed {
 113     USB_SPEED_LOW,
 114     USB_SPEED_FULL,
 115 };
 116
 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,
 127     USB_HOST_CALLBACK_N,
 128 };
 129
 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,
 137 };
 138
 139 /**
 140  * \brief Host pipe types.
 141  */
 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,
 149 };
 150
 151 /**
 152  * \brief Host pipe token types.
 153  */
 154 enum usb_host_pipe_token {
 155     USB_HOST_PIPE_TOKEN_SETUP,
 156     USB_HOST_PIPE_TOKEN_IN,
 157     USB_HOST_PIPE_TOKEN_OUT,
 158 };
 159
 160 /**
 161  * \brief Enumeration for the possible callback types for the USB in device module
 162  */
 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,
 172 };
 173
 174 /**
 175  * \brief Enumeration for the possible callback types for the USB endpoint in device module
 176  */
 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,
 183 };
 184
 185 /**
 186  * \brief Device Endpoint types.
 187  */
 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,
 194 };
 195
 196 /**
 197  * \brief Endpoint Size
 198  */
 199 enum usb_endpoint_size {
 200     USB_ENDPOINT_8_BYTE,
 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,
 208 };
 209
 210 /**
 211  * \brief Link Power Management Handshake.
 212  */
 213 enum usb_device_lpm_mode {
 214     USB_DEVICE_LPM_NOT_SUPPORT,
 215     USB_DEVICE_LPM_ACK,
 216     USB_DEVICE_LPM_NYET,
 217 };
 218
 219 /**
 220  * \brief Module structure
 221  */
 222 struct usb_module;
 223
 224 /**
 225  * \name Host Callback Functions Types
 226  * @{
 227  */
 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 *);
 230 /** @} */
 231
 232 /**
 233  * \name Device Callback Functions Types
 234  * @{
 235  */
 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);
 238 /** @} */
 239
 240 /** USB configurations */
 241 struct usb_config {
 242     /** \c true for host, \c false for device. */
 243     bool select_host_mode;
 244     /** When \c true the module is enabled during standby. */
 245     bool run_in_standby;
 246     /** Generic Clock Generator source channel. */
 247     // enum gclk_generator source_generator;
 248     uint8_t source_generator;
 249     /** Speed mode */
 250     //enum usb_speed speed_mode;
 251     uint8_t speed_mode;
 252 };
 253
 254 /**
 255  * \brief USB software module instance structure.
 256  *
 257  * USB software module instance structure, used to retain software state
 258  * information of an associated hardware module instance.
 259  *
 260  */
 261 struct usb_module {
 262     /** Hardware module pointer of the associated USB peripheral. */
 263     Usb *hw;
 264
 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];
 276 };
 277
 278 /** USB device endpoint configurations */
 279 struct usb_device_endpoint_config {
 280     /** device address */
 281     uint8_t ep_address;
 282     /** endpoint size */
 283     enum usb_endpoint_size ep_size;
 284     /** automatic zero length packet mode, \c true to enable */
 285     bool auto_zlp;
 286     /** type of endpoint with Bank */
 287     enum usb_device_endpoint_type ep_type;
 288 };
 289
 290 /** USB device endpoint callback status parameter structure */
 291 struct usb_endpoint_callback_parameter {
 292     uint16_t received_bytes;
 293     uint16_t sent_bytes;
 294     uint16_t out_buffer_size;
 295     uint8_t endpoint_address;
 296 };
 297
 298 void usb_enable(struct usb_module *module_inst);
 299 void usb_disable(struct usb_module *module_inst);
 300
 301 /**
 302  * \brief Get the status of USB module's state machine
 303  *
 304  * \param module_inst Pointer to USB module instance
 305  */
 306 static inline uint8_t usb_get_state_machine_status(struct usb_module *module_inst)
 307 {
 308     /* Sanity check arguments */
 309     Assert(module_inst);
 310     Assert(module_inst->hw);
 311
 312     return module_inst->hw->DEVICE.FSMSTATUS.reg;
 313 }
 314
 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);
 318
 319 /**
 320  * \brief Attach USB device to the bus
 321  *
 322  * \param module_inst Pointer to USB device module instance
 323  */
 324 static inline void usb_device_attach(struct usb_module *module_inst)
 325 {
 326     module_inst->hw->DEVICE.CTRLB.reg &= ~USB_DEVICE_CTRLB_DETACH;
 327 }
 328
 329 /**
 330  * \brief Detach USB device from the bus
 331  *
 332  * \param module_inst Pointer to USB device module instance
 333  */
 334 static inline void usb_device_detach(struct usb_module *module_inst)
 335 {
 336     module_inst->hw->DEVICE.CTRLB.reg |= USB_DEVICE_CTRLB_DETACH;
 337 }
 338
 339 /**
 340  * \brief Get the speed mode of USB device
 341  *
 342  * \param module_inst Pointer to USB device module instance
 343  * \return USB Speed mode (\ref usb_speed).
 344  */
 345 static inline enum usb_speed usb_device_get_speed(struct usb_module *module_inst)
 346 {
 347     if (!(module_inst->hw->DEVICE.STATUS.reg & USB_DEVICE_STATUS_SPEED_Msk)) {
 348         return USB_SPEED_FULL;
 349     } else {
 350         return USB_SPEED_LOW;
 351     }
 352 }
 353
 354 /**
 355  * \brief Get the address of USB device
 356  *
 357  * \param module_inst Pointer to USB device module instance
 358  * \return USB device address value.
 359  */
 360 static inline uint8_t usb_device_get_address(struct usb_module *module_inst)
 361 {
 362     return ((uint8_t)(module_inst->hw->DEVICE.DADD.bit.DADD));
 363 }
 364
 365 /**
 366  * \brief Set the speed mode of USB device
 367  *
 368  * \param module_inst Pointer to USB device module instance
 369  * \param address     USB device address value
 370  */
 371 static inline void usb_device_set_address(struct usb_module *module_inst, uint8_t address)
 372 {
 373     module_inst->hw->DEVICE.DADD.reg = USB_DEVICE_DADD_ADDEN | address;
 374 }
 375
 376 /**
 377  * \brief Get the frame number of USB device
 378  *
 379  * \param module_inst Pointer to USB device module instance
 380  * \return USB device frame number value.
 381  */
 382 static inline uint16_t usb_device_get_frame_number(struct usb_module *module_inst)
 383 {
 384     return ((uint16_t)(module_inst->hw->DEVICE.FNUM.bit.FNUM));
 385 }
 386
 387 /**
 388  * \brief Get the micro-frame number of USB device
 389  *
 390  * \param module_inst Pointer to USB device module instance
 391  * \return USB device micro-frame number value.
 392  */
 393 static inline uint16_t usb_device_get_micro_frame_number(struct usb_module *module_inst)
 394 {
 395     return ((uint16_t)(module_inst->hw->DEVICE.FNUM.reg));
 396 }
 397
 398 /**
 399  * \brief USB device send the resume wakeup
 400  *
 401  * \param module_inst Pointer to USB device module instance
 402  */
 403 static inline void usb_device_send_remote_wake_up(struct usb_module *module_inst)
 404 {
 405     module_inst->hw->DEVICE.CTRLB.reg |= USB_DEVICE_CTRLB_UPRSM;
 406 }
 407
 408 /**
 409  * \brief USB device set the LPM mode
 410  *
 411  * \param module_inst Pointer to USB device module instance
 412  * \param lpm_mode    LPM mode
 413  */
 414 static inline void usb_device_set_lpm_mode(struct usb_module *module_inst,
 415         enum usb_device_lpm_mode lpm_mode)
 416 {
 417     module_inst->hw->DEVICE.CTRLB.bit.LPMHDSK = lpm_mode;
 418 }
 419
 420 /**
 421  * \name USB Device Callback Management
 422  * @{
 423  */
 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);
 433 /** @} */
 434
 435 /**
 436  * \name USB Device Endpoint Configuration
 437  * @{
 438  */
 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);
 443 /** @} */
 444
 445 /**
 446  * \name USB Device Endpoint Callback Management
 447  * @{
 448  */
 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);
 462 /** @} */
 463
 464 /**
 465  * \name USB Device Endpoint Job Management
 466  * @{
 467  */
 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,
 473         uint8_t* pbuf);
 474 void usb_device_endpoint_abort_job(struct usb_module *module_inst, uint8_t ep);
 475 /** @} */
 476
 477 /**
 478  * \name USB Device Endpoint Operations
 479  * @{
 480  */
 481
 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);
 485
 486 /** @} */
 487
 488 #ifdef __cplusplus
 489 }
 490 #endif
 491
 492 #endif /* USB_H_INCLUDED */