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