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