1 /* SPDX-License-Identifier: BSD-3-Clause */ 2 3 /* 4 * LPCUSB, an USB device driver for LPC microcontrollers 5 * Copyright (C) 2006 Bertrik Sikken (bertrik@sikken.nl) 6 * Copyright (c) 2016 Intel Corporation 7 * 8 * Redistribution and use in source and binary forms, with or without 9 * modification, are permitted provided that the following conditions are met: 10 * 11 * 1. Redistributions of source code must retain the above copyright 12 * notice, this list of conditions and the following disclaimer. 13 * 2. Redistributions in binary form must reproduce the above copyright 14 * notice, this list of conditions and the following disclaimer in the 15 * documentation and/or other materials provided with the distribution. 16 * 3. The name of the author may not be used to endorse or promote products 17 * derived from this software without specific prior written permission. 18 * 19 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 20 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 21 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 22 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 23 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 24 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 25 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 26 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 27 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 28 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29 */ 30 31 /** 32 * @file 33 * @brief USB device core layer APIs and structures 34 * 35 * This file contains the USB device core layer APIs and structures. 36 */ 37 38 #ifndef ZEPHYR_INCLUDE_USB_USB_DEVICE_H_ 39 #define ZEPHYR_INCLUDE_USB_USB_DEVICE_H_ 40 41 #include <zephyr/drivers/usb/usb_dc.h> 42 #include <zephyr/usb/usb_ch9.h> 43 #include <zephyr/logging/log.h> 44 #include <zephyr/sys/iterable_sections.h> 45 46 #ifdef __cplusplus 47 extern "C" { 48 #endif 49 50 /* 51 * These macros should be used to place the USB descriptors 52 * in predetermined order in the RAM. 53 */ 54 #define USBD_DEVICE_DESCR_DEFINE(p) \ 55 static __in_section(usb, descriptor_##p, 0) __used __aligned(1) 56 #define USBD_CLASS_DESCR_DEFINE(p, instance) \ 57 static __in_section(usb, descriptor_##p.1, instance) __used __aligned(1) 58 #define USBD_MISC_DESCR_DEFINE(p) \ 59 static __in_section(usb, descriptor_##p, 2) __used __aligned(1) 60 #define USBD_USER_DESCR_DEFINE(p) \ 61 static __in_section(usb, descriptor_##p, 3) __used __aligned(1) 62 #define USBD_STRING_DESCR_DEFINE(p) \ 63 static __in_section(usb, descriptor_##p, 4) __used __aligned(1) 64 #define USBD_STRING_DESCR_USER_DEFINE(p) \ 65 static __in_section(usb, descriptor_##p, 5) __used __aligned(1) 66 #define USBD_TERM_DESCR_DEFINE(p) \ 67 static __in_section(usb, descriptor_##p, 6) __used __aligned(1) 68 69 /* 70 * This macro should be used to place the struct usb_cfg_data 71 * inside usb data section in the RAM. 72 */ 73 #define USBD_DEFINE_CFG_DATA(name) \ 74 static STRUCT_SECTION_ITERABLE(usb_cfg_data, name) 75 76 #define USBD_CFG_DATA_DEFINE(p, name) __DEPRECATED_MACRO \ 77 static __in_section(_usb_cfg_data, static, p##_name) __used __aligned(4) 78 79 /************************************************************************* 80 * USB configuration 81 **************************************************************************/ 82 83 #define USB_MAX_CTRL_MPS 64 /**< maximum packet size (MPS) for EP 0 */ 84 #define USB_MAX_FS_BULK_MPS 64 /**< full speed MPS for bulk EP */ 85 #define USB_MAX_FS_INT_MPS 64 /**< full speed MPS for interrupt EP */ 86 #define USB_MAX_FS_ISO_MPS 1023 /**< full speed MPS for isochronous EP */ 87 88 /************************************************************************* 89 * USB application interface 90 **************************************************************************/ 91 92 /** 93 * @brief USB Device Core Layer API 94 * @defgroup _usb_device_core_api USB Device Core API 95 * @since 1.5 96 * @version 1.0.0 97 * @{ 98 */ 99 100 /** 101 * @brief Callback function signature for the USB Endpoint status 102 */ 103 typedef void (*usb_ep_callback)(uint8_t ep, 104 enum usb_dc_ep_cb_status_code cb_status); 105 106 /** 107 * @brief Callback function signature for class specific requests 108 * 109 * Function which handles Class specific requests corresponding to an 110 * interface number specified in the device descriptor table. For host 111 * to device direction the 'len' and 'payload_data' contain the length 112 * of the received data and the pointer to the received data respectively. 113 * For device to host class requests, 'len' and 'payload_data' should be 114 * set by the callback function with the length and the address of the 115 * data to be transmitted buffer respectively. 116 */ 117 typedef int (*usb_request_handler)(struct usb_setup_packet *setup, 118 int32_t *transfer_len, uint8_t **payload_data); 119 120 /** 121 * @brief Function for interface runtime configuration 122 */ 123 typedef void (*usb_interface_config)(struct usb_desc_header *head, 124 uint8_t bInterfaceNumber); 125 126 /** 127 * @brief USB Endpoint Configuration 128 * 129 * This structure contains configuration for the endpoint. 130 */ 131 struct usb_ep_cfg_data { 132 /** 133 * Callback function for notification of data received and 134 * available to application or transmit done, NULL if callback 135 * not required by application code 136 */ 137 usb_ep_callback ep_cb; 138 /** 139 * The number associated with the EP in the device configuration 140 * structure 141 * IN EP = 0x80 | \<endpoint number\> 142 * OUT EP = 0x00 | \<endpoint number\> 143 */ 144 uint8_t ep_addr; 145 }; 146 147 /** 148 * @brief USB Interface Configuration 149 * 150 * This structure contains USB interface configuration. 151 */ 152 struct usb_interface_cfg_data { 153 /** Handler for USB Class specific Control (EP 0) communications */ 154 usb_request_handler class_handler; 155 /** Handler for USB Vendor specific commands */ 156 usb_request_handler vendor_handler; 157 /** 158 * The custom request handler gets a first chance at handling 159 * the request before it is handed over to the 'chapter 9' request 160 * handler. 161 * return 0 on success, -EINVAL if the request has not been handled by 162 * the custom handler and instead needs to be handled by the 163 * core USB stack. Any other error code to denote failure within 164 * the custom handler. 165 */ 166 usb_request_handler custom_handler; 167 }; 168 169 /** 170 * @brief USB device configuration 171 * 172 * The Application instantiates this with given parameters added 173 * using the "usb_set_config" function. Once this function is called 174 * changes to this structure will result in undefined behavior. This structure 175 * may only be updated after calls to usb_deconfig 176 */ 177 struct usb_cfg_data { 178 /** 179 * USB device description, see 180 * http://www.beyondlogic.org/usbnutshell/usb5.shtml#DeviceDescriptors 181 */ 182 const uint8_t *usb_device_description; 183 /** Pointer to interface descriptor */ 184 void *interface_descriptor; 185 /** Function for interface runtime configuration */ 186 usb_interface_config interface_config; 187 /** Callback to be notified on USB connection status change */ 188 void (*cb_usb_status)(struct usb_cfg_data *cfg, 189 enum usb_dc_status_code cb_status, 190 const uint8_t *param); 191 /** USB interface (Class) handler and storage space */ 192 struct usb_interface_cfg_data interface; 193 /** Number of individual endpoints in the device configuration */ 194 uint8_t num_endpoints; 195 /** 196 * Pointer to an array of endpoint structs of length equal to the 197 * number of EP associated with the device description, 198 * not including control endpoints 199 */ 200 struct usb_ep_cfg_data *endpoint; 201 }; 202 203 /** 204 * @brief Configure USB controller 205 * 206 * Function to configure USB controller. 207 * Configuration parameters must be valid or an error is returned 208 * 209 * @param[in] usb_descriptor USB descriptor table 210 * 211 * @return 0 on success, negative errno code on fail 212 */ 213 int usb_set_config(const uint8_t *usb_descriptor); 214 215 /** 216 * @brief Deconfigure USB controller 217 * 218 * This function returns the USB device to it's initial state 219 * 220 * @return 0 on success, negative errno code on fail 221 */ 222 int usb_deconfig(void); 223 224 /** 225 * @brief Enable the USB subsystem and associated hardware 226 * 227 * This function initializes the USB core subsystem and enables the 228 * corresponding hardware so that it can begin transmitting and receiving 229 * on the USB bus, as well as generating interrupts. 230 * 231 * Class-specific initialization and registration must be performed by the user 232 * before invoking this, so that any data or events on the bus are processed 233 * correctly by the associated class handling code. 234 * 235 * @param[in] status_cb Callback registered by user to notify 236 * about USB device controller state. 237 * 238 * @return 0 on success, negative errno code on fail. 239 */ 240 int usb_enable(usb_dc_status_callback status_cb); 241 242 /** 243 * @brief Disable the USB device 244 * 245 * Function to disable the USB device. 246 * Upon success, the specified USB interface is clock gated in hardware, 247 * it is no longer capable of generating interrupts. 248 * 249 * @return 0 on success, negative errno code on fail 250 */ 251 int usb_disable(void); 252 253 /** 254 * @brief Write data to the specified endpoint 255 * 256 * Function to write data to the specified endpoint. The supplied 257 * usb_ep_callback will be called when transmission is done. 258 * 259 * @param[in] ep Endpoint address corresponding to the one listed in the 260 * device configuration table 261 * @param[in] data Pointer to data to write 262 * @param[in] data_len Length of data requested to write. This may be zero for 263 * a zero length status packet. 264 * @param[out] bytes_ret Bytes written to the EP FIFO. This value may be NULL if 265 * the application expects all bytes to be written 266 * 267 * @return 0 on success, negative errno code on fail 268 */ 269 int usb_write(uint8_t ep, const uint8_t *data, uint32_t data_len, uint32_t *bytes_ret); 270 271 /** 272 * @brief Read data from the specified endpoint 273 * 274 * This function is called by the Endpoint handler function, after an 275 * OUT interrupt has been received for that EP. The application must 276 * only call this function through the supplied usb_ep_callback function. 277 * 278 * @param[in] ep Endpoint address corresponding to the one listed in 279 * the device configuration table 280 * @param[in] data Pointer to data buffer to write to 281 * @param[in] max_data_len Max length of data to read 282 * @param[out] ret_bytes Number of bytes read. If data is NULL and 283 * max_data_len is 0 the number of bytes available 284 * for read is returned. 285 * 286 * @return 0 on success, negative errno code on fail 287 */ 288 int usb_read(uint8_t ep, uint8_t *data, uint32_t max_data_len, uint32_t *ret_bytes); 289 290 /** 291 * @brief Set STALL condition on the specified endpoint 292 * 293 * This function is called by USB device class handler code to set stall 294 * condition on endpoint. 295 * 296 * @param[in] ep Endpoint address corresponding to the one listed in 297 * the device configuration table 298 * 299 * @return 0 on success, negative errno code on fail 300 */ 301 int usb_ep_set_stall(uint8_t ep); 302 303 /** 304 * @brief Clears STALL condition on the specified endpoint 305 * 306 * This function is called by USB device class handler code to clear stall 307 * condition on endpoint. 308 * 309 * @param[in] ep Endpoint address corresponding to the one listed in 310 * the device configuration table 311 * 312 * @return 0 on success, negative errno code on fail 313 */ 314 int usb_ep_clear_stall(uint8_t ep); 315 316 /** 317 * @brief Read data from the specified endpoint 318 * 319 * This is similar to usb_ep_read, the difference being that, it doesn't 320 * clear the endpoint NAKs so that the consumer is not bogged down by further 321 * upcalls till he is done with the processing of the data. The caller should 322 * reactivate ep by invoking usb_ep_read_continue() do so. 323 * 324 * @param[in] ep Endpoint address corresponding to the one 325 * listed in the device configuration table 326 * @param[in] data pointer to data buffer to write to 327 * @param[in] max_data_len max length of data to read 328 * @param[out] read_bytes Number of bytes read. If data is NULL and 329 * max_data_len is 0 the number of bytes 330 * available for read should be returned. 331 * 332 * @return 0 on success, negative errno code on fail. 333 */ 334 int usb_ep_read_wait(uint8_t ep, uint8_t *data, uint32_t max_data_len, 335 uint32_t *read_bytes); 336 337 338 /** 339 * @brief Continue reading data from the endpoint 340 * 341 * Clear the endpoint NAK and enable the endpoint to accept more data 342 * from the host. Usually called after usb_ep_read_wait() when the consumer 343 * is fine to accept more data. Thus these calls together acts as flow control 344 * mechanism. 345 * 346 * @param[in] ep Endpoint address corresponding to the one 347 * listed in the device configuration table 348 * 349 * @return 0 on success, negative errno code on fail. 350 */ 351 int usb_ep_read_continue(uint8_t ep); 352 353 /** 354 * Callback function signature for transfer completion. 355 */ 356 typedef void (*usb_transfer_callback)(uint8_t ep, int tsize, void *priv); 357 358 /* USB transfer flags */ 359 #define USB_TRANS_READ BIT(0) /** Read transfer flag */ 360 #define USB_TRANS_WRITE BIT(1) /** Write transfer flag */ 361 #define USB_TRANS_NO_ZLP BIT(2) /** No zero-length packet flag */ 362 363 /** 364 * @brief Transfer management endpoint callback 365 * 366 * If a USB class driver wants to use high-level transfer functions, driver 367 * needs to register this callback as usb endpoint callback. 368 */ 369 void usb_transfer_ep_callback(uint8_t ep, enum usb_dc_ep_cb_status_code); 370 371 /** 372 * @brief Start a transfer 373 * 374 * Start a usb transfer to/from the data buffer. This function is asynchronous 375 * and can be executed in IRQ context. The provided callback will be called 376 * on transfer completion (or error) in thread context. 377 * 378 * @param[in] ep Endpoint address corresponding to the one 379 * listed in the device configuration table 380 * @param[in] data Pointer to data buffer to write-to/read-from 381 * @param[in] dlen Size of data buffer 382 * @param[in] flags Transfer flags (USB_TRANS_READ, USB_TRANS_WRITE...) 383 * @param[in] cb Function called on transfer completion/failure 384 * @param[in] priv Data passed back to the transfer completion callback 385 * 386 * @return 0 on success, negative errno code on fail. 387 */ 388 int usb_transfer(uint8_t ep, uint8_t *data, size_t dlen, unsigned int flags, 389 usb_transfer_callback cb, void *priv); 390 391 /** 392 * @brief Start a transfer and block-wait for completion 393 * 394 * Synchronous version of usb_transfer, wait for transfer completion before 395 * returning. 396 * A return value of zero can also mean that transfer was cancelled or that the 397 * endpoint is not ready. This is due to the design of transfers and usb_dc API. 398 * 399 * @param[in] ep Endpoint address corresponding to the one 400 * listed in the device configuration table 401 * @param[in] data Pointer to data buffer to write-to/read-from 402 * @param[in] dlen Size of data buffer 403 * @param[in] flags Transfer flags 404 * 405 * @return number of bytes transferred on success, negative errno code on fail. 406 */ 407 int usb_transfer_sync(uint8_t ep, uint8_t *data, size_t dlen, unsigned int flags); 408 409 /** 410 * @brief Cancel any ongoing transfer on the specified endpoint 411 * 412 * @param[in] ep Endpoint address corresponding to the one 413 * listed in the device configuration table 414 */ 415 void usb_cancel_transfer(uint8_t ep); 416 417 /** 418 * @brief Cancel all ongoing transfers 419 */ 420 void usb_cancel_transfers(void); 421 422 /** 423 * @brief Check that transfer is ongoing for the endpoint 424 * 425 * @param[in] ep Endpoint address corresponding to the one 426 * listed in the device configuration table 427 * 428 * @return true if transfer is ongoing, false otherwise. 429 */ 430 bool usb_transfer_is_busy(uint8_t ep); 431 432 /** 433 * @brief Start the USB remote wakeup procedure 434 * 435 * Function to request a remote wakeup. 436 * This feature must be enabled in configuration, otherwise 437 * it will always return -ENOTSUP error. 438 * 439 * @return 0 on success, negative errno code on fail, 440 * i.e. when the bus is already active. 441 */ 442 int usb_wakeup_request(void); 443 444 /** 445 * @brief Get status of the USB remote wakeup feature 446 * 447 * @return true if remote wakeup has been enabled by the host, false otherwise. 448 */ 449 bool usb_get_remote_wakeup_status(void); 450 451 /** 452 * @brief Helper macro to place the BOS compatibility descriptor 453 * in the right memory section. 454 */ 455 #define USB_DEVICE_BOS_DESC_DEFINE_CAP \ 456 static __in_section(usb, bos_desc_area, 1) __aligned(1) __used 457 458 /** 459 * @brief Register BOS capability descriptor 460 * 461 * This function should be used by the application to register BOS capability 462 * descriptors before the USB device stack is enabled. 463 * 464 * @param[in] hdr Pointer to BOS capability descriptor 465 */ 466 void usb_bos_register_cap(void *hdr); 467 468 /** 469 * @} 470 */ 471 472 #ifdef __cplusplus 473 } 474 #endif 475 476 #endif /* ZEPHYR_INCLUDE_USB_USB_DEVICE_H_ */ 477
