michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: Using doxygen comments from the code for USB Core

Browse source 
Instead of documenting in rst, pull the API from USB Device Core Layer
header.

Fixes: #5702

Signed-off-by: Andrei Emeltchenko <andrei.emeltchenko@intel.com>
This commit is contained in:
Andrei Emeltchenko 2018-09-11 14:19:48 +03:00 • committed by Anas Nashif
commit 798cdaec7e
1 changed files with 4 additions and 118 deletions
Download patch file Download diff file Expand all files Collapse all files

122
doc/subsystems/usb/usb.rst
View file

@ -55,124 +55,10 @@ functionalities:
* Uses the APIs provided by the device controller drivers to interact with
the USB device controller.
Structures
==========
.. code-block:: c
typedef void (*usb_status_callback)(enum usb_dc_status_code status_code);
Callback function signature for the device status.
.. code-block:: c
typedef void (*usb_ep_callback)(u8_t ep,
enum usb_dc_ep_cb_status_code cb_status);
Callback function signature for the USB Endpoint.
.. code-block:: c
typedef int (*usb_request_handler) (struct usb_setup_packet *setup,
int *transfer_len, u8_t **payload_data);
Callback function signature for class specific requests. For host to device
direction the 'len' and 'payload_data' contain the length of the received data
and the pointer to the received data respectively. For device to host class
requests, 'len' and 'payload_data' should be set by the callback function
with the length and the address of the data to be transmitted buffer
respectively.
.. code-block:: c
struct usb_ep_cfg_data {
usb_ep_callback ep_cb;
u8_t ep_addr;
};
This structure contains configuration for a certain endpoint.
* ep_cb: callback function for notification of data received and available
to application or transmit done, NULL if callback not required by
application code.
* ep_addr: endpoint address. The number associated with the EP in the device
configuration structure.
.. code-block:: c
struct usb_interface_cfg_data {
usb_request_handler class_handler;
usb_request_handler custom_handler;
u8_t *payload_data;
};
This structure contains USB interface configuration.
* class_handler: handler for USB Class specific Control (EP 0)
communications.
* custom_handler: the custom request handler gets a first
chance at handling the request before it is handed over to the
'chapter 9' request handler.
* payload_data: this data area, allocated by the application, is used to
store class specific command data and must be large enough to store the
largest payload associated with the largest supported Class' command set.
.. code-block:: c
struct usb_cfg_data {
const u8_t *usb_device_description;
usb_status_callback cb_usb_status;
struct usb_interface_cfg_data interface;
u8_t num_endpoints;
struct usb_ep_cfg_data *endpoint;
};
This structure contains USB device configuration.
* usb_device_description: USB device description, see
http://www.beyondlogic.org/usbnutshell/usb5.shtml#DeviceDescriptors
* cb_usb_status: callback to be notified on USB connection status change
* interface: USB class handlers and storage space.
* num_endpoints: number of individual endpoints in the device configuration
* endpoint: pointer to an array of endpoint configuration structures
(usb_cfg_data) of length equal to the number of EP associated with the
device description, not including control endpoints.
The class drivers instantiates this with given parameters using the
"usb_set_config" function.
APIs
====
:c:func:`usb_set_config()`
This function configures USB device.
:c:func:`usb_deconfig()`
This function returns the USB device back to it's initial state
:c:func:`usb_enable()`
This function enable USB for host/device connection. Upon success, the USB
module is no longer clock gated in hardware, it is now capable of
transmitting and receiving on the USB bus and of generating interrupts.
:c:func:`usb_disable()`
This function disables the USB device. Upon success, the USB module clock
is gated in hardware and it is no longer capable of generating interrupts.
:c:func:`usb_write()`
write data to the specified endpoint. The supplied usb_ep_callback will be
called when transmission is done.
:c:func:`usb_read()`
This function is called by the endpoint handler function after an OUT
interrupt has been received for that EP. The application must only call
this function through the supplied usb_ep_callback function.
:c:func:`usb_transfer()`
This asynchronous function starts a usb transfer from/to a specified buffer.
A callback can be provided and will be called on transfer completion.
This function can be used in IRQ context.
:c:func:`usb_transfer_sync()`
This function is the synchronous version of the usb_transfer function,
waiting for transfer completion before returning.
USB Device Core Layer API
=========================
.. doxygengroup:: _usb_device_core_api
:project: Zephyr
USB device class drivers
************************