Kévin Redon | 69b92d9 | 2019-01-24 16:39:20 +0100 | [diff] [blame] | 1 | /** |
| 2 | * \file |
| 3 | * |
| 4 | * \brief SAM USB device HAL |
| 5 | * |
| 6 | * Copyright (c) 2015-2018 Microchip Technology Inc. and its subsidiaries. |
| 7 | * |
| 8 | * \asf_license_start |
| 9 | * |
| 10 | * \page License |
| 11 | * |
| 12 | * Subject to your compliance with these terms, you may use Microchip |
| 13 | * software and any derivatives exclusively with Microchip products. |
| 14 | * It is your responsibility to comply with third party license terms applicable |
| 15 | * to your use of third party software (including open source software) that |
| 16 | * may accompany Microchip software. |
| 17 | * |
| 18 | * THIS SOFTWARE IS SUPPLIED BY MICROCHIP "AS IS". NO WARRANTIES, |
| 19 | * WHETHER EXPRESS, IMPLIED OR STATUTORY, APPLY TO THIS SOFTWARE, |
| 20 | * INCLUDING ANY IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, |
| 21 | * AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT WILL MICROCHIP BE |
| 22 | * LIABLE FOR ANY INDIRECT, SPECIAL, PUNITIVE, INCIDENTAL OR CONSEQUENTIAL |
| 23 | * LOSS, DAMAGE, COST OR EXPENSE OF ANY KIND WHATSOEVER RELATED TO THE |
| 24 | * SOFTWARE, HOWEVER CAUSED, EVEN IF MICROCHIP HAS BEEN ADVISED OF THE |
| 25 | * POSSIBILITY OR THE DAMAGES ARE FORESEEABLE. TO THE FULLEST EXTENT |
| 26 | * ALLOWED BY LAW, MICROCHIP'S TOTAL LIABILITY ON ALL CLAIMS IN ANY WAY |
| 27 | * RELATED TO THIS SOFTWARE WILL NOT EXCEED THE AMOUNT OF FEES, IF ANY, |
| 28 | * THAT YOU HAVE PAID DIRECTLY TO MICROCHIP FOR THIS SOFTWARE. |
| 29 | * |
| 30 | * \asf_license_stop |
| 31 | * |
| 32 | */ |
| 33 | |
| 34 | #ifndef _HAL_USB_DEVICE_H_INCLUDED |
| 35 | #define _HAL_USB_DEVICE_H_INCLUDED |
| 36 | |
| 37 | #include <hpl_usb_device.h> |
| 38 | |
| 39 | #ifdef __cplusplus |
| 40 | extern "C" { |
| 41 | #endif |
| 42 | |
| 43 | /** |
| 44 | * \addtogroup doc_driver_hal_usb_device |
| 45 | * |
| 46 | * @{ |
| 47 | */ |
| 48 | |
| 49 | /** USB device endpoint status structure. */ |
| 50 | struct usb_d_ep_status { |
| 51 | /** Endpoint address, including direction. */ |
| 52 | uint8_t ep; |
| 53 | /** Endpoint transfer status code that triggers the callback. |
| 54 | * \ref usb_xfer_code. */ |
| 55 | uint8_t code; |
| 56 | /** Endpoint error, if \c code is \ref USB_TRANS_ERROR. */ |
| 57 | uint8_t error; |
| 58 | /** Transfer state, \ref usb_ep_state. */ |
| 59 | uint8_t state; |
| 60 | /** Transfer count. */ |
| 61 | uint32_t count; |
| 62 | /** Transfer size. */ |
| 63 | uint32_t size; |
| 64 | }; |
| 65 | |
| 66 | /** Prototype function for callback that is invoked on USB device SOF. */ |
| 67 | typedef void (*usb_d_sof_cb_t)(void); |
| 68 | |
| 69 | /** Prototype function for callback that is invoked on USB device events. */ |
| 70 | typedef void (*usb_d_event_cb_t)(const enum usb_event event, const uint32_t param); |
| 71 | |
| 72 | /** USB device callbacks. */ |
| 73 | struct usb_d_callbacks { |
| 74 | /** Callback that is invoked on SOF. */ |
| 75 | usb_d_sof_cb_t sof; |
| 76 | /** Callback that is invoked on USB RESET/WAKEUP/RESUME/SUSPEND. */ |
| 77 | usb_d_event_cb_t event; |
| 78 | }; |
| 79 | |
| 80 | /** Callback that is invoked when setup packet is received. |
| 81 | * Return \c true if request has been handled, or control endpoint will |
| 82 | * stall IN/OUT transactions. |
| 83 | */ |
| 84 | typedef bool (*usb_d_ep_cb_setup_t)(const uint8_t ep, const uint8_t *req); |
| 85 | |
| 86 | /** Callback that is invoked when buffer is done without error, but last packet |
| 87 | * is full size packet without ZLP. |
| 88 | * Return \c true if more data has been requested. |
| 89 | */ |
| 90 | typedef bool (*usb_d_ep_cb_more_t)(const uint8_t ep, const uint32_t count); |
| 91 | |
| 92 | /** Callback that is invoked when all data is finished, including background |
| 93 | * transfer, or error happens. |
| 94 | * In control transfer data stage, return value is checked, |
| 95 | * return \c false if no error happens. |
| 96 | */ |
| 97 | typedef bool (*usb_d_ep_cb_xfer_t)(const uint8_t ep, const enum usb_xfer_code code, void *param); |
| 98 | |
| 99 | /** |
| 100 | * \brief Initialize the USB device driver |
| 101 | * \return Operation status. |
| 102 | * \retval 0 Success. |
| 103 | * \retval <0 Error code. |
| 104 | */ |
| 105 | int32_t usb_d_init(void); |
| 106 | |
| 107 | /** |
| 108 | * \brief Deinitialize the USB device driver |
| 109 | */ |
| 110 | void usb_d_deinit(void); |
| 111 | |
| 112 | /** |
| 113 | * \brief Register the USB device callback |
| 114 | * \param[in] type The callback type to register. |
| 115 | * \param[in] func The callback function, NULL to disable callback. |
| 116 | */ |
| 117 | void usb_d_register_callback(const enum usb_d_cb_type type, const FUNC_PTR func); |
| 118 | |
| 119 | /** |
| 120 | * \brief Enable the USB device driver |
| 121 | * \return Operation status. |
| 122 | * \retval 0 Success. |
| 123 | * \retval <0 Error code. |
| 124 | */ |
| 125 | int32_t usb_d_enable(void); |
| 126 | |
| 127 | /** |
| 128 | * \brief Disable the USB device driver |
| 129 | */ |
| 130 | void usb_d_disable(void); |
| 131 | |
| 132 | /** |
| 133 | * \brief Attach the USB device |
| 134 | */ |
| 135 | void usb_d_attach(void); |
| 136 | |
| 137 | /** |
| 138 | * \brief Detach the USB device |
| 139 | */ |
| 140 | void usb_d_detach(void); |
| 141 | |
| 142 | /** |
| 143 | * \brief Retrieve current USB working speed. |
| 144 | * \return USB Speed. See \ref usb_speed. |
| 145 | */ |
| 146 | enum usb_speed usb_d_get_speed(void); |
| 147 | |
| 148 | /** |
| 149 | * \brief Retrieve current USB frame number. |
| 150 | * \return Frame number. |
| 151 | */ |
| 152 | uint16_t usb_d_get_frame_num(void); |
| 153 | |
| 154 | /** |
| 155 | * \brief Retrieve current USB micro frame number. |
| 156 | * \return Micro frame number inside a frame (0~7). |
| 157 | * 0 if not available (not HS). |
| 158 | */ |
| 159 | uint8_t usb_d_get_uframe_num(void); |
| 160 | |
| 161 | /** |
| 162 | * \brief Set the USB address that is used. |
| 163 | * \param[in] addr The address to set. |
| 164 | */ |
| 165 | void usb_d_set_address(const uint8_t addr); |
| 166 | |
| 167 | /** |
| 168 | * \brief Send remote wakeup to host |
| 169 | * \return Operation status. |
| 170 | */ |
| 171 | void usb_d_send_remotewakeup(void); |
| 172 | |
| 173 | /** |
| 174 | * \brief Initialize the endpoint 0. |
| 175 | * |
| 176 | * Note that endpoint 0 must be initialized as control endpoint. |
| 177 | * |
| 178 | * \param[in] max_pkt_size Max. packet size of EP0. |
| 179 | * \return Operation status. |
| 180 | * \retval 0 Success. |
| 181 | * \retval <0 Error code. |
| 182 | */ |
| 183 | int32_t usb_d_ep0_init(const uint8_t max_pkt_size); |
| 184 | |
| 185 | /** |
| 186 | * \brief Initialize the endpoint. |
| 187 | * |
| 188 | * \param[in] ep The endpoint address. |
| 189 | * \param[in] attr The endpoint attributes. |
| 190 | * \param[in] max_pkt_size Max. packet size of EP0. |
| 191 | * \return Operation status. |
| 192 | * \retval 0 Success. |
| 193 | * \retval <0 Error code. |
| 194 | */ |
| 195 | int32_t usb_d_ep_init(const uint8_t ep, const uint8_t attr, const uint16_t max_pkt_size); |
| 196 | |
| 197 | /** |
| 198 | * \brief Disable and deinitialize the endpoint. |
| 199 | * \param[in] ep The endpoint address to deinitialize. |
| 200 | */ |
| 201 | void usb_d_ep_deinit(const uint8_t ep); |
| 202 | |
| 203 | /** |
| 204 | * \brief Register the USB device endpoint callback on initialized endpoint. |
| 205 | * |
| 206 | * \param[in] ep The endpoint address. |
| 207 | * \param[in] type The callback type to register. |
| 208 | * \param[in] func The callback function, NULL to disable callback. |
| 209 | */ |
| 210 | void usb_d_ep_register_callback(const uint8_t ep, const enum usb_d_ep_cb_type type, const FUNC_PTR func); |
| 211 | |
| 212 | /** |
| 213 | * \brief Enabled the initialized endpoint. |
| 214 | * |
| 215 | * Setup request will be monitored after enabling a control endpoint. |
| 216 | * |
| 217 | * \param[in] ep The endpoint address. |
| 218 | * \return Operation status. |
| 219 | * \retval 0 Success. |
| 220 | * \retval <0 Error code. |
| 221 | */ |
| 222 | int32_t usb_d_ep_enable(const uint8_t ep); |
| 223 | |
| 224 | /** |
| 225 | * \brief Disable the initialized endpoint. |
| 226 | * \param[in] ep The endpoint address. |
| 227 | */ |
| 228 | void usb_d_ep_disable(const uint8_t ep); |
| 229 | |
| 230 | /** |
| 231 | * \brief Get request data pointer to access received setup request packet |
| 232 | * \param[in] ep The endpoint address. |
| 233 | * \return Pointer to the request data. |
| 234 | * \retval NULL The endpoint is not a control endpoint. |
| 235 | */ |
| 236 | uint8_t *usb_d_ep_get_req(const uint8_t ep); |
| 237 | |
| 238 | /** |
| 239 | * \brief Endpoint transfer. |
| 240 | * |
| 241 | * For control endpoints, start the transfer according to the direction in the bmRequest |
| 242 | * type, and finish with STATUS stage. |
| 243 | * For non-control endpoints, the transfer will be unique direction. Defined by |
| 244 | * bit 8 of the endpoint address. |
| 245 | * |
| 246 | * \param[in] xfer Pointer to the transfer description. |
| 247 | * \return Operation status. |
| 248 | * \retval 0 Success. |
| 249 | * \retval <0 Error code. |
| 250 | */ |
| 251 | int32_t usb_d_ep_transfer(const struct usb_d_transfer *xfer); |
| 252 | |
| 253 | /** |
| 254 | * \brief Abort an on-going transfer on a specific endpoint. |
| 255 | * |
| 256 | * \param[in] ep The endpoint address. |
| 257 | */ |
| 258 | void usb_d_ep_abort(const uint8_t ep); |
| 259 | |
| 260 | /** |
| 261 | * \brief Retrieve the endpoint status. |
| 262 | * |
| 263 | * \param[in] ep The endpoint address. |
| 264 | * \param[out] stat Pointer to the buffer to fill the status description. |
| 265 | * |
| 266 | * \return Endpoint status. |
| 267 | * \retval 1 Busy. |
| 268 | * \retval 0 Idle. |
| 269 | * \retval <0 Error code. |
| 270 | */ |
| 271 | int32_t usb_d_ep_get_status(const uint8_t ep, struct usb_d_ep_status *stat); |
| 272 | |
| 273 | /** |
| 274 | * \brief Endpoint halt control. |
| 275 | * |
| 276 | * \param[in] ep The endpoint address. |
| 277 | * \param[in] ctrl Control code (SET/CLEAR/GET). |
| 278 | * |
| 279 | * \return Operation status or HALT state (if \c ctrl is \ref USB_EP_HALT_GET). |
| 280 | */ |
| 281 | int32_t usb_d_ep_halt(const uint8_t ep, const enum usb_ep_halt_ctrl ctrl); |
| 282 | |
| 283 | /** \brief Retrieve the current driver version |
| 284 | * |
| 285 | * \return Current driver version. |
| 286 | */ |
| 287 | uint32_t usb_d_get_version(void); |
| 288 | |
| 289 | /**@}*/ |
| 290 | |
| 291 | #ifdef __cplusplus |
| 292 | } |
| 293 | #endif |
| 294 | |
| 295 | #endif /* _HAL_USB_DEVICE_H_INCLUDED */ |