1 /* 2 * Copyright (c) 2016 - 2018, Nordic Semiconductor ASA 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 8 * 1. Redistributions of source code must retain the above copyright notice, this 9 * list of conditions and the following disclaimer. 10 * 11 * 2. Redistributions in binary form must reproduce the above copyright 12 * notice, this list of conditions and the following disclaimer in the 13 * documentation and/or other materials provided with the distribution. 14 * 15 * 3. Neither the name of the copyright holder nor the names of its 16 * contributors may be used to endorse or promote products derived from this 17 * software without specific prior written permission. 18 * 19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 20 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 23 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29 * POSSIBILITY OF SUCH DAMAGE. 30 */ 31 32 #ifndef NRFX_USBD_H__ 33 #define NRFX_USBD_H__ 34 35 #include <nrfx.h> 36 #include <hal/nrf_usbd.h> 37 38 #ifdef __cplusplus 39 extern "C" { 40 #endif 41 42 /** 43 * @defgroup nrfx_usbd USBD driver 44 * @{ 45 * @ingroup nrf_usbd 46 * @brief Universal Serial Bus Device (USBD) peripheral driver. 47 */ 48 49 /** 50 * @brief Number of bytes in the endpoint. 51 */ 52 #define NRFX_USBD_EPSIZE 64 53 54 /** 55 * @brief Number of bytes for isochronous endpoints. 56 * 57 * Number of bytes for isochronous endpoints in total. 58 * This number would be shared between IN and OUT endpoint. 59 * It may be also assigned totaly to one endpoint. 60 * @sa nrf_usbd_isosplit_set 61 * @sa nrf_usbd_isosplit_get 62 */ 63 #define NRFX_USBD_ISOSIZE 1024 64 65 /** 66 * @brief The size of internal feeder buffer. 67 * 68 * @sa nrfx_usbd_feeder_buffer_get 69 */ 70 #define NRFX_USBD_FEEDER_BUFFER_SIZE NRFX_USBD_EPSIZE 71 72 /** 73 * @name Macros for creating endpoint identifiers. 74 * 75 * Auxiliary macros for creating endpoint identifiers compatible with the USB specification. 76 * @{ 77 * @brief Create identifier for IN endpoint. 78 * 79 * Simple macro to create IN endpoint identifier for given endpoint number. 80 * 81 * @param[in] n Endpoint number. 82 * 83 * @return Endpoint identifier that connects endpoint number and endpoint direction. 84 */ 85 #define NRFX_USBD_EPIN(n) ((nrfx_usbd_ep_t)NRF_USBD_EPIN(n)) 86 /** 87 * @brief Create identifier for OUT endpoint. 88 * 89 * Simple macro to create OUT endpoint identifier for given endpoint number. 90 * 91 * @param[in] n Endpoint number. 92 * 93 * @return Endpoint identifier that connects endpoint number and endpoint direction. 94 */ 95 #define NRFX_USBD_EPOUT(n) ((nrfx_usbd_ep_t)NRF_USBD_EPOUT(n)) 96 /** @} */ 97 98 /** 99 * @brief Endpoint identifier. 100 * 101 * Endpoint identifier used in the driver. 102 * This endpoint number is consistent with USB 2.0 specification. 103 */ 104 typedef enum 105 { 106 NRFX_USBD_EPOUT0 = NRF_USBD_EPOUT(0), /**< Endpoint OUT 0 */ 107 NRFX_USBD_EPOUT1 = NRF_USBD_EPOUT(1), /**< Endpoint OUT 1 */ 108 NRFX_USBD_EPOUT2 = NRF_USBD_EPOUT(2), /**< Endpoint OUT 2 */ 109 NRFX_USBD_EPOUT3 = NRF_USBD_EPOUT(3), /**< Endpoint OUT 3 */ 110 NRFX_USBD_EPOUT4 = NRF_USBD_EPOUT(4), /**< Endpoint OUT 4 */ 111 NRFX_USBD_EPOUT5 = NRF_USBD_EPOUT(5), /**< Endpoint OUT 5 */ 112 NRFX_USBD_EPOUT6 = NRF_USBD_EPOUT(6), /**< Endpoint OUT 6 */ 113 NRFX_USBD_EPOUT7 = NRF_USBD_EPOUT(7), /**< Endpoint OUT 7 */ 114 NRFX_USBD_EPOUT8 = NRF_USBD_EPOUT(8), /**< Endpoint OUT 8 */ 115 116 NRFX_USBD_EPIN0 = NRF_USBD_EPIN(0), /**< Endpoint IN 0 */ 117 NRFX_USBD_EPIN1 = NRF_USBD_EPIN(1), /**< Endpoint IN 1 */ 118 NRFX_USBD_EPIN2 = NRF_USBD_EPIN(2), /**< Endpoint IN 2 */ 119 NRFX_USBD_EPIN3 = NRF_USBD_EPIN(3), /**< Endpoint IN 3 */ 120 NRFX_USBD_EPIN4 = NRF_USBD_EPIN(4), /**< Endpoint IN 4 */ 121 NRFX_USBD_EPIN5 = NRF_USBD_EPIN(5), /**< Endpoint IN 5 */ 122 NRFX_USBD_EPIN6 = NRF_USBD_EPIN(6), /**< Endpoint IN 6 */ 123 NRFX_USBD_EPIN7 = NRF_USBD_EPIN(7), /**< Endpoint IN 7 */ 124 NRFX_USBD_EPIN8 = NRF_USBD_EPIN(8), /**< Endpoint IN 8 */ 125 } nrfx_usbd_ep_t; 126 127 /** 128 * @brief Events generated by the driver. 129 * 130 * Enumeration of possible events that may be generated by the driver. 131 */ 132 typedef enum 133 { 134 NRFX_USBD_EVT_SOF, /**< Start Of Frame event on USB bus detected. */ 135 NRFX_USBD_EVT_RESET, /**< Reset condition on USB bus detected. */ 136 NRFX_USBD_EVT_SUSPEND, /**< This device should go to suspend mode now. */ 137 NRFX_USBD_EVT_RESUME, /**< This device should resume from suspend now. */ 138 NRFX_USBD_EVT_WUREQ, /**< Wakeup request - the USBD peripheral is ready to generate 139 WAKEUP signal after exiting low power mode. */ 140 NRFX_USBD_EVT_SETUP, /**< Setup frame received and decoded. */ 141 NRFX_USBD_EVT_EPTRANSFER, /**< For Rx (OUT: Host->Device): 142 * 1. The packet has been received but there is no buffer prepared for transfer already. 143 * 2. Whole transfer has been finished. 144 * 145 * For Tx (IN: Device->Host): 146 * The last packet from requested transfer has been transfered over USB bus and acknowledged. 147 */ 148 NRFX_USBD_EVT_CNT /**< Number of defined events. */ 149 } nrfx_usbd_event_type_t; 150 151 /** 152 * @brief Endpoint status codes. 153 * 154 * Status codes that may be returned by @ref nrfx_usbd_ep_status_get or, except for 155 * @ref NRFX_USBD_EP_BUSY, reported together with @ref NRFX_USBD_EVT_EPTRANSFER. 156 */ 157 typedef enum 158 { 159 NRFX_USBD_EP_OK, /**< No error occured. */ 160 NRFX_USBD_EP_WAITING, /**< Data received, no buffer prepared already - waiting for configured transfer. */ 161 NRFX_USBD_EP_OVERLOAD, /**< Received number of bytes cannot fit given buffer. 162 * This error would also be returned when next_transfer function has been defined 163 * but currently received data cannot fit completely in current buffer. 164 * No data split from single endpoint transmission is supported. 165 * 166 * When this error is reported - data is left inside endpoint buffer. 167 * Clear endpoint or prepare new buffer and read it. 168 */ 169 NRFX_USBD_EP_ABORTED, /**< EP0 transfer can be aborted when new setup comes. 170 * Any other transfer can be aborted by USB reset or driver stopping. 171 */ 172 NRFX_USBD_EP_BUSY, /**< A transfer is in progress. */ 173 } nrfx_usbd_ep_status_t; 174 175 /** 176 * @brief Event structure. 177 * 178 * Structure passed to event handler. 179 */ 180 typedef struct 181 { 182 nrfx_usbd_event_type_t type; 183 union 184 { 185 struct { 186 uint16_t framecnt; /**< Current value of frame counter. */ 187 } sof; /**< Data available for @ref NRFX_USBD_EVT_SOF. */ 188 struct { 189 nrfx_usbd_ep_t ep; /**< Endpoint number. */ 190 } isocrc; 191 struct { 192 nrfx_usbd_ep_t ep; /**< Endpoint number. */ 193 nrfx_usbd_ep_status_t status; /**< Status for the endpoint. */ 194 } eptransfer; 195 } data; 196 } nrfx_usbd_evt_t; 197 198 /** 199 * @brief USBD event callback function type. 200 * 201 * @param[in] p_event Event information structure. 202 */ 203 typedef void (*nrfx_usbd_event_handler_t)(nrfx_usbd_evt_t const * p_event); 204 205 /** 206 * @brief Universal data pointer. 207 * 208 * Universal data pointer that can be used for any type of transfer. 209 */ 210 typedef union 211 { 212 void const * tx; //!< Constant TX buffer pointer. 213 void * rx; //!< Writable RX buffer pointer. 214 uint32_t addr; //!< Numeric value used internally by the driver. 215 } nrfx_usbd_data_ptr_t; 216 217 /** 218 * @brief Structure to be filled with information about the next transfer. 219 * 220 * This is used mainly for transfer feeders and consumers. 221 * It describes a single endpoint transfer and therefore the size of the buffer 222 * can never be higher than the endpoint size. 223 */ 224 typedef struct 225 { 226 nrfx_usbd_data_ptr_t p_data; //!< Union with available data pointers used by the driver. 227 size_t size; //!< Size of the requested transfer. 228 } nrfx_usbd_ep_transfer_t; 229 230 /** 231 * @brief Flags for the current transfer. 232 * 233 * Flags configured for the transfer that can be merged using the bitwise 'or' operator (|). 234 */ 235 typedef enum 236 { 237 NRFX_USBD_TRANSFER_ZLP_FLAG = 1U << 0, //!< Add a zero-length packet. 238 } nrfx_usbd_transfer_flags_t; 239 240 /** 241 * @brief Total transfer configuration. 242 * 243 * This structure is used to configure total transfer information. 244 * It is used by internal built-in feeders and consumers. 245 */ 246 typedef struct 247 { 248 nrfx_usbd_data_ptr_t p_data; //!< Union with available data pointers used by the driver. 249 size_t size; //!< Total size of the requested transfer. 250 uint32_t flags; //!< Transfer flags. 251 /**< Use the @ref nrfx_usbd_transfer_flags_t values. */ 252 } nrfx_usbd_transfer_t; 253 254 /** 255 * @brief Auxiliary macro for declaring IN transfer description with optional flags. 256 * 257 * The base macro for creating transfers with any configuration option. 258 * 259 * @param name Instance name. 260 * @param tx_buff Buffer to transfer. 261 * @param tx_size Transfer size. 262 * @param tx_flags Flags for the transfer (see @ref nrfx_usbd_transfer_flags_t). 263 * 264 * @return Configured variable with total transfer description. 265 */ 266 #define NRFX_USBD_TRANSFER_IN(name, tx_buff, tx_size, tx_flags) \ 267 const nrfx_usbd_transfer_t name = { \ 268 .p_data = { .tx = (tx_buff) }, \ 269 .size = (tx_size), \ 270 .flags = (tx_flags) \ 271 } 272 273 /** 274 * @brief Helper macro for declaring OUT transfer item (@ref nrfx_usbd_transfer_t). 275 * 276 * @param name Instance name. 277 * @param rx_buff Buffer to transfer. 278 * @param rx_size Transfer size. 279 * */ 280 #define NRFX_USBD_TRANSFER_OUT(name, rx_buff, rx_size) \ 281 const nrfx_usbd_transfer_t name = { \ 282 .p_data = { .rx = (rx_buff) }, \ 283 .size = (rx_size), \ 284 .flags = 0 \ 285 } 286 287 /** 288 * @brief USBD transfer feeder. 289 * 290 * Pointer for a transfer feeder. 291 * Transfer feeder is a feedback function used to prepare a single 292 * TX (Device->Host) endpoint transfer. 293 * 294 * The transfers provided by the feeder must be simple: 295 * - The size of the transfer provided by this function is limited to a single endpoint buffer. 296 * Bigger transfers are not handled automatically in this case. 297 * - Flash transfers are not automatically supported- you must copy them to the RAM buffer before. 298 * 299 * @note 300 * This function may use @ref nrfx_usbd_feeder_buffer_get to gain a temporary buffer 301 * that can be used to prepare transfer. 302 * 303 * @param[out] p_next Structure with the data for the next transfer to be filled. 304 * Required only if the function returns true. 305 * @param[in,out] p_context Context variable configured with the transfer. 306 * @param[in] ep_size The endpoint size. 307 * 308 * @retval false The current transfer is the last one - you do not need to call 309 * the function again. 310 * @retval true There is more data to be prepared and when the current transfer 311 * finishes, the feeder function is expected to be called again. 312 */ 313 typedef bool (*nrfx_usbd_feeder_t)(nrfx_usbd_ep_transfer_t * p_next, 314 void * p_context, 315 size_t ep_size); 316 317 /** 318 * @brief USBD transfer consumer. 319 * 320 * Pointer for a transfer consumer. 321 * Transfer consumer is a feedback function used to prepare a single 322 * RX (Host->Device) endpoint transfer. 323 * 324 * The transfer must provide a buffer big enough to fit the whole data from the endpoint. 325 * Otherwise, the NRFX_USBD_EP_OVERLOAD event is generated. 326 * 327 * @param[out] p_next Structure with the data for the next transfer to be filled. 328 * Required only if the function returns true. 329 * @param[in,out] p_context Context variable configured with the transfer. 330 * @param[in] ep_size The endpoint size. 331 * @param[in] data_size Number of received bytes in the endpoint buffer. 332 * 333 * @retval false Current transfer is the last one - you do not need to call 334 * the function again. 335 * @retval true There is more data to be prepared and when current transfer 336 * finishes, the feeder function is expected to be called again. 337 */ 338 typedef bool (*nrfx_usbd_consumer_t)(nrfx_usbd_ep_transfer_t * p_next, 339 void * p_context, 340 size_t ep_size, 341 size_t data_size); 342 343 /** 344 * @brief Universal transfer handler. 345 * 346 * Union with feeder and consumer function pointer. 347 */ 348 typedef union 349 { 350 nrfx_usbd_feeder_t feeder; //!< Feeder function pointer. 351 nrfx_usbd_consumer_t consumer; //!< Consumer function pointer. 352 } nrfx_usbd_handler_t; 353 354 /** 355 * @brief USBD transfer descriptor. 356 * 357 * Universal structure that may hold the setup for callback configuration for 358 * IN or OUT type of the transfer. 359 */ 360 typedef struct 361 { 362 nrfx_usbd_handler_t handler; //!< Handler for the current transfer, function pointer. 363 void * p_context; //!< Context for the transfer handler. 364 } nrfx_usbd_handler_desc_t; 365 366 /** 367 * @brief Setup packet structure. 368 * 369 * Structure that contains interpreted SETUP packet as described in USB specification. 370 */ 371 typedef struct 372 { 373 uint8_t bmRequestType; //!< byte 0 374 uint8_t bRequest; //!< byte 1 375 uint16_t wValue; //!< byte 2, 3 376 uint16_t wIndex; //!< byte 4, 5 377 uint16_t wLength; //!< byte 6, 7 378 } nrfx_usbd_setup_t; 379 380 /** 381 * @brief Driver initialization. 382 * 383 * @param[in] event_handler Event handler provided by the user. Cannot be null. 384 * 385 * @retval NRFX_SUCCESS Initialization successful. 386 * @retval NRFX_ERROR_INVALID_STATE Driver was already initialized. 387 */ 388 nrfx_err_t nrfx_usbd_init(nrfx_usbd_event_handler_t event_handler); 389 390 /** 391 * @brief Driver deinitialization. 392 */ 393 void nrfx_usbd_uninit(void); 394 395 /** 396 * @brief Enable the USBD port. 397 * 398 * After calling this function USBD peripheral would be enabled. 399 * The USB LDO would be enabled. 400 * Enabled USBD peripheral would request HFCLK. 401 * This function does not enable external oscillator, so if it is not enabled by other part of the 402 * program after enabling USBD driver HFINT would be used for the USBD peripheral. 403 * It is perfectly fine until USBD is started. See @ref nrfx_usbd_start. 404 * 405 * In normal situation this function should be called in reaction to USBDETECTED 406 * event from POWER peripheral. 407 * 408 * Interrupts and USB pins pull-up would stay disabled until @ref nrfx_usbd_start 409 * function is called. 410 */ 411 void nrfx_usbd_enable(void); 412 413 /** 414 * @brief Disable the USBD port. 415 * 416 * After calling this function USBD peripheral would be disabled. 417 * No events would be detected or processed by the driver. 418 * Clock for the peripheral would be disconnected. 419 */ 420 void nrfx_usbd_disable(void); 421 422 /** 423 * @brief Start USB functionality. 424 * 425 * After calling this function USBD peripheral should be fully functional 426 * and all new incoming events / interrupts would be processed by the driver. 427 * 428 * Also only after calling this function host sees new connected device. 429 * 430 * Call this function when USBD power LDO regulator is ready - on USBPWRRDY event 431 * from POWER peripheral. 432 * 433 * Before USBD interrupts are enabled, external HFXO is requested. 434 * 435 * @param enable_sof The flag that is used to enable SOF processing. 436 * If it is false, SOF interrupt is left disabled and will not be generated. 437 * This improves power saving if SOF is not required. 438 * 439 * @note If the isochronous endpoints are going to be used, 440 * it is required to enable the SOF. 441 * In other case any isochronous endpoint would stay busy 442 * after first transmission. 443 */ 444 void nrfx_usbd_start(bool enable_sof); 445 446 /** 447 * @brief Stop USB functionality. 448 * 449 * This function disables USBD pull-up and interrupts. 450 * 451 * The HFXO request is released in this function. 452 * 453 * @note 454 * This function can also be used to logically disconnect USB from the HOST that 455 * would force it to enumerate device after calling @ref nrfx_usbd_start. 456 */ 457 void nrfx_usbd_stop(void); 458 459 /** 460 * @brief Check if driver is initialized. 461 * 462 * @retval false Driver is not initialized. 463 * @retval true Driver is initialized. 464 */ 465 bool nrfx_usbd_is_initialized(void); 466 467 /** 468 * @brief Check if driver is enabled. 469 * 470 * @retval false Driver is disabled. 471 * @retval true Driver is enabled. 472 */ 473 bool nrfx_usbd_is_enabled(void); 474 475 /** 476 * @brief Check if driver is started. 477 * 478 * @retval false Driver is not started. 479 * @retval true Driver is started (fully functional). 480 * @note The USBD peripheral interrupt state is checked. 481 */ 482 bool nrfx_usbd_is_started(void); 483 484 /** 485 * @brief Suspend USBD operation. 486 * 487 * The USBD peripheral is forced to go into the low power mode. 488 * The function has to be called in the reaction to @ref NRFX_USBD_EVT_SUSPEND event 489 * when the firmware is ready. 490 * 491 * After successful call of this function most of the USBD registers would be unavailable. 492 * 493 * @note Check returned value for the feedback if suspending was successful. 494 * 495 * @retval true USBD peripheral successfully suspended. 496 * @retval false USBD peripheral was not suspended due to resume detection. 497 */ 498 bool nrfx_usbd_suspend(void); 499 500 /** 501 * @brief Start wake up procedure. 502 * 503 * The USBD peripheral is forced to quit the low power mode. 504 * After calling this function all the USBD registers would be available. 505 * 506 * The hardware starts measuring time when wake up is possible. 507 * This may take 0-5 ms depending on how long the SUSPEND state was kept on the USB line. 508 509 * When NRFX_USBD_EVT_WUREQ event is generated it means that Wake Up signaling has just been 510 * started on the USB lines. 511 * 512 * @note Do not expect only @ref NRFX_USBD_EVT_WUREQ event. 513 * There always may appear @ref NRFX_USBD_EVT_RESUME event. 514 * @note NRFX_USBD_EVT_WUREQ event means that Remote WakeUp signal 515 * has just begun to be generated. 516 * This may take up to 20 ms for the bus to become active. 517 * 518 * @retval true WakeUp procedure started. 519 * @retval false No WakeUp procedure started - bus is already active. 520 */ 521 bool nrfx_usbd_wakeup_req(void); 522 523 /** 524 * @brief Check if USBD is in SUSPEND mode. 525 * 526 * @note This is the information about peripheral itself, not about the bus state. 527 * 528 * @retval true USBD peripheral is suspended. 529 * @retval false USBD peripheral is active. 530 */ 531 bool nrfx_usbd_suspend_check(void); 532 533 /** 534 * @brief Enable only interrupts that should be processed in SUSPEND mode. 535 * 536 * Auxiliary function to help with SUSPEND mode integration. 537 * It enables only the interrupts that can be properly processed without stable HFCLK. 538 * 539 * Normally all the interrupts are enabled. 540 * Use this function to suspend interrupt processing that may require stable HFCLK until the 541 * clock is enabled. 542 * 543 * @sa nrfx_usbd_active_irq_config 544 */ 545 void nrfx_usbd_suspend_irq_config(void); 546 547 /** 548 * @brief Default active interrupt configuration. 549 * 550 * Default interrupt configuration. 551 * Use in a pair with @ref nrfx_usbd_active_irq_config. 552 * 553 * @sa nrfx_usbd_suspend_irq_config 554 */ 555 void nrfx_usbd_active_irq_config(void); 556 557 /** 558 * @brief Check the bus state. 559 * 560 * This function checks if the bus state is suspended. 561 * 562 * @note The value returned by this function changes on SUSPEND and RESUME event processing. 563 * 564 * @retval true USBD bus is suspended. 565 * @retval false USBD bus is active. 566 */ 567 bool nrfx_usbd_bus_suspend_check(void); 568 569 /** 570 * @brief Force the bus state to active 571 */ 572 void nrfx_usbd_force_bus_wakeup(void); 573 574 /** 575 * @brief Configure packet size that should be supported by the endpoint. 576 * 577 * The real endpoint buffer size is always the same. 578 * This value sets max packet size that would be transmitted over the endpoint. 579 * This is required by the driver. 580 * 581 * @param[in] ep Endpoint number. 582 * @param[in] size Required maximum packet size. 583 * 584 * @note Endpoint size is always set to @ref NRFX_USBD_EPSIZE or @ref NRFX_USBD_ISOSIZE / 2 585 * when @ref nrfx_usbd_ep_enable function is called. 586 */ 587 void nrfx_usbd_ep_max_packet_size_set(nrfx_usbd_ep_t ep, uint16_t size); 588 589 /** 590 * @brief Get configured endpoint packet size. 591 * 592 * Function to get configured endpoint size on the buffer. 593 * 594 * @param[in] ep Endpoint number. 595 * 596 * @return Maximum pocket size configured on selected endpoint. 597 */ 598 uint16_t nrfx_usbd_ep_max_packet_size_get(nrfx_usbd_ep_t ep); 599 600 /** 601 * @brief Check if the selected endpoint is enabled. 602 * 603 * @param[in] ep Endpoint number to check. 604 * 605 * @retval true Endpoint is enabled. 606 * @retval false Endpoint is disabled. 607 */ 608 bool nrfx_usbd_ep_enable_check(nrfx_usbd_ep_t ep); 609 610 /** 611 * @brief Enable selected endpoint. 612 * 613 * This function enables endpoint itself and its interrupts. 614 * 615 * @param[in] ep Endpoint number to enable. 616 * 617 * @note 618 * Max packet size is set to endpoint default maximum value. 619 * 620 * @sa nrfx_usbd_ep_max_packet_size_set 621 */ 622 void nrfx_usbd_ep_enable(nrfx_usbd_ep_t ep); 623 624 /** 625 * @brief Disable selected endpoint. 626 * 627 * This function disables endpoint itself and its interrupts. 628 * 629 * @param[in] ep Endpoint number to disable. 630 */ 631 void nrfx_usbd_ep_disable(nrfx_usbd_ep_t ep); 632 633 /** 634 * @brief Disable all endpoints except for EP0. 635 * 636 * Disable all endpoints that can be disabled in USB device while it is still active. 637 */ 638 void nrfx_usbd_ep_default_config(void); 639 640 /** 641 * @brief Start sending data over endpoint. 642 * 643 * Function initializes endpoint transmission. 644 * This is asynchronous function - it finishes immediately after configuration 645 * for transmission is prepared. 646 * 647 * @note Data buffer pointed by p_data have to be kept active till 648 * @ref NRFX_USBD_EVT_EPTRANSFER event is generated. 649 * 650 * @param[in] ep Endpoint number. 651 * For IN endpoint sending would be initiated. 652 * For OUT endpoint receiving would be initiated. 653 * @param[in] p_transfer Transfer parameters. 654 * 655 * @retval NRFX_SUCCESS Transfer queued or started. 656 * @retval NRFX_ERROR_BUSY Selected endpoint is pending. 657 * @retval NRFX_ERROR_INVALID_ADDR Unexpected transfer on EPIN0 or EPOUT0. 658 */ 659 nrfx_err_t nrfx_usbd_ep_transfer(nrfx_usbd_ep_t ep, 660 nrfx_usbd_transfer_t const * p_transfer); 661 662 /** 663 * @brief Start sending data over the endpoint using the transfer handler function. 664 * 665 * This function initializes an endpoint transmission. 666 * Just before data is transmitted, the transfer handler 667 * is called and it prepares a data chunk. 668 * 669 * @param[in] ep Endpoint number. 670 * For an IN endpoint, sending is initiated. 671 * For an OUT endpoint, receiving is initiated. 672 * @param[in] p_handler Transfer handler - feeder for IN direction and consumer for 673 * OUT direction. 674 * 675 * @retval NRFX_SUCCESS Transfer queued or started. 676 * @retval NRFX_ERROR_BUSY Selected endpoint is pending. 677 * @retval NRFX_ERROR_INVALID_ADDR Unexpected transfer on EPIN0 or EPOUT0. 678 */ 679 nrfx_err_t nrfx_usbd_ep_handled_transfer(nrfx_usbd_ep_t ep, 680 nrfx_usbd_handler_desc_t const * p_handler); 681 682 /** 683 * @brief Get the temporary buffer to be used by the feeder. 684 * 685 * This buffer is used for TX transfers and it can be reused automatically 686 * when the transfer is finished. 687 * Use it for transfer preparation. 688 * 689 * May be used inside the feeder configured in @ref nrfx_usbd_ep_handled_transfer. 690 * 691 * @return Pointer to the buffer that can be used temporarily. 692 * 693 * @sa NRFX_USBD_FEEDER_BUFFER_SIZE 694 */ 695 void * nrfx_usbd_feeder_buffer_get(void); 696 697 /** 698 * @brief Get the information about last finished or current transfer. 699 * 700 * Function returns the status of the last buffer set for transfer on selected endpoint. 701 * The status considers last buffer set by @ref nrfx_usbd_ep_transfer function or 702 * by transfer callback function. 703 * 704 * @param[in] ep Endpoint number. 705 * @param[out] p_size Information about the current/last transfer size. 706 * 707 * @return Endpoint status. 708 * 709 * @sa nrfx_usbd_ep_status_t 710 */ 711 nrfx_usbd_ep_status_t nrfx_usbd_ep_status_get(nrfx_usbd_ep_t ep, size_t * p_size); 712 713 /** 714 * @brief Get number of received bytes. 715 * 716 * Get the number of received bytes. 717 * The function behavior is undefined when called on IN endpoint. 718 * 719 * @param[in] ep Endpoint number. 720 * 721 * @return Number of received bytes. 722 */ 723 size_t nrfx_usbd_epout_size_get(nrfx_usbd_ep_t ep); 724 725 /** 726 * @brief Check if endpoint buffer is ready or is under USB IP control. 727 * 728 * Function to test if endpoint is busy. 729 * Endpoint that is busy cannot be accessed by MCU. 730 * It means that: 731 * - OUT (TX) endpoint: Last uploaded data is still in endpoint and is waiting 732 * to be received by the host. 733 * - IN (RX) endpoint: Endpoint is ready to receive data from the host 734 * and the endpoint does not have any data. 735 * When endpoint is not busy: 736 * - OUT (TX) endpoint: New data can be uploaded. 737 * - IN (RX) endpoint: New data can be downloaded using @ref nrfx_usbd_ep_transfer 738 * function. 739 * 740 * @param[in] ep Endpoint number. 741 * 742 * @retval false Endpoint is not busy. 743 * @retval true Endpoint is busy. 744 */ 745 bool nrfx_usbd_ep_is_busy(nrfx_usbd_ep_t ep); 746 747 /** 748 * @brief Stall endpoint 749 * 750 * Stall endpoit to send error information during next transfer request from 751 * the host. 752 * 753 * @note To stall endpoint it is safer to use @ref nrfx_usbd_setup_stall 754 * @note Stalled endpoint would not be cleared when DMA transfer finishes. 755 * 756 * @param[in] ep Endpoint number to stall. 757 */ 758 void nrfx_usbd_ep_stall(nrfx_usbd_ep_t ep); 759 760 /** 761 * @brief Clear stall flag on endpoint. 762 * 763 * This function clears endpoint that is stalled. 764 * @note 765 * If it is OUT endpoint (receiving) it would be also prepared for reception. 766 * It means that busy flag would be set. 767 * @note 768 * In endpoint (transmitting) would not be cleared - it gives possibility to 769 * write new data before transmitting. 770 * 771 * @param[in] ep Endpoint number. 772 */ 773 void nrfx_usbd_ep_stall_clear(nrfx_usbd_ep_t ep); 774 775 /** 776 * @brief Check if endpoint is stalled. 777 * 778 * This function gets stall state of selected endpoint. 779 * 780 * @param[in] ep Endpoint number to check. 781 * 782 * @retval false Endpoint is not stalled. 783 * @retval true Endpoint is stalled. 784 */ 785 bool nrfx_usbd_ep_stall_check(nrfx_usbd_ep_t ep); 786 787 /** 788 * @brief Clear current endpoint data toggle. 789 * 790 * @param[in] ep Endpoint number to clear. 791 */ 792 void nrfx_usbd_ep_dtoggle_clear(nrfx_usbd_ep_t ep); 793 794 /** 795 * @brief Get parsed setup data. 796 * 797 * Function fills the parsed setup data structure. 798 * 799 * @param[out] p_setup Pointer to data structure that would be filled by 800 * parsed data. 801 */ 802 void nrfx_usbd_setup_get(nrfx_usbd_setup_t * p_setup); 803 804 /** 805 * @brief Clear the control endpoint for packet reception during DATA stage. 806 * 807 * This function may be called if any more data in control write transfer is expected. 808 * Clears only OUT endpoint to be able to take another OUT data token. 809 * It does not allow STATUS stage. 810 * @sa nrfx_usbd_setup_clear 811 */ 812 void nrfx_usbd_setup_data_clear(void); 813 814 /** 815 * @brief Clear setup endpoint. 816 * 817 * This function acknowledges setup when SETUP command was received and processed. 818 * It has to be called if no data respond for the SETUP command is sent. 819 */ 820 void nrfx_usbd_setup_clear(void); 821 822 /** 823 * @brief Stall setup endpoint. 824 * 825 * Mark an error on setup endpoint. 826 */ 827 void nrfx_usbd_setup_stall(void); 828 829 /** 830 * @brief Abort pending transfer on selected endpoint. 831 * 832 * @param[in] ep Endpoint number. 833 */ 834 void nrfx_usbd_ep_abort(nrfx_usbd_ep_t ep); 835 836 /** 837 * @brief Get the information about expected transfer SETUP data direction. 838 * 839 * Function returns the information about last expected transfer direction. 840 * 841 * @retval NRFX_USBD_EPOUT0 Expecting OUT (Host->Device) direction or no data. 842 * @retval NRFX_USBD_EPIN0 Expecting IN (Device->Host) direction. 843 */ 844 nrfx_usbd_ep_t nrfx_usbd_last_setup_dir_get(void); 845 846 /** 847 * @brief Drop transfer on OUT endpoint. 848 * 849 * @param[in] ep OUT endpoint ID. 850 */ 851 void nrfx_usbd_transfer_out_drop(nrfx_usbd_ep_t ep); 852 853 854 void nrfx_usbd_irq_handler(void); 855 856 857 /** @} */ 858 859 #ifdef __cplusplus 860 } 861 #endif 862 863 #endif // NRFX_USBD_H__ 864