1 /* usb_dc.h - USB device controller driver interface */ 2 3 /* 4 * Copyright (c) 2016 Intel Corporation. 5 * 6 * SPDX-License-Identifier: Apache-2.0 7 */ 8 9 /** 10 * @file 11 * @brief USB device controller APIs 12 * 13 * This file contains the USB device controller APIs. All device controller 14 * drivers should implement the APIs described in this file. 15 */ 16 17 #ifndef ZEPHYR_INCLUDE_DRIVERS_USB_USB_DC_H_ 18 #define ZEPHYR_INCLUDE_DRIVERS_USB_USB_DC_H_ 19 20 #include <zephyr/device.h> 21 22 /** 23 * @brief USB Device Controller API 24 * @defgroup _usb_device_controller_api USB Device Controller API 25 * @{ 26 */ 27 28 /** 29 * @brief USB Driver Status Codes 30 * 31 * Status codes reported by the registered device status callback. 32 */ 33 enum usb_dc_status_code { 34 /** USB error reported by the controller */ 35 USB_DC_ERROR, 36 /** USB reset */ 37 USB_DC_RESET, 38 /** USB connection established, hardware enumeration is completed */ 39 USB_DC_CONNECTED, 40 /** USB configuration done */ 41 USB_DC_CONFIGURED, 42 /** USB connection lost */ 43 USB_DC_DISCONNECTED, 44 /** USB connection suspended by the HOST */ 45 USB_DC_SUSPEND, 46 /** USB connection resumed by the HOST */ 47 USB_DC_RESUME, 48 /** USB interface selected */ 49 USB_DC_INTERFACE, 50 /** Set Feature ENDPOINT_HALT received */ 51 USB_DC_SET_HALT, 52 /** Clear Feature ENDPOINT_HALT received */ 53 USB_DC_CLEAR_HALT, 54 /** Start of Frame received */ 55 USB_DC_SOF, 56 /** Initial USB connection status */ 57 USB_DC_UNKNOWN 58 }; 59 60 /** 61 * @brief USB Endpoint Callback Status Codes 62 * 63 * Status Codes reported by the registered endpoint callback. 64 */ 65 enum usb_dc_ep_cb_status_code { 66 /** SETUP received */ 67 USB_DC_EP_SETUP, 68 /** Out transaction on this EP, data is available for read */ 69 USB_DC_EP_DATA_OUT, 70 /** In transaction done on this EP */ 71 USB_DC_EP_DATA_IN 72 }; 73 74 /** 75 * @brief USB Endpoint Transfer Type 76 */ 77 enum usb_dc_ep_transfer_type { 78 /** Control type endpoint */ 79 USB_DC_EP_CONTROL = 0, 80 /** Isochronous type endpoint */ 81 USB_DC_EP_ISOCHRONOUS, 82 /** Bulk type endpoint */ 83 USB_DC_EP_BULK, 84 /** Interrupt type endpoint */ 85 USB_DC_EP_INTERRUPT 86 }; 87 88 /** 89 * @brief USB Endpoint Synchronization Type 90 * 91 * @note Valid only for Isochronous Endpoints 92 */ 93 enum usb_dc_ep_synchronozation_type { 94 /** No Synchronization */ 95 USB_DC_EP_NO_SYNCHRONIZATION = (0U << 2U), 96 /** Asynchronous */ 97 USB_DC_EP_ASYNCHRONOUS = (1U << 2U), 98 /** Adaptive */ 99 USB_DC_EP_ADAPTIVE = (2U << 2U), 100 /** Synchronous*/ 101 USB_DC_EP_SYNCHRONOUS = (3U << 2U) 102 }; 103 104 /** 105 * @brief USB Endpoint Configuration. 106 * 107 * Structure containing the USB endpoint configuration. 108 */ 109 struct usb_dc_ep_cfg_data { 110 /** The number associated with the EP in the device 111 * configuration structure 112 * IN EP = 0x80 | \<endpoint number\> 113 * OUT EP = 0x00 | \<endpoint number\> 114 */ 115 uint8_t ep_addr; 116 /** Endpoint max packet size */ 117 uint16_t ep_mps; 118 /** Endpoint Transfer Type. 119 * May be Bulk, Interrupt, Control or Isochronous 120 */ 121 enum usb_dc_ep_transfer_type ep_type; 122 }; 123 124 /** 125 * Callback function signature for the USB Endpoint status 126 */ 127 typedef void (*usb_dc_ep_callback)(uint8_t ep, 128 enum usb_dc_ep_cb_status_code cb_status); 129 130 /** 131 * Callback function signature for the device 132 */ 133 typedef void (*usb_dc_status_callback)(enum usb_dc_status_code cb_status, 134 const uint8_t *param); 135 136 /** 137 * @brief Attach USB for device connection 138 * 139 * Function to attach USB for device connection. Upon success, the USB PLL 140 * is enabled, and the USB device is now capable of transmitting and receiving 141 * on the USB bus and of generating interrupts. 142 * 143 * @return 0 on success, negative errno code on fail. 144 */ 145 int usb_dc_attach(void); 146 147 /** 148 * @brief Detach the USB device 149 * 150 * Function to detach the USB device. Upon success, the USB hardware PLL 151 * is powered down and USB communication is disabled. 152 * 153 * @return 0 on success, negative errno code on fail. 154 */ 155 int usb_dc_detach(void); 156 157 /** 158 * @brief Reset the USB device 159 * 160 * This function returns the USB device and firmware back to it's initial state. 161 * N.B. the USB PLL is handled by the usb_detach function 162 * 163 * @return 0 on success, negative errno code on fail. 164 */ 165 int usb_dc_reset(void); 166 167 /** 168 * @brief Set USB device address 169 * 170 * @param[in] addr Device address 171 * 172 * @return 0 on success, negative errno code on fail. 173 */ 174 int usb_dc_set_address(const uint8_t addr); 175 176 /** 177 * @brief Set USB device controller status callback 178 * 179 * Function to set USB device controller status callback. The registered 180 * callback is used to report changes in the status of the device controller. 181 * The status code are described by the usb_dc_status_code enumeration. 182 * 183 * @param[in] cb Callback function 184 */ 185 void usb_dc_set_status_callback(const usb_dc_status_callback cb); 186 187 /** 188 * @brief check endpoint capabilities 189 * 190 * Function to check capabilities of an endpoint. usb_dc_ep_cfg_data structure 191 * provides the endpoint configuration parameters: endpoint address, 192 * endpoint maximum packet size and endpoint type. 193 * The driver should check endpoint capabilities and return 0 if the 194 * endpoint configuration is possible. 195 * 196 * @param[in] cfg Endpoint config 197 * 198 * @return 0 on success, negative errno code on fail. 199 */ 200 int usb_dc_ep_check_cap(const struct usb_dc_ep_cfg_data * const cfg); 201 202 /** 203 * @brief Configure endpoint 204 * 205 * Function to configure an endpoint. usb_dc_ep_cfg_data structure provides 206 * the endpoint configuration parameters: endpoint address, endpoint maximum 207 * packet size and endpoint type. 208 * 209 * @param[in] cfg Endpoint config 210 * 211 * @return 0 on success, negative errno code on fail. 212 */ 213 int usb_dc_ep_configure(const struct usb_dc_ep_cfg_data * const cfg); 214 215 /** 216 * @brief Set stall condition for the selected endpoint 217 * 218 * @param[in] ep Endpoint address corresponding to the one 219 * listed in the device configuration table 220 * 221 * @return 0 on success, negative errno code on fail. 222 */ 223 int usb_dc_ep_set_stall(const uint8_t ep); 224 225 /** 226 * @brief Clear stall condition for the selected endpoint 227 * 228 * @param[in] ep Endpoint address corresponding to the one 229 * listed in the device configuration table 230 * 231 * @return 0 on success, negative errno code on fail. 232 */ 233 int usb_dc_ep_clear_stall(const uint8_t ep); 234 235 /** 236 * @brief Check if the selected endpoint is stalled 237 * 238 * @param[in] ep Endpoint address corresponding to the one 239 * listed in the device configuration table 240 * @param[out] stalled Endpoint stall status 241 * 242 * @return 0 on success, negative errno code on fail. 243 */ 244 int usb_dc_ep_is_stalled(const uint8_t ep, uint8_t *const stalled); 245 246 /** 247 * @brief Halt the selected endpoint 248 * 249 * @param[in] ep Endpoint address corresponding to the one 250 * listed in the device configuration table 251 * 252 * @return 0 on success, negative errno code on fail. 253 */ 254 int usb_dc_ep_halt(const uint8_t ep); 255 256 /** 257 * @brief Enable the selected endpoint 258 * 259 * Function to enable the selected endpoint. Upon success interrupts are 260 * enabled for the corresponding endpoint and the endpoint is ready for 261 * transmitting/receiving data. 262 * 263 * @param[in] ep Endpoint address corresponding to the one 264 * listed in the device configuration table 265 * 266 * @return 0 on success, negative errno code on fail. 267 */ 268 int usb_dc_ep_enable(const uint8_t ep); 269 270 /** 271 * @brief Disable the selected endpoint 272 * 273 * Function to disable the selected endpoint. Upon success interrupts are 274 * disabled for the corresponding endpoint and the endpoint is no longer able 275 * for transmitting/receiving data. 276 * 277 * @param[in] ep Endpoint address corresponding to the one 278 * listed in the device configuration table 279 * 280 * @return 0 on success, negative errno code on fail. 281 */ 282 int usb_dc_ep_disable(const uint8_t ep); 283 284 /** 285 * @brief Flush the selected endpoint 286 * 287 * This function flushes the FIFOs for the selected endpoint. 288 * 289 * @param[in] ep Endpoint address corresponding to the one 290 * listed in the device configuration table 291 * 292 * @return 0 on success, negative errno code on fail. 293 */ 294 int usb_dc_ep_flush(const uint8_t ep); 295 296 /** 297 * @brief Write data to the specified endpoint 298 * 299 * This function is called to write data to the specified endpoint. The 300 * supplied usb_ep_callback function will be called when data is transmitted 301 * out. 302 * 303 * @param[in] ep Endpoint address corresponding to the one 304 * listed in the device configuration table 305 * @param[in] data Pointer to data to write 306 * @param[in] data_len Length of the data requested to write. This may 307 * be zero for a zero length status packet. 308 * @param[out] ret_bytes Bytes scheduled for transmission. This value 309 * may be NULL if the application expects all 310 * bytes to be written 311 * 312 * @return 0 on success, negative errno code on fail. 313 */ 314 int usb_dc_ep_write(const uint8_t ep, const uint8_t *const data, 315 const uint32_t data_len, uint32_t * const ret_bytes); 316 317 /** 318 * @brief Read data from the specified endpoint 319 * 320 * This function is called by the endpoint handler function, after an OUT 321 * interrupt has been received for that EP. The application must only call this 322 * function through the supplied usb_ep_callback function. This function clears 323 * the ENDPOINT NAK, if all data in the endpoint FIFO has been read, 324 * so as to accept more data from host. 325 * 326 * @param[in] ep Endpoint address corresponding to the one 327 * listed in the device configuration table 328 * @param[in] data Pointer to data buffer to write to 329 * @param[in] max_data_len Max length of data to read 330 * @param[out] read_bytes Number of bytes read. If data is NULL and 331 * max_data_len is 0 the number of bytes 332 * available for read should be returned. 333 * 334 * @return 0 on success, negative errno code on fail. 335 */ 336 int usb_dc_ep_read(const uint8_t ep, uint8_t *const data, 337 const uint32_t max_data_len, uint32_t *const read_bytes); 338 339 /** 340 * @brief Set callback function for the specified endpoint 341 * 342 * Function to set callback function for notification of data received and 343 * available to application or transmit done on the selected endpoint, 344 * NULL if callback not required by application code. The callback status 345 * code is described by usb_dc_ep_cb_status_code. 346 * 347 * @param[in] ep Endpoint address corresponding to the one 348 * listed in the device configuration table 349 * @param[in] cb Callback function 350 * 351 * @return 0 on success, negative errno code on fail. 352 */ 353 int usb_dc_ep_set_callback(const uint8_t ep, const usb_dc_ep_callback cb); 354 355 /** 356 * @brief Read data from the specified endpoint 357 * 358 * This is similar to usb_dc_ep_read, the difference being that, it doesn't 359 * clear the endpoint NAKs so that the consumer is not bogged down by further 360 * upcalls till he is done with the processing of the data. The caller should 361 * reactivate ep by invoking usb_dc_ep_read_continue() do so. 362 * 363 * @param[in] ep Endpoint address corresponding to the one 364 * listed in the device configuration table 365 * @param[in] data Pointer to data buffer to write to 366 * @param[in] max_data_len Max length of data to read 367 * @param[out] read_bytes Number of bytes read. If data is NULL and 368 * max_data_len is 0 the number of bytes 369 * available for read should be returned. 370 * 371 * @return 0 on success, negative errno code on fail. 372 */ 373 int usb_dc_ep_read_wait(uint8_t ep, uint8_t *data, uint32_t max_data_len, 374 uint32_t *read_bytes); 375 376 /** 377 * @brief Continue reading data from the endpoint 378 * 379 * Clear the endpoint NAK and enable the endpoint to accept more data 380 * from the host. Usually called after usb_dc_ep_read_wait() when the consumer 381 * is fine to accept more data. Thus these calls together act as a flow control 382 * mechanism. 383 * 384 * @param[in] ep Endpoint address corresponding to the one 385 * listed in the device configuration table 386 * 387 * @return 0 on success, negative errno code on fail. 388 */ 389 int usb_dc_ep_read_continue(uint8_t ep); 390 391 /** 392 * @brief Get endpoint max packet size 393 * 394 * @param[in] ep Endpoint address corresponding to the one 395 * listed in the device configuration table 396 * 397 * @return Endpoint max packet size (mps) 398 */ 399 int usb_dc_ep_mps(uint8_t ep); 400 401 /** 402 * @brief Start the host wake up procedure. 403 * 404 * Function to wake up the host if it's currently in sleep mode. 405 * 406 * @return 0 on success, negative errno code on fail. 407 */ 408 int usb_dc_wakeup_request(void); 409 410 /** 411 * @} 412 */ 413 414 #endif /* ZEPHYR_INCLUDE_DRIVERS_USB_USB_DC_H_ */ 415
