2  * Copyright (c) 2021-2022 Nordic Semiconductor ASA
4  * SPDX-License-Identifier: Apache-2.0
9  * @brief New USB device controller (UDC) driver API
22  * @brief Maximum packet size of control endpoint supported by the controller.
32  * USB device controller capabilities
37 	/** USB high speed capable controller */
39 	/** Controller supports USB remote wakeup */
41 	/** Controller performs status OUT stage automatically */
43 	/** Controller expects device address to be set before status stage */
45 	/** Controller can detect the state change of USB supply VBUS.*/
66  * USB device controller endpoint capabilities
79 	/** High-Bandwidth (interrupt or iso) capable endpoint */
88  * USB device controller endpoint status
104  * USB device controller endpoint configuration
129  * @brief USB device controller event types
147 	 * Non-correctable error event, requires attention from higher
154  * USB device controller event
159  * by higher layer during controller initialization (udc_init).
194 	/** Flag marks request buffer claimed by the controller (TBD) */
200 	/** Transfer result, 0 on success, other values on error */
215  * @return 0 on success, all other values should be treated as error.
222  * This is the mandatory API any USB device controller driver needs to expose
257  * Controller is initialized by udc_init() and can generate the VBUS events,
262  * Controller is enabled and all API functions are available,
263  * controller is recognizable by host.
266 /** Controller is suspended by the host */
272  * Mandatory structure for each UDC controller driver.
273  * To be implemented as device's private data (device->data).
278 	/** Controller capabilities */
286 	/** USB device controller status */
297  * @brief New USB device controller (UDC) driver API
298  * @defgroup udc_api USB device controller driver API
306  * @brief Checks whether the controller is initialized.
310  * @return true if controller is initialized, false otherwise
314 	struct udc_data *data = dev->data;  in udc_is_initialized()
316 	return atomic_test_bit(&data->status, UDC_STATUS_INITIALIZED);  in udc_is_initialized()
320  * @brief Checks whether the controller is enabled.
324  * @return true if controller is enabled, false otherwise
328 	struct udc_data *data = dev->data;  in udc_is_enabled()
330 	return atomic_test_bit(&data->status, UDC_STATUS_ENABLED);  in udc_is_enabled()
334  * @brief Checks whether the controller is suspended.
338  * @return true if controller is suspended, false otherwise
342 	struct udc_data *data = dev->data;  in udc_is_suspended()
344 	return atomic_test_bit(&data->status, UDC_STATUS_SUSPENDED);  in udc_is_suspended()
348  * @brief Initialize USB device controller
350  * Initialize USB device controller and control IN/OUT endpoint.
351  * After initialization controller driver should be able to detect
358  * @return 0 on success, all other values should be treated as error.
359  * @retval -EINVAL on parameter error (no callback is passed)
360  * @retval -EALREADY already initialized
366  * @brief Enable USB device controller
368  * Enable powered USB device controller and allow host to
373  * @return 0 on success, all other values should be treated as error.
374  * @retval -EPERM controller is not initialized
375  * @retval -EALREADY already enabled
376  * @retval -ETIMEDOUT enable operation timed out
381  * @brief Disable USB device controller
383  * Disable enabled USB device controller.
388  * @return 0 on success, all other values should be treated as error.
389  * @retval -EALREADY already disabled
394  * @brief Poweroff USB device controller
396  * Shut down the controller completely to reduce energy consumption
397  * or to change the role of the controller.
401  * @return 0 on success, all other values should be treated as error.
402  * @retval -EALREADY controller is not initialized
407  * @brief Get USB device controller capabilities
409  * Obtain the capabilities of the controller
414  * @return USB device controller capabilities.
418 	struct udc_data *data = dev->data;  in udc_caps()
420 	return data->caps;  in udc_caps()
431  * @return USB device controller capabilities.
443  * @return 0 on success, all other values should be treated as error.
444  * @retval -EPERM controller is not enabled (or not initialized)
448 	const struct udc_api *api = dev->api;  in udc_set_address()
452 		return -EPERM;  in udc_set_address()
455 	api->lock(dev);  in udc_set_address()
456 	ret = api->set_address(dev, addr);  in udc_set_address()
457 	api->unlock(dev);  in udc_set_address()
465  * For compliance testing, high-speed controllers must support test modes.
474  * @return 0 on success, all other values should be treated as error.
475  * @retval -ENOTSUP Test mode is not supported
480 	const struct udc_api *api = dev->api;  in udc_test_mode()
484 		return -EPERM;  in udc_test_mode()
487 	if (api->test_mode != NULL) {  in udc_test_mode()
488 		api->lock(dev);  in udc_test_mode()
489 		ret = api->test_mode(dev, mode, dryrun);  in udc_test_mode()
490 		api->unlock(dev);  in udc_test_mode()
492 		ret = -ENOTSUP;  in udc_test_mode()
505  * @return 0 on success, all other values should be treated as error.
506  * @retval -EPERM controller is not enabled (or not initialized)
510 	const struct udc_api *api = dev->api;  in udc_host_wakeup()
514 		return -EPERM;  in udc_host_wakeup()
517 	api->lock(dev);  in udc_host_wakeup()
518 	ret = api->host_wakeup(dev);  in udc_host_wakeup()
519 	api->unlock(dev);  in udc_host_wakeup()
540  * @return 0 on success, all other values should be treated as error.
541  * @retval -EINVAL on wrong parameter
542  * @retval -ENOTSUP endpoint configuration not supported
543  * @retval -ENODEV no endpoints available
563  * @return 0 on success, all other values should be treated as error.
564  * @retval -EINVAL on wrong parameter (control IN/OUT endpoint)
565  * @retval -EPERM controller is not initialized
566  * @retval -ENODEV endpoint configuration not found
567  * @retval -EALREADY endpoint is already enabled
583  * @return 0 on success, all other values should be treated as error.
584  * @retval -EINVAL on wrong parameter (control IN/OUT endpoint)
585  * @retval -ENODEV endpoint configuration not found
586  * @retval -EALREADY endpoint is already disabled
587  * @retval -EPERM controller is not initialized
599  * @return 0 on success, all other values should be treated as error.
600  * @retval -ENODEV endpoint configuration not found
601  * @retval -ENOTSUP not supported (e.g. isochronous endpoint)
602  * @retval -EPERM controller is not enabled
614  * @return 0 on success, all other values should be treated as error.
615  * @retval -ENODEV endpoint configuration not found
616  * @retval -ENOTSUP not supported (e.g. isochronous endpoint)
617  * @retval -EPERM controller is not enabled
622  * @brief Queue USB device controller request
625  * buffer can be claimed by the controller immediately.
630  * @return 0 on success, all other values should be treated as error.
631  * @retval -ENODEV endpoint configuration not found
632  * @retval -EACCES endpoint is not enabled (TBD)
633  * @retval -EBUSY request can not be queued
634  * @retval -EPERM controller is not initialized
639  * @brief Remove all USB device controller requests from endpoint queue
649  * @return 0 on success, all other values should be treated as error.
650  * @retval -ENODEV endpoint configuration not found
651  * @retval -EACCES endpoint is not disabled
652  * @retval -EPERM controller is not initialized
679  * @return 0 on success, all other values should be treated as error.
686  * The controller should send a ZLP at the end of the transfer.
696 	if (USB_EP_DIR_IS_IN(bi->ep)) {  in udc_ep_buf_set_zlp()
697 		bi->zlp = 1;  in udc_ep_buf_set_zlp()
727 	struct udc_data *data = dev->data;  in udc_get_event_ctx()
729 	return data->event_ctx;  in udc_get_event_ctx()
741 	return USB_MPS_EP_SIZE(cfg->mps);  in udc_mps_ep_size()