michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: Using doxygen comments from the code for USB DC

Browse source 
Fixes issue with USB subsystem doc not pulling from header
doxygen comments of USB Device Controller code.

Fixes: #5702

Signed-off-by: Andrei Emeltchenko <andrei.emeltchenko@intel.com>
This commit is contained in:
Andrei Emeltchenko 2018-09-11 13:25:43 +03:00 • committed by Anas Nashif
commit 1e1b46d101
1 changed files with 5 additions and 141 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -30,149 +30,13 @@ The Device Controller Driver Layer implements the low level control routines
to deal directly with the hardware. All device controller drivers should
implement the APIs described in file usb_dc.h. This allows the integration of
new USB device controllers to be done without changing the upper layers.
For now only Quark SE USB device controller (Designware IP) is supported.
Structures
==========
.. _usb_device_controller_api:
.. code-block:: c
struct usb_dc_ep_cfg_data {
u8_t ep_addr;
u16_t ep_mps;
enum usb_dc_ep_type ep_type;
};
Structure containing the USB endpoint configuration.
* ep_addr: endpoint address, the number associated with the EP in the device
configuration structure.
IN EP = 0x80 | <endpoint number>. OUT EP = 0x00 | <endpoint number>
* ep_mps: Endpoint max packet size.
* ep_type: Endpoint type, may be Bulk, Interrupt or Control. Isochronous
endpoints are not supported for now.
.. code-block:: c
enum usb_dc_status_code {
USB_DC_ERROR,
USB_DC_RESET,
USB_DC_CONNECTED,
USB_DC_CONFIGURED,
USB_DC_DISCONNECTED,
USB_DC_SUSPEND,
USB_DC_RESUME,
USB_DC_INTERFACE,
USB_DC_UNKNOWN
};
Status codes reported by the registered device status callback.
* USB_DC_ERROR: USB error reported by the controller.
* USB_DC_RESET: USB reset.
* USB_DC_CONNECTED: USB connection established - hardware enumeration is completed.
* USB_DC_CONFIGURED: USB configuration done.
* USB_DC_DISCONNECTED: USB connection lost.
* USB_DC_SUSPEND: USB connection suspended by the HOST.
* USB_DC_RESUME: USB connection resumed by the HOST.
* USB_DC_INTERFACE: USB Interface selected by the HOST.
* USB_DC_UNKNOWN: Initial USB connection status.
.. code-block:: c
enum usb_dc_ep_cb_status_code {
USB_DC_EP_SETUP,
USB_DC_EP_DATA_OUT,
USB_DC_EP_DATA_IN,
};
Status Codes reported by the registered endpoint callback.
* USB_DC_EP_SETUP: SETUP packet received.
* USB_DC_EP_DATA_OUT: Out transaction on this endpoint. Data is available
for read.
* USB_DC_EP_DATA_IN: In transaction done on this endpoint.
APIs
====
The following APIs are provided by the device controller driver:
:c:func:`usb_dc_attach()`
This function attaches USB for device connection. Upon success, the USB PLL
is enabled, and the USB device is now capable of transmitting and receiving
on the USB bus and of generating interrupts.
:c:func:`usb_dc_detach()`
This function detaches the USB device. Upon success the USB hardware PLL is
powered down and USB communication is disabled.
:c:func:`usb_dc_reset()`
This function returns the USB device to it's initial state.
:c:func:`usb_dc_set_address()`
This function sets USB device address.
:c:func:`usb_dc_set_status_callback()`
This function sets USB device controller status callback. The registered
callback is used to report changes in the status of the device controller.
The status code are described by the usb_dc_status_code enumeration.
:c:func:`usb_dc_ep_configure()`
This function configures an endpoint. usb_dc_ep_cfg_data structure provides
the endpoint configuration parameters: endpoint address, endpoint maximum
packet size and endpoint type.
:c:func:`usb_dc_ep_set_stall()`
This function sets stall condition for the selected endpoint.
:c:func:`usb_dc_ep_clear_stall()`
This functions clears stall condition for the selected endpoint
:c:func:`usb_dc_ep_is_stalled()`
This function check if selected endpoint is stalled.
:c:func:`usb_dc_ep_halt()`
This function halts the selected endpoint
:c:func:`usb_dc_ep_enable()`
This function enables the selected endpoint. Upon success interrupts are
enabled for the corresponding endpoint and the endpoint is ready for
transmitting/receiving data.
:c:func:`usb_dc_ep_disable()`
This function disables the selected endpoint. Upon success interrupts are
disabled for the corresponding endpoint and the endpoint is no longer able
for transmitting/receiving data.
:c:func:`usb_dc_ep_flush()`
This function flushes the FIFOs for the selected endpoint.
:c:func:`usb_dc_ep_write()`
This function writes data to the specified endpoint. The supplied
usb_ep_callback function will be called when data is transmitted out.
:c:func:`usb_dc_ep_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_dc_ep_set_callback()`
This function sets callback function for notification of data received
and available to application or transmit done on the selected endpoint.
The callback status code is described by usb_dc_ep_cb_status_code.
:c:func:`usb_dc_ep_read_wait()`
This function is similar to usb_dc_ep_read, the difference being that, it
doesn't clear the endpoint NAKs so that the consumer is not bogged down by
further upcalls till he is done with the processing of the data. The caller
should reactivate ep by invoking usb_dc_ep_read_continue() do so.
:c:func:`usb_dc_ep_read_continue()`
Clear the endpoint NAK and enable the endpoint to accept more data from the
host. Usually called after usb_dc_ep_read_wait() when the consumer is fine
to accept more data. Thus these calls together acts as flow control
mechanism.
:c:func:`usb_dc_ep_mps()`
Get endpoint max packet size.
USB Device Controller API
=========================
.. doxygengroup:: _usb_device_controller_api
:project: Zephyr
USB device core layer
*********************