1 /* 2 * SPDX-FileCopyrightText: 2006 Bertrik Sikken (bertrik@sikken.nl) 3 * SPDX-FileContributor: 2016 Intel Corporation 4 * 5 * SPDX-License-Identifier: BSD-3-Clause 6 * 7 * LPCUSB, an USB device driver for LPC microcontrollers 8 */ 9 10 /** 11 * @file 12 * @brief USB device core layer APIs and structures 13 * 14 * This file contains the USB device core layer APIs and structures. 15 */ 16 17 #pragma once 18 19 #include <stddef.h> 20 #include <sys/cdefs.h> 21 #include "usb_dc.h" 22 #include "esp_assert.h" 23 24 #ifdef __cplusplus 25 extern "C" { 26 #endif 27 28 /************************************************************************* 29 * USB configuration 30 **************************************************************************/ 31 32 #define MAX_PACKET_SIZE0 64 /**< maximum packet size for EP 0 */ 33 //Note: for FS this should be 8, 16, 32, 64 bytes. HS can go up to 512. 34 35 /************************************************************************* 36 * USB application interface 37 **************************************************************************/ 38 39 /** setup packet definitions */ 40 struct usb_setup_packet { 41 uint8_t bmRequestType; /**< characteristics of the specific request */ 42 uint8_t bRequest; /**< specific request */ 43 uint16_t wValue; /**< request specific parameter */ 44 uint16_t wIndex; /**< request specific parameter */ 45 uint16_t wLength; /**< length of data transferred in data phase */ 46 } __packed; 47 48 49 ESP_STATIC_ASSERT(sizeof(struct usb_setup_packet) == 8, "USB setup packet struct size error"); 50 51 /** 52 * Callback function signature for the device 53 */ 54 typedef void (*usb_status_callback)(enum usb_dc_status_code status_code, 55 uint8_t *param); 56 57 /** 58 * Callback function signature for the USB Endpoint status 59 */ 60 typedef void (*usb_ep_callback)(uint8_t ep, 61 enum usb_dc_ep_cb_status_code cb_status); 62 63 /** 64 * Function which handles Class specific requests corresponding to an 65 * interface number specified in the device descriptor table 66 */ 67 typedef int (*usb_request_handler) (struct usb_setup_packet *detup, 68 int32_t *transfer_len, uint8_t **payload_data); 69 70 /** 71 * Function for interface runtime configuration 72 */ 73 typedef void (*usb_interface_config)(uint8_t bInterfaceNumber); 74 75 /* 76 * USB Endpoint Configuration 77 */ 78 struct usb_ep_cfg_data { 79 /** 80 * Callback function for notification of data received and 81 * available to application or transmit done, NULL if callback 82 * not required by application code 83 */ 84 usb_ep_callback ep_cb; 85 /** 86 * The number associated with the EP in the device configuration 87 * structure 88 * IN EP = 0x80 | \<endpoint number\> 89 * OUT EP = 0x00 | \<endpoint number\> 90 */ 91 uint8_t ep_addr; 92 }; 93 94 /** 95 * USB Interface Configuration 96 */ 97 struct usb_interface_cfg_data { 98 /** Handler for USB Class specific Control (EP 0) communications */ 99 usb_request_handler class_handler; 100 /** Handler for USB Vendor specific commands */ 101 usb_request_handler vendor_handler; 102 /** 103 * The custom request handler gets a first chance at handling 104 * the request before it is handed over to the 'chapter 9' request 105 * handler 106 */ 107 usb_request_handler custom_handler; 108 /** 109 * This data area, allocated by the application, is used to store 110 * Class specific command data and must be large enough to store the 111 * largest payload associated with the largest supported Class' 112 * command set. This data area may be used for USB IN or OUT 113 * communications 114 */ 115 uint8_t *payload_data; 116 /** 117 * This data area, allocated by the application, is used to store 118 * Vendor specific payload 119 */ 120 uint8_t *vendor_data; 121 }; 122 123 /* 124 * @brief USB device configuration 125 * 126 * The Application instantiates this with given parameters added 127 * using the "usb_set_config" function. Once this function is called 128 * changes to this structure will result in undefined behaviour. This structure 129 * may only be updated after calls to usb_deconfig 130 */ 131 struct usb_cfg_data { 132 /** 133 * USB device description, see 134 * http://www.beyondlogic.org/usbnutshell/usb5.shtml#DeviceDescriptors 135 */ 136 const uint8_t *usb_device_description; 137 /** Pointer to interface descriptor */ 138 const void *interface_descriptor; 139 /** Function for interface runtime configuration */ 140 usb_interface_config interface_config; 141 /** Callback to be notified on USB connection status change */ 142 usb_status_callback cb_usb_status; 143 /** USB interface (Class) handler and storage space */ 144 struct usb_interface_cfg_data interface; 145 /** Number of individual endpoints in the device configuration */ 146 uint8_t num_endpoints; 147 /** 148 * Pointer to an array of endpoint structs of length equal to the 149 * number of EP associated with the device description, 150 * not including control endpoints 151 */ 152 struct usb_ep_cfg_data *endpoint; 153 }; 154 155 /* 156 * @brief configure USB controller 157 * 158 * Function to configure USB controller. 159 * Configuration parameters must be valid or an error is returned 160 * 161 * @param[in] config Pointer to configuration structure 162 * 163 * @return 0 on success, negative errno code on fail 164 */ 165 int usb_set_config(struct usb_cfg_data *config); 166 167 /* 168 * @brief return the USB device to it's initial state 169 * 170 * @return 0 on success, negative errno code on fail 171 */ 172 int usb_deconfig(void); 173 174 /* 175 * @brief enable USB for host/device connection 176 * 177 * Function to enable USB for host/device connection. 178 * Upon success, the USB module is no longer clock gated in hardware, 179 * it is now capable of transmitting and receiving on the USB bus and 180 * of generating interrupts. 181 * 182 * @return 0 on success, negative errno code on fail. 183 */ 184 int usb_enable(struct usb_cfg_data *config); 185 186 /* 187 * @brief disable the USB device. 188 * 189 * Function to disable the USB device. 190 * Upon success, the specified USB interface is clock gated in hardware, 191 * it is no longer capable of generating interrupts. 192 * 193 * @return 0 on success, negative errno code on fail 194 */ 195 int usb_disable(void); 196 197 /* 198 * @brief Check if a write to an in ep would block until there is enough space 199 * in the fifo 200 * 201 * @param[in] ep Endpoint address corresponding to the one listed in the 202 * device configuration table 203 * 204 * @return 0 if free to write, 1 if a write would block, negative errno code on fail 205 */ 206 int usb_write_would_block(uint8_t ep); 207 208 /* 209 * @brief write data to the specified endpoint 210 * 211 * Function to write data to the specified endpoint. The supplied 212 * usb_ep_callback will be called when transmission is done. 213 * 214 * @param[in] ep Endpoint address corresponding to the one listed in the 215 * device configuration table 216 * @param[in] data Pointer to data to write 217 * @param[in] data_len Length of data requested to write. This may be zero for 218 * a zero length status packet. 219 * @param[out] bytes_ret Bytes written to the EP FIFO. This value may be NULL if 220 * the application expects all bytes to be written 221 * 222 * @return 0 on success, negative errno code on fail 223 */ 224 int usb_write(uint8_t ep, const uint8_t *data, uint32_t data_len, 225 uint32_t *bytes_ret); 226 227 /* 228 * @brief read data from the specified endpoint 229 * 230 * This function is called by the Endpoint handler function, after an 231 * OUT interrupt has been received for that EP. The application must 232 * only call this function through the supplied usb_ep_callback function. 233 * 234 * @param[in] ep Endpoint address corresponding to the one listed in 235 * the device configuration table 236 * @param[in] data Pointer to data buffer to write to 237 * @param[in] max_data_len Max length of data to read 238 * @param[out] ret_bytes Number of bytes read. If data is NULL and 239 * max_data_len is 0 the number of bytes available 240 * for read is returned. 241 * 242 * @return 0 on success, negative errno code on fail 243 */ 244 int usb_read(uint8_t ep, uint8_t *data, uint32_t max_data_len, 245 uint32_t *ret_bytes); 246 247 /* 248 * @brief set STALL condition on the specified endpoint 249 * 250 * This function is called by USB device class handler code to set stall 251 * conditionin on endpoint. 252 * 253 * @param[in] ep Endpoint address corresponding to the one listed in 254 * the device configuration table 255 * 256 * @return 0 on success, negative errno code on fail 257 */ 258 int usb_ep_set_stall(uint8_t ep); 259 260 261 /* 262 * @brief clears STALL condition on the specified endpoint 263 * 264 * This function is called by USB device class handler code to clear stall 265 * conditionin on endpoint. 266 * 267 * @param[in] ep Endpoint address corresponding to the one listed in 268 * the device configuration table 269 * 270 * @return 0 on success, negative errno code on fail 271 */ 272 int usb_ep_clear_stall(uint8_t ep); 273 274 /** 275 * @brief read data from the specified endpoint 276 * 277 * This is similar to usb_ep_read, the difference being that, it doesn't 278 * clear the endpoint NAKs so that the consumer is not bogged down by further 279 * upcalls till he is done with the processing of the data. The caller should 280 * reactivate ep by invoking usb_ep_read_continue() do so. 281 * 282 * @param[in] ep Endpoint address corresponding to the one 283 * listed in the device configuration table 284 * @param[in] data pointer to data buffer to write to 285 * @param[in] max_data_len max length of data to read 286 * @param[out] read_bytes Number of bytes read. If data is NULL and 287 * max_data_len is 0 the number of bytes 288 * available for read should be returned. 289 * 290 * @return 0 on success, negative errno code on fail. 291 */ 292 int usb_ep_read_wait(uint8_t ep, uint8_t *data, uint32_t max_data_len, 293 uint32_t *read_bytes); 294 295 296 /** 297 * @brief Continue reading data from the endpoint 298 * 299 * Clear the endpoint NAK and enable the endpoint to accept more data 300 * from the host. Usually called after usb_ep_read_wait() when the consumer 301 * is fine to accept more data. Thus these calls together acts as flow control 302 * mechanism. 303 * 304 * @param[in] ep Endpoint address corresponding to the one 305 * listed in the device configuration table 306 * 307 * @return 0 on success, negative errno code on fail. 308 */ 309 int usb_ep_read_continue(uint8_t ep); 310 311 /** 312 * Callback function signature for transfer completion. 313 */ 314 typedef void (*usb_transfer_callback)(uint8_t ep, int tsize, void *priv); 315 316 /* USB transfer flags */ 317 #define USB_TRANS_READ BIT(0) /** Read transfer flag */ 318 #define USB_TRANS_WRITE BIT(1) /** Write transfer flag */ 319 #define USB_TRANS_NO_ZLP BIT(2) /** No zero-length packet flag */ 320 321 /** 322 * @brief Transfer management endpoint callback 323 * 324 * If a USB class driver wants to use high-level transfer functions, driver 325 * needs to register this callback as usb endpoint callback. 326 */ 327 void usb_transfer_ep_callback(uint8_t ep, enum usb_dc_ep_cb_status_code); 328 329 /** 330 * @brief Start a transfer 331 * 332 * Start a usb transfer to/from the data buffer. This function is asynchronous 333 * and can be executed in IRQ context. The provided callback will be called 334 * on transfer completion (or error) in thread context. 335 * 336 * @param[in] ep Endpoint address corresponding to the one 337 * listed in the device configuration table 338 * @param[in] data Pointer to data buffer to write-to/read-from 339 * @param[in] dlen Size of data buffer 340 * @param[in] flags Transfer flags (USB_TRANS_READ, USB_TRANS_WRITE...) 341 * @param[in] cb Function called on transfer completion/failure 342 * @param[in] priv Data passed back to the transfer completion callback 343 * 344 * @return 0 on success, negative errno code on fail. 345 */ 346 int usb_transfer(uint8_t ep, uint8_t *data, size_t dlen, unsigned int flags, 347 usb_transfer_callback cb, void *priv); 348 349 /** 350 * @brief Start a transfer and block-wait for completion 351 * 352 * Synchronous version of usb_transfer, wait for transfer completion before 353 * returning. 354 * 355 * @param[in] ep Endpoint address corresponding to the one 356 * listed in the device configuration table 357 * @param[in] data Pointer to data buffer to write-to/read-from 358 * @param[in] dlen Size of data buffer 359 * @param[in] flags Transfer flags 360 361 * 362 * @return number of bytes transferred on success, negative errno code on fail. 363 */ 364 int usb_transfer_sync(uint8_t ep, uint8_t *data, size_t dlen, unsigned int flags); 365 366 /** 367 * @brief Cancel any ongoing transfer on the specified endpoint 368 * 369 * @param[in] ep Endpoint address corresponding to the one 370 * listed in the device configuration table 371 * 372 * @return 0 on success, negative errno code on fail. 373 */ 374 void usb_cancel_transfer(uint8_t ep); 375 376 /** 377 * @brief Provide IDF with an interface to clear the static variable usb_dev 378 * 379 * 380 */ 381 void usb_dev_deinit(void); 382 383 void usb_dev_resume(int configuration); 384 int usb_dev_get_configuration(void); 385 386 387 #ifdef __cplusplus 388 } 389 #endif 390
