tmk_core/protocol/arm_atsam/usb/udd.h

   1 /**
   2  * \file
   3  *
   4  * \brief Common API for USB Device Drivers (UDD)
   5  *
   6  * Copyright (c) 2009-2015 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
  47 #ifndef _UDD_H_
  48 #define _UDD_H_
  49
  50 #include "usb_protocol.h"
  51 #include "udc_desc.h"
  52
  53 #ifdef __cplusplus
  54 extern "C" {
  55 #endif
  56
  57 /**
  58  * \ingroup usb_device_group
  59  * \defgroup udd_group USB Device Driver (UDD)
  60  *
  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.
  64  *
  65  * @{
  66  */
  67
  68 //! \brief Endpoint identifier
  69 typedef uint8_t udd_ep_id_t;
  70
  71 //! \brief Endpoint transfer status
  72 //! Returned in parameters of callback register via udd_ep_run routine.
  73 typedef enum {
  74     UDD_EP_TRANSFER_OK = 0,
  75     UDD_EP_TRANSFER_ABORT = 1,
  76 } udd_ep_status_t;
  77
  78 /**
  79  * \brief Global variable to give and record information of the setup request management
  80  *
  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.
  83  */
  84 typedef struct {
  85     //! Data received in USB SETUP packet
  86     //! Note: The swap of "req.wValues" from uin16_t to le16_t is done by UDD.
  87     usb_setup_req_t req;
  88
  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)
  91     uint8_t *payload;
  92
  93     //! Size of buffer to send or fill, and content the number of byte transfered
  94     uint16_t payload_size;
  95
  96     //! Callback called after reception of ZLP from setup request
  97     void (*callback) (void);
  98
  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;
 104
 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))
 108
 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))
 112
 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)
 116
 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)
 120
 121 /**
 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.
 125  */
 126 typedef void (*udd_callback_halt_cleared_t) (void);
 127
 128 /**
 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,...).
 132  *
 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
 136  */
 137 typedef void (*udd_callback_trans_t) (udd_ep_status_t status,
 138         iram_size_t nb_transfered, udd_ep_id_t ep);
 139
 140 /**
 141  * \brief Authorizes the VBUS event
 142  *
 143  * \return true, if the VBUS monitoring is possible.
 144  */
 145 bool udd_include_vbus_monitoring(void);
 146
 147 /**
 148  * \brief Enables the USB Device mode
 149  */
 150 void udd_enable(void);
 151
 152 /**
 153  * \brief Disables the USB Device mode
 154  */
 155 void udd_disable(void);
 156
 157 /**
 158  * \brief Attach device to the bus when possible
 159  *
 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.
 163  */
 164 void udd_attach(void);
 165
 166 /**
 167  * \brief Detaches the device from the bus
 168  *
 169  * The driver must remove pull-up on USB line D- or D+.
 170  */
 171 void udd_detach(void);
 172
 173 /**
 174  * \brief Test whether the USB Device Controller is running at high
 175  * speed or not.
 176  *
 177  * \return \c true if the Device is running at high speed mode, otherwise \c false.
 178  */
 179 bool udd_is_high_speed(void);
 180
 181 /**
 182  * \brief Changes the USB address of device
 183  *
 184  * \param address    New USB address
 185  */
 186 void udd_set_address(uint8_t address);
 187
 188 /**
 189  * \brief Returns the USB address of device
 190  *
 191  * \return USB address
 192  */
 193 uint8_t udd_getaddress(void);
 194
 195 /**
 196  * \brief Returns the current start of frame number
 197  *
 198  * \return current start of frame number.
 199  */
 200 uint16_t udd_get_frame_number(void);
 201
 202 /**
 203  * \brief Returns the current micro start of frame number
 204  *
 205  * \return current micro start of frame number required in high speed mode.
 206  */
 207 uint16_t udd_get_micro_frame_number(void);
 208
 209 /*! \brief The USB driver sends a resume signal called Upstream Resume
 210  */
 211 void udd_send_remotewakeup(void);
 212
 213 /**
 214  * \brief Load setup payload
 215  *
 216  * \param payload       Pointer on payload
 217  * \param payload_size  Size of payload
 218  */
 219 void udd_set_setup_payload( uint8_t *payload, uint16_t payload_size );
 220
 221
 222 /**
 223  * \name Endpoint Management
 224  *
 225  * The following functions allow drivers to create and remove
 226  * endpoints, as well as set, clear and query their "halted" and
 227  * "wedged" states.
 228  */
 229 //@{
 230
 231 #if (USB_DEVICE_MAX_EP != 0)
 232
 233 /**
 234  * \brief Configures and enables an endpoint
 235  *
 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
 239  *
 240  * \return \c 1 if the endpoint is enabled, otherwise \c 0.
 241  */
 242 bool udd_ep_alloc(udd_ep_id_t ep, uint8_t bmAttributes,
 243         uint16_t MaxEndpointSize);
 244
 245 /**
 246  * \brief Disables an endpoint
 247  *
 248  * \param ep               Endpoint number including direction (USB_EP_DIR_IN/USB_EP_DIR_OUT).
 249  */
 250 void udd_ep_free(udd_ep_id_t ep);
 251
 252 /**
 253  * \brief Check if the endpoint \a ep is halted.
 254  *
 255  * \param ep The ID of the endpoint to check.
 256  *
 257  * \return \c 1 if \a ep is halted, otherwise \c 0.
 258  */
 259 bool udd_ep_is_halted(udd_ep_id_t ep);
 260
 261 /**
 262  * \brief Set the halted state of the endpoint \a ep
 263  *
 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.
 267  *
 268  * \param ep The ID of the endpoint to be halted
 269  *
 270  * \return \c 1 if \a ep is halted, otherwise \c 0.
 271  */
 272 bool udd_ep_set_halt(udd_ep_id_t ep);
 273
 274 /**
 275  * \brief Clear the halted state of the endpoint \a ep
 276  *
 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.
 280  *
 281  * \param ep The ID of the endpoint to be un-halted
 282  *
 283  * \return \c 1 if function was successfully done, otherwise \c 0.
 284  */
 285 bool udd_ep_clear_halt(udd_ep_id_t ep);
 286
 287 /**
 288  * \brief Registers a callback to call when endpoint halt is cleared
 289  *
 290  * \param ep            The ID of the endpoint to use
 291  * \param callback      NULL or function to call when endpoint halt is cleared
 292  *
 293  * \warning if the endpoint is not halted then the \a callback is called immediately.
 294  *
 295  * \return \c 1 if the register is accepted, otherwise \c 0.
 296  */
 297 bool udd_ep_wait_stall_clear(udd_ep_id_t ep,
 298         udd_callback_halt_cleared_t callback);
 299
 300 /**
 301  * \brief Allows to receive or send data on an endpoint
 302  *
 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.
 308  *
 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
 315  *
 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).
 321  *
 322  * \return \c 1 if function was successfully done, otherwise \c 0.
 323  */
 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);
 327 /**
 328  * \brief Aborts transfer on going on endpoint
 329  *
 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.
 333  *
 334  * \param ep            Endpoint to abort
 335  */
 336 void udd_ep_abort(udd_ep_id_t ep);
 337
 338 #endif
 339
 340 //@}
 341
 342
 343 /**
 344  * \name High speed test mode management
 345  *
 346  * The following functions allow the device to jump to a specific test mode required in high speed mode.
 347  */
 348 //@{
 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);
 353 //@}
 354
 355
 356 /**
 357  * \name UDC callbacks to provide for UDD
 358  *
 359  * The following callbacks are used by UDD.
 360  */
 361 //@{
 362
 363 /**
 364  * \brief Decodes and manages a setup request
 365  *
 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.
 370  *
 371  * \return \c 1 if the request is accepted, otherwise \c 0.
 372  */
 373 extern bool udc_process_setup(void);
 374
 375 /**
 376  * \brief Reset the UDC
 377  *
 378  * The UDC must reset all configuration.
 379  */
 380 extern void udc_reset(void);
 381
 382 /**
 383  * \brief To signal that a SOF is occurred
 384  *
 385  * The UDC must send the signal to all UDIs enabled
 386  */
 387 extern void udc_sof_notify(void);
 388
 389 //@}
 390
 391 //@}
 392
 393 #ifdef __cplusplus
 394 }
 395 #endif
 396 #endif // _UDD_H_