Kévin Redon | 69b92d9 | 2019-01-24 16:39:20 +0100 | [diff] [blame] | 1 | /** |
| 2 | * \file |
| 3 | * |
| 4 | * \brief SAM USB HPL |
| 5 | * |
| 6 | * Copyright (c) 2016-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 _HPL_USB_DEVICE_H_INCLUDED |
| 35 | #define _HPL_USB_DEVICE_H_INCLUDED |
| 36 | |
| 37 | #include <hpl_usb.h> |
| 38 | #include "hpl_usb_config.h" |
| 39 | |
| 40 | #ifdef __cplusplus |
| 41 | extern "C" { |
| 42 | #endif |
| 43 | |
| 44 | /** USB Device callback type. */ |
| 45 | enum usb_d_cb_type { |
| 46 | /** USB device SOF callback. */ |
| 47 | USB_D_CB_SOF, |
| 48 | /** USB device events callbacks. */ |
| 49 | USB_D_CB_EVENT, |
| 50 | /** Number of types of USB device callback types. */ |
| 51 | USB_D_CB_N |
| 52 | }; |
| 53 | |
| 54 | /** USB Device endpoint callback type. */ |
| 55 | enum usb_d_ep_cb_type { |
| 56 | /** USB device endpoint setup callback. */ |
| 57 | USB_D_EP_CB_SETUP, |
| 58 | /** USB device endpoint more data callback. */ |
| 59 | USB_D_EP_CB_MORE, |
| 60 | /** USB device endpoint transaction done or error callback. */ |
| 61 | USB_D_EP_CB_XFER, |
| 62 | /** Number of types of USB device endpoint callback types. */ |
| 63 | USB_D_EP_CB_N |
| 64 | }; |
| 65 | |
| 66 | /** Control action for USB device LPM handshake. */ |
| 67 | enum usb_d_lpm_ctrl { |
| 68 | /** No LPM handshake, not supported. */ |
| 69 | USB_D_LPM_DISABLE, |
| 70 | /** ACK the LPM transaction. */ |
| 71 | USB_D_LPM_ACK, |
| 72 | /** NYET the LPM transaction. */ |
| 73 | USB_D_LPM_NYET |
| 74 | }; |
| 75 | |
| 76 | /** |
| 77 | * USB device transfer descriptor. |
| 78 | */ |
| 79 | struct usb_d_transfer { |
| 80 | /** Pointer to data buffer to transfer. |
| 81 | * Note that it's recommended that the buffer is 32-bit aligned since |
| 82 | * some of USB peripheral require this. |
| 83 | */ |
| 84 | uint8_t *buf; |
| 85 | /** Transfer size, in number of bytes. |
| 86 | * Note that it's recommended that the buffer size is 32-bit aligned |
| 87 | * (modeled by 4) since some of USB peripheral require this. |
| 88 | */ |
| 89 | uint32_t size; |
| 90 | /** Endpoint address. */ |
| 91 | uint8_t ep; |
| 92 | /** Append ZLP for IN transfer, wait ZLP for OUT transfer. */ |
| 93 | uint8_t zlp; |
| 94 | }; |
| 95 | |
| 96 | /** USB device transactions status structure. */ |
| 97 | struct usb_d_trans_status { |
| 98 | /** Total data size. */ |
| 99 | uint32_t size; |
| 100 | /** Total transfered data count. */ |
| 101 | uint32_t count; |
| 102 | /** Endpoint address. */ |
| 103 | uint8_t ep; |
| 104 | /** Endpoint type - CTRL/ISO/INT/BULK. */ |
| 105 | uint8_t xtype : 2; |
| 106 | /** Transactions state, busy or not. */ |
| 107 | uint8_t busy : 1; |
| 108 | /** Transactions state, setup received or not. */ |
| 109 | uint8_t setup : 1; |
| 110 | /** Transactions state, stall or not. */ |
| 111 | uint8_t stall : 1; |
| 112 | /** Transactions direction. */ |
| 113 | uint8_t dir : 1; |
| 114 | }; |
| 115 | |
| 116 | /** Prototype function for callback that is invoked on USB device SOF. */ |
| 117 | typedef void (*_usb_d_dev_sof_cb_t)(void); |
| 118 | |
| 119 | /** Prototype function for callback that is invoked on USB device events. */ |
| 120 | typedef void (*_usb_d_dev_event_cb_t)(const enum usb_event, const uint32_t param); |
| 121 | |
| 122 | /** HPL USB device callbacks. */ |
| 123 | struct _usb_d_dev_callbacks { |
| 124 | /** Callback that is invoked on SOF. */ |
| 125 | _usb_d_dev_sof_cb_t sof; |
| 126 | /** Callback that is invoked on USB RESET/WAKEUP/RESUME/SUSPEND. */ |
| 127 | _usb_d_dev_event_cb_t event; |
| 128 | }; |
| 129 | |
| 130 | /** USB device endpoint callbacks. */ |
| 131 | enum usb_d_dev_ep_cb_type { |
| 132 | /** Setup packet is received. */ |
| 133 | USB_D_DEV_EP_CB_SETUP, |
| 134 | /** Try to require more data. */ |
| 135 | USB_D_DEV_EP_CB_MORE, |
| 136 | /** Transaction done OK/ERROR. */ |
| 137 | USB_D_DEV_EP_CB_DONE, |
| 138 | /** Number of device endpoint callbacks. */ |
| 139 | USB_D_DEV_EP_CB_N |
| 140 | }; |
| 141 | |
| 142 | /** |
| 143 | * Callback that is invoked when control SETUP packet has bee received. |
| 144 | * \ref _usb_d_dev_ep_read_req() must be invoked to read setup data, and allow |
| 145 | * IN/OUT transactions on control endpoint. |
| 146 | */ |
| 147 | typedef void (*_usb_d_dev_ep_cb_setup_t)(const uint8_t ep); |
| 148 | |
| 149 | /** Callback that is invoked when buffer is done, but last packet is full size |
| 150 | * packet without ZLP. Return \c true if more data has been requested. */ |
| 151 | typedef bool (*_usb_d_dev_ep_cb_more_t)(const uint8_t ep, const uint32_t transfered); |
| 152 | |
| 153 | /** Callback that is invoked when all data is finished, including background |
| 154 | * transfer, or error happens. */ |
| 155 | typedef void (*_usb_d_dev_ep_cb_done_t)(const uint8_t ep, const int32_t code, const uint32_t transfered); |
| 156 | |
| 157 | /** Callbacks for HPL USB device endpoint. */ |
| 158 | struct _usb_d_dev_ep_callbacks { |
| 159 | /** Callback that is invoked when SETUP packet is received. |
| 160 | * \ref _usb_d_dev_ep_read_req() must be invoked to read setup data, and |
| 161 | * allow IN/OUT transactions on control endpoint. |
| 162 | */ |
| 163 | _usb_d_dev_ep_cb_setup_t setup; |
| 164 | /** Callback that is invoked to check if buffer is NULL and more data is |
| 165 | * required. |
| 166 | * It's called when last packet is full size packet, without |
| 167 | * auto ZLP enabled. |
| 168 | * It could be called when background transfer is still in progress. |
| 169 | */ |
| 170 | _usb_d_dev_ep_cb_more_t more; |
| 171 | /** Callback that is invoked when transaction is done, including background |
| 172 | * transfer, or error occurs. |
| 173 | */ |
| 174 | _usb_d_dev_ep_cb_done_t done; |
| 175 | }; |
| 176 | |
| 177 | /** |
| 178 | * \brief Initialize the USB device instance |
| 179 | * \return Operation result status. |
| 180 | * \retval 0 Success. |
| 181 | * \retval <0 Error code. |
| 182 | */ |
| 183 | int32_t _usb_d_dev_init(void); |
| 184 | |
| 185 | /** |
| 186 | * \brief Deinitialize the USB device instance |
| 187 | * \return Operation result status. |
| 188 | * \retval 0 Success. |
| 189 | * \retval <0 Error code. |
| 190 | */ |
| 191 | void _usb_d_dev_deinit(void); |
| 192 | |
| 193 | /** |
| 194 | * \brief Register callback to handle USB device events |
| 195 | * \param[in] type Callback type. See \ref usb_d_cb_type. |
| 196 | * \param[in] func Pointer to callback function. |
| 197 | * Refer to \ref _usb_d_dev_callbacks for the prototypes. |
| 198 | */ |
| 199 | void _usb_d_dev_register_callback(const enum usb_d_cb_type type, const FUNC_PTR func); |
| 200 | |
| 201 | /** |
| 202 | * \brief Register callback to handle USB device endpoint events |
| 203 | * \param[in] type Callback type. See \ref usb_d_dev_ep_cb_type. |
| 204 | * \param[in] func Pointer to callback function. |
| 205 | * Refer to \ref _usb_d_dev_ep_callbacks for the prototypes. |
| 206 | */ |
| 207 | void _usb_d_dev_register_ep_callback(const enum usb_d_dev_ep_cb_type type, const FUNC_PTR func); |
| 208 | |
| 209 | /** |
| 210 | * \brief Enable the USB device |
| 211 | * \return Operation result status. |
| 212 | * \retval 0 Success. |
| 213 | * \retval <0 Error code. |
| 214 | */ |
| 215 | int32_t _usb_d_dev_enable(void); |
| 216 | |
| 217 | /** |
| 218 | * \brief Disable the USB device |
| 219 | * \return Operation result status. |
| 220 | * \retval 0 Success. |
| 221 | * \retval <0 Error code. |
| 222 | */ |
| 223 | int32_t _usb_d_dev_disable(void); |
| 224 | |
| 225 | /** |
| 226 | * \brief Attach the USB device |
| 227 | */ |
| 228 | void _usb_d_dev_attach(void); |
| 229 | |
| 230 | /** |
| 231 | * \brief Detach the USB device |
| 232 | */ |
| 233 | void _usb_d_dev_detach(void); |
| 234 | |
| 235 | /** |
| 236 | * \brief Send the USB device remote wakeup to host |
| 237 | */ |
| 238 | void _usb_d_dev_send_remotewakeup(void); |
| 239 | |
| 240 | /** |
| 241 | * \brief Get the USB device working speed |
| 242 | * \return USB speed. See \ref usb_speed. |
| 243 | */ |
| 244 | enum usb_speed _usb_d_dev_get_speed(void); |
| 245 | |
| 246 | /** |
| 247 | * \brief Set the USB device address |
| 248 | * \param[in] addr Address to be used. |
| 249 | */ |
| 250 | void _usb_d_dev_set_address(const uint8_t addr); |
| 251 | |
| 252 | /** |
| 253 | * \brief Get the USB device address |
| 254 | * \return Address that is used. |
| 255 | */ |
| 256 | uint8_t _usb_d_dev_get_address(void); |
| 257 | |
| 258 | /** |
| 259 | * \brief Get the USB device frame number |
| 260 | * \return The frame number. |
| 261 | */ |
| 262 | uint16_t _usb_d_dev_get_frame_n(void); |
| 263 | |
| 264 | /** |
| 265 | * \brief Get the USB device micro frame number |
| 266 | * \return The micro frame number inside one frame (0~7). |
| 267 | */ |
| 268 | uint8_t _usb_d_dev_get_uframe_n(void); |
| 269 | |
| 270 | /** |
| 271 | * \brief Initialize and enable the USB device default endpoint 0 |
| 272 | * \param[in] max_pkt_siz Max endpoint size. |
| 273 | * \return Operation result status. |
| 274 | * \retval 0 Success. |
| 275 | * \retval <0 Error code. |
| 276 | */ |
| 277 | int32_t _usb_d_dev_ep0_init(const uint8_t max_pkt_siz); |
| 278 | |
| 279 | /** |
| 280 | * \brief Initialize and enable the USB device endpoint |
| 281 | * \param[in] ep Endpoint address, |
| 282 | * see endpoint descriptor details in USB spec. |
| 283 | * \param[in] attr Endpoint attributes, |
| 284 | * see endpoint descriptor details in USB spec. |
| 285 | * \param[in] max_pkt_siz Endpoint size, |
| 286 | * see endpoint descriptor details in USB spec. |
| 287 | * \return Operation result status. |
| 288 | * \retval 0 Success. |
| 289 | * \retval <0 Error code. |
| 290 | */ |
| 291 | int32_t _usb_d_dev_ep_init(const uint8_t ep, const uint8_t attr, uint16_t max_pkt_siz); |
| 292 | |
| 293 | /** |
| 294 | * \brief Disable and deinitialize the USB device endpoint |
| 295 | |
| 296 | * \param[in] ep The endpoint to deinitialize. |
| 297 | */ |
| 298 | void _usb_d_dev_ep_deinit(const uint8_t ep); |
| 299 | |
| 300 | /** |
| 301 | * \brief Enable the endpoint |
| 302 | * \param[in] ep The endpoint to enable. |
| 303 | * \return Operation result status. |
| 304 | * \retval 0 Success. |
| 305 | * \retval <0 Error code. |
| 306 | */ |
| 307 | int32_t _usb_d_dev_ep_enable(const uint8_t ep); |
| 308 | |
| 309 | /** |
| 310 | * \brief Disable the endpoint |
| 311 | * \param[in] ep The endpoint to disable. |
| 312 | */ |
| 313 | void _usb_d_dev_ep_disable(const uint8_t ep); |
| 314 | |
| 315 | /** |
| 316 | * \brief Set/Clear/Get USB device endpoint stall status |
| 317 | * \param[in] ep Endpoint address. |
| 318 | * \param[in] ctrl Operation selector. See \ref usb_ep_stall_ctrl. |
| 319 | * \return Operation result or stall status. |
| 320 | * \retval 0 Success or not stall. |
| 321 | * \retval 1 Endpoint is stalled. |
| 322 | * \retval -1 error. |
| 323 | */ |
| 324 | int32_t _usb_d_dev_ep_stall(const uint8_t ep, const enum usb_ep_stall_ctrl ctrl); |
| 325 | |
| 326 | /** |
| 327 | * \brief Read setup request data from specific endpoint |
| 328 | * \param[in] ep Endpoint address. |
| 329 | * \param[out] req_buf Pointer to buffer to locate the setup packet. |
| 330 | * \return Number of bytes or error code. |
| 331 | * \retval <0 error code. |
| 332 | * \retval 0 No setup packet ready for read. |
| 333 | * \retval >0 Size of bytes read, and ready to start IN/OUT. Note that if |
| 334 | * this number is over 8, only first 8 bytes will be copied. |
| 335 | */ |
| 336 | int32_t _usb_d_dev_ep_read_req(const uint8_t ep, uint8_t *req_buf); |
| 337 | |
| 338 | /** |
| 339 | * \brief Start USB device transfer |
| 340 | * |
| 341 | * On different USB peripheral hardware the transaction buffer address and size |
| 342 | * may have different constraints. E.g., some hardware may require input address |
| 343 | * 32-bit aligned, and input size 32-bit aligned. Refer to the corresponding |
| 344 | * hardware usage reference documents. |
| 345 | * The constraints are checked in implementation, with error code returned. |
| 346 | * |
| 347 | * \param[in] trans Pointer to the transaction description. |
| 348 | * \return Operation result status. |
| 349 | * \retval 1 Busy. |
| 350 | * \retval 0 Success. |
| 351 | * \retval <0 Error code. |
| 352 | */ |
| 353 | int32_t _usb_d_dev_ep_trans(const struct usb_d_transfer *trans); |
| 354 | |
| 355 | /** |
| 356 | * \brief Abort pending USB device transaction on specific endpoint |
| 357 | * \param[in] ep Endpoint address to abort. |
| 358 | */ |
| 359 | void _usb_d_dev_ep_abort(const uint8_t ep); |
| 360 | |
| 361 | /** |
| 362 | * \brief Retrieve endpoint status. |
| 363 | * \param[in] ep Endpoint address. |
| 364 | * \param[out] stat Pointer to buffer to fill status description. |
| 365 | * \return Status. |
| 366 | * \retval 2 Packet writing. |
| 367 | * \retval 1 Busy. |
| 368 | * \retval 0 Ready. |
| 369 | * \retval <0 Error code. |
| 370 | */ |
| 371 | int32_t _usb_d_dev_ep_get_status(const uint8_t ep, struct usb_d_trans_status *stat); |
| 372 | |
| 373 | #ifdef __cplusplus |
| 374 | } |
| 375 | #endif |
| 376 | |
| 377 | #endif /* _HPL_USB_DEVICE_H_INCLUDED */ |