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 * @{ 96 */ 97 98 /** 99 * @brief Callback function signature for the USB Endpoint status 100 */ 101 typedef void (*usb_ep_callback)(uint8_t ep, 102 enum usb_dc_ep_cb_status_code cb_status); 103 104 /** 105 * @brief Callback function signature for class specific requests 106 * 107 * Function which handles Class specific requests corresponding to an 108 * interface number specified in the device descriptor table. For host 109 * to device direction the 'len' and 'payload_data' contain the length 110 * of the received data and the pointer to the received data respectively. 111 * For device to host class requests, 'len' and 'payload_data' should be 112 * set by the callback function with the length and the address of the 113 * data to be transmitted buffer respectively. 114 */ 115 typedef int (*usb_request_handler)(struct usb_setup_packet *setup, 116 int32_t *transfer_len, uint8_t **payload_data); 117 118 /** 119 * @brief Function for interface runtime configuration 120 */ 121 typedef void (*usb_interface_config)(struct usb_desc_header *head, 122 uint8_t bInterfaceNumber); 123 124 /** 125 * @brief USB Endpoint Configuration 126 * 127 * This structure contains configuration for the endpoint. 128 */ 129 struct usb_ep_cfg_data { 130 /** 131 * Callback function for notification of data received and 132 * available to application or transmit done, NULL if callback 133 * not required by application code 134 */ 135 usb_ep_callback ep_cb; 136 /** 137 * The number associated with the EP in the device configuration 138 * structure 139 * IN EP = 0x80 | \<endpoint number\> 140 * OUT EP = 0x00 | \<endpoint number\> 141 */ 142 uint8_t ep_addr; 143 }; 144 145 /** 146 * @brief USB Interface Configuration 147 * 148 * This structure contains USB interface configuration. 149 */ 150 struct usb_interface_cfg_data { 151 /** Handler for USB Class specific Control (EP 0) communications */ 152 usb_request_handler class_handler; 153 /** Handler for USB Vendor specific commands */ 154 usb_request_handler vendor_handler; 155 /** 156 * The custom request handler gets a first chance at handling 157 * the request before it is handed over to the 'chapter 9' request 158 * handler. 159 * return 0 on success, -EINVAL if the request has not been handled by 160 * the custom handler and instead needs to be handled by the 161 * core USB stack. Any other error code to denote failure within 162 * the custom handler. 163 */ 164 usb_request_handler custom_handler; 165 }; 166 167 /** 168 * @brief USB device configuration 169 * 170 * The Application instantiates this with given parameters added 171 * using the "usb_set_config" function. Once this function is called 172 * changes to this structure will result in undefined behavior. This structure 173 * may only be updated after calls to usb_deconfig 174 */ 175 struct usb_cfg_data { 176 /** 177 * USB device description, see 178 * http://www.beyondlogic.org/usbnutshell/usb5.shtml#DeviceDescriptors 179 */ 180 const uint8_t *usb_device_description; 181 /** Pointer to interface descriptor */ 182 void *interface_descriptor; 183 /** Function for interface runtime configuration */ 184 usb_interface_config interface_config; 185 /** Callback to be notified on USB connection status change */ 186 void (*cb_usb_status)(struct usb_cfg_data *cfg, 187 enum usb_dc_status_code cb_status, 188 const uint8_t *param); 189 /** USB interface (Class) handler and storage space */ 190 struct usb_interface_cfg_data interface; 191 /** Number of individual endpoints in the device configuration */ 192 uint8_t num_endpoints; 193 /** 194 * Pointer to an array of endpoint structs of length equal to the 195 * number of EP associated with the device description, 196 * not including control endpoints 197 */ 198 struct usb_ep_cfg_data *endpoint; 199 }; 200 201 /** 202 * @brief Configure USB controller 203 * 204 * Function to configure USB controller. 205 * Configuration parameters must be valid or an error is returned 206 * 207 * @param[in] usb_descriptor USB descriptor table 208 * 209 * @return 0 on success, negative errno code on fail 210 */ 211 int usb_set_config(const uint8_t *usb_descriptor); 212 213 /** 214 * @brief Deconfigure USB controller 215 * 216 * This function returns the USB device to it's initial state 217 * 218 * @return 0 on success, negative errno code on fail 219 */ 220 int usb_deconfig(void); 221 222 /** 223 * @brief Enable the USB subsystem and associated hardware 224 * 225 * This function initializes the USB core subsystem and enables the 226 * corresponding hardware so that it can begin transmitting and receiving 227 * on the USB bus, as well as generating interrupts. 228 * 229 * Class-specific initialization and registration must be performed by the user 230 * before invoking this, so that any data or events on the bus are processed 231 * correctly by the associated class handling code. 232 * 233 * @param[in] status_cb Callback registered by user to notify 234 * about USB device controller state. 235 * 236 * @return 0 on success, negative errno code on fail. 237 */ 238 int usb_enable(usb_dc_status_callback status_cb); 239 240 /** 241 * @brief Disable the USB device 242 * 243 * Function to disable the USB device. 244 * Upon success, the specified USB interface is clock gated in hardware, 245 * it is no longer capable of generating interrupts. 246 * 247 * @return 0 on success, negative errno code on fail 248 */ 249 int usb_disable(void); 250 251 /** 252 * @brief Write data to the specified endpoint 253 * 254 * Function to write data to the specified endpoint. The supplied 255 * usb_ep_callback will be called when transmission is done. 256 * 257 * @param[in] ep Endpoint address corresponding to the one listed in the 258 * device configuration table 259 * @param[in] data Pointer to data to write 260 * @param[in] data_len Length of data requested to write. This may be zero for 261 * a zero length status packet. 262 * @param[out] bytes_ret Bytes written to the EP FIFO. This value may be NULL if 263 * the application expects all bytes to be written 264 * 265 * @return 0 on success, negative errno code on fail 266 */ 267 int usb_write(uint8_t ep, const uint8_t *data, uint32_t data_len, uint32_t *bytes_ret); 268 269 /** 270 * @brief Read data from the specified endpoint 271 * 272 * This function is called by the Endpoint handler function, after an 273 * OUT interrupt has been received for that EP. The application must 274 * only call this function through the supplied usb_ep_callback function. 275 * 276 * @param[in] ep Endpoint address corresponding to the one listed in 277 * the device configuration table 278 * @param[in] data Pointer to data buffer to write to 279 * @param[in] max_data_len Max length of data to read 280 * @param[out] ret_bytes Number of bytes read. If data is NULL and 281 * max_data_len is 0 the number of bytes available 282 * for read is returned. 283 * 284 * @return 0 on success, negative errno code on fail 285 */ 286 int usb_read(uint8_t ep, uint8_t *data, uint32_t max_data_len, uint32_t *ret_bytes); 287 288 /** 289 * @brief Set STALL condition on the specified endpoint 290 * 291 * This function is called by USB device class handler code to set stall 292 * condition on endpoint. 293 * 294 * @param[in] ep Endpoint address corresponding to the one listed in 295 * the device configuration table 296 * 297 * @return 0 on success, negative errno code on fail 298 */ 299 int usb_ep_set_stall(uint8_t ep); 300 301 /** 302 * @brief Clears STALL condition on the specified endpoint 303 * 304 * This function is called by USB device class handler code to clear stall 305 * condition on endpoint. 306 * 307 * @param[in] ep Endpoint address corresponding to the one listed in 308 * the device configuration table 309 * 310 * @return 0 on success, negative errno code on fail 311 */ 312 int usb_ep_clear_stall(uint8_t ep); 313 314 /** 315 * @brief Read data from the specified endpoint 316 * 317 * This is similar to usb_ep_read, the difference being that, it doesn't 318 * clear the endpoint NAKs so that the consumer is not bogged down by further 319 * upcalls till he is done with the processing of the data. The caller should 320 * reactivate ep by invoking usb_ep_read_continue() do so. 321 * 322 * @param[in] ep Endpoint address corresponding to the one 323 * listed in the device configuration table 324 * @param[in] data pointer to data buffer to write to 325 * @param[in] max_data_len max length of data to read 326 * @param[out] read_bytes Number of bytes read. If data is NULL and 327 * max_data_len is 0 the number of bytes 328 * available for read should be returned. 329 * 330 * @return 0 on success, negative errno code on fail. 331 */ 332 int usb_ep_read_wait(uint8_t ep, uint8_t *data, uint32_t max_data_len, 333 uint32_t *read_bytes); 334 335 336 /** 337 * @brief Continue reading data from the endpoint 338 * 339 * Clear the endpoint NAK and enable the endpoint to accept more data 340 * from the host. Usually called after usb_ep_read_wait() when the consumer 341 * is fine to accept more data. Thus these calls together acts as flow control 342 * mechanism. 343 * 344 * @param[in] ep Endpoint address corresponding to the one 345 * listed in the device configuration table 346 * 347 * @return 0 on success, negative errno code on fail. 348 */ 349 int usb_ep_read_continue(uint8_t ep); 350 351 /** 352 * Callback function signature for transfer completion. 353 */ 354 typedef void (*usb_transfer_callback)(uint8_t ep, int tsize, void *priv); 355 356 /* USB transfer flags */ 357 #define USB_TRANS_READ BIT(0) /** Read transfer flag */ 358 #define USB_TRANS_WRITE BIT(1) /** Write transfer flag */ 359 #define USB_TRANS_NO_ZLP BIT(2) /** No zero-length packet flag */ 360 361 /** 362 * @brief Transfer management endpoint callback 363 * 364 * If a USB class driver wants to use high-level transfer functions, driver 365 * needs to register this callback as usb endpoint callback. 366 */ 367 void usb_transfer_ep_callback(uint8_t ep, enum usb_dc_ep_cb_status_code); 368 369 /** 370 * @brief Start a transfer 371 * 372 * Start a usb transfer to/from the data buffer. This function is asynchronous 373 * and can be executed in IRQ context. The provided callback will be called 374 * on transfer completion (or error) in thread context. 375 * 376 * @param[in] ep Endpoint address corresponding to the one 377 * listed in the device configuration table 378 * @param[in] data Pointer to data buffer to write-to/read-from 379 * @param[in] dlen Size of data buffer 380 * @param[in] flags Transfer flags (USB_TRANS_READ, USB_TRANS_WRITE...) 381 * @param[in] cb Function called on transfer completion/failure 382 * @param[in] priv Data passed back to the transfer completion callback 383 * 384 * @return 0 on success, negative errno code on fail. 385 */ 386 int usb_transfer(uint8_t ep, uint8_t *data, size_t dlen, unsigned int flags, 387 usb_transfer_callback cb, void *priv); 388 389 /** 390 * @brief Start a transfer and block-wait for completion 391 * 392 * Synchronous version of usb_transfer, wait for transfer completion before 393 * returning. 394 * A return value of zero can also mean that transfer was cancelled or that the 395 * endpoint is not ready. This is due to the design of transfers and usb_dc API. 396 * 397 * @param[in] ep Endpoint address corresponding to the one 398 * listed in the device configuration table 399 * @param[in] data Pointer to data buffer to write-to/read-from 400 * @param[in] dlen Size of data buffer 401 * @param[in] flags Transfer flags 402 * 403 * @return number of bytes transferred on success, negative errno code on fail. 404 */ 405 int usb_transfer_sync(uint8_t ep, uint8_t *data, size_t dlen, unsigned int flags); 406 407 /** 408 * @brief Cancel any ongoing transfer on the specified endpoint 409 * 410 * @param[in] ep Endpoint address corresponding to the one 411 * listed in the device configuration table 412 */ 413 void usb_cancel_transfer(uint8_t ep); 414 415 /** 416 * @brief Cancel all ongoing transfers 417 */ 418 void usb_cancel_transfers(void); 419 420 /** 421 * @brief Check that transfer is ongoing for the endpoint 422 * 423 * @param[in] ep Endpoint address corresponding to the one 424 * listed in the device configuration table 425 * 426 * @return true if transfer is ongoing, false otherwise. 427 */ 428 bool usb_transfer_is_busy(uint8_t ep); 429 430 /** 431 * @brief Start the USB remote wakeup procedure 432 * 433 * Function to request a remote wakeup. 434 * This feature must be enabled in configuration, otherwise 435 * it will always return -ENOTSUP error. 436 * 437 * @return 0 on success, negative errno code on fail, 438 * i.e. when the bus is already active. 439 */ 440 int usb_wakeup_request(void); 441 442 /** 443 * @brief Get status of the USB remote wakeup feature 444 * 445 * @return true if remote wakeup has been enabled by the host, false otherwise. 446 */ 447 bool usb_get_remote_wakeup_status(void); 448 449 /** 450 * @brief Helper macro to place the BOS compatibility descriptor 451 * in the right memory section. 452 */ 453 #define USB_DEVICE_BOS_DESC_DEFINE_CAP \ 454 static __in_section(usb, bos_desc_area, 1) __aligned(1) __used 455 456 /** 457 * @brief Register BOS capability descriptor 458 * 459 * This function should be used by the application to register BOS capability 460 * descriptors before the USB device stack is enabled. 461 * 462 * @param[in] hdr Pointer to BOS capability descriptor 463 */ 464 void usb_bos_register_cap(void *hdr); 465 466 /** 467 * @} 468 */ 469 470 #ifdef __cplusplus 471 } 472 #endif 473 474 #endif /* ZEPHYR_INCLUDE_USB_USB_DEVICE_H_ */ 475
