diff options
Diffstat (limited to 'os/hal/dox/hal_usb.dox')
| -rw-r--r-- | os/hal/dox/hal_usb.dox | 180 |
1 files changed, 180 insertions, 0 deletions
diff --git a/os/hal/dox/hal_usb.dox b/os/hal/dox/hal_usb.dox new file mode 100644 index 000000000..82de6ccfc --- /dev/null +++ b/os/hal/dox/hal_usb.dox @@ -0,0 +1,180 @@ +/*
+ ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+*/
+
+/**
+ * @defgroup USB USB Driver
+ * @brief Generic USB Driver.
+ * @details This module implements a generic USB (Universal Serial Bus) driver
+ * supporting device-mode operations.
+ * @pre In order to use the USB driver the @p HAL_USE_USB option
+ * must be enabled in @p halconf.h.
+ *
+ * @section usb_1 Driver State Machine
+ * The driver implements a state machine internally, not all the driver
+ * functionalities can be used in any moment, any transition not explicitly
+ * shown in the following diagram has to be considered an error and shall
+ * be captured by an assertion (if enabled).
+ * @if LATEX_PDF
+ * @dot
+ digraph example {
+ size="5, 7";
+ rankdir="LR";
+ node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true",
+ width="0.9", height="0.9"];
+ edge [fontname=Helvetica, fontsize=8];
+
+ stop [label="USB_STOP\nLow Power"];
+ uninit [label="USB_UNINIT", style="bold"];
+ ready [label="USB_READY\nClock Enabled"];
+ selected [label="\nUSB_SELECTED\naddress\nassigned"];
+ active [label="\nUSB_ACTIVE\nconfiguration\nselected"];
+
+ uninit -> stop [label=" usbInit()", constraint=false];
+ stop -> stop [label="\nusbStop()"];
+ stop -> ready [label="\nusbStart()"];
+ ready -> stop [label="\nusbStop()"];
+ ready -> ready [label="\n\nusbStart()"];
+ ready -> ready [label="\nSUSPEND/WAKEUP\n>event_cb<"];
+ ready -> selected [label="\nSET_ADDRESS\n>event_cb<"];
+ selected -> stop [label="\nusbStop()"];
+ selected -> ready [label="\nUSB RESET\n>event_cb<"];
+ selected -> selected [label="\nSUSPEND/WAKEUP\n>event_cb<\n\nValid EP0 Message\n>requests_hook_cb<\n\nGET DESCRIPTOR\n>get_descriptor_cb<"];
+ selected -> active [label="\nSET_CONF(n)\n>event_cb<"];
+ active -> stop [label="\nusbStop()"];
+ active -> selected [label="\nSET_CONF(0)\n>event_cb<"];
+ active -> active [label="\nSUSPEND/WAKEUP\n>event_cb<\n\nValid EP0 Message\n>requests_hook_cb<\n\nGET DESCRIPTOR\n>get_descriptor_cb<\n\nEndpoints Activity\n >in_cb< or >out_cb<"];
+ active -> ready [label="\nUSB RESET\n>event_cb<"];
+ }
+ * @enddot
+ * @else
+ * @dot
+ digraph example {
+ rankdir="LR";
+ node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true",
+ width="0.9", height="0.9"];
+ edge [fontname=Helvetica, fontsize=8];
+
+ stop [label="USB_STOP\nLow Power"];
+ uninit [label="USB_UNINIT", style="bold"];
+ ready [label="USB_READY\nClock Enabled"];
+ selected [label="\nUSB_SELECTED\naddress\nassigned"];
+ active [label="\nUSB_ACTIVE\nconfiguration\nselected"];
+
+ uninit -> stop [label=" usbInit()", constraint=false];
+ stop -> stop [label="\nusbStop()"];
+ stop -> ready [label="\nusbStart()"];
+ ready -> stop [label="\nusbStop()"];
+ ready -> ready [label="\n\nusbStart()"];
+ ready -> ready [label="\nSUSPEND/WAKEUP\n>event_cb<"];
+ ready -> selected [label="\nSET_ADDRESS\n>event_cb<"];
+ selected -> stop [label="\nusbStop()"];
+ selected -> ready [label="\nUSB RESET\n>event_cb<"];
+ selected -> selected [label="\nSUSPEND/WAKEUP\n>event_cb<\n\nValid EP0 Message\n>requests_hook_cb<\n\nGET DESCRIPTOR\n>get_descriptor_cb<"];
+ selected -> active [label="\nSET_CONF(n)\n>event_cb<"];
+ active -> stop [label="\nusbStop()"];
+ active -> selected [label="\nSET_CONF(0)\n>event_cb<"];
+ active -> active [label="\nSUSPEND/WAKEUP\n>event_cb<\n\nValid EP0 Message\n>requests_hook_cb<\n\nGET DESCRIPTOR\n>get_descriptor_cb<\n\nEndpoints Activity\n >in_cb< or >out_cb<"];
+ active -> ready [label="\nUSB RESET\n>event_cb<"];
+ }
+ * @enddot
+ * @endif
+ *
+ * @section usb_2 USB Operations
+ * The USB driver is quite complex and USB is complex in itself, it is
+ * recommended to study the USB specification before trying to use the
+ * driver.
+ *
+ * @subsection usb_2_1 USB Implementation
+ * The USB driver abstracts the inner details of the underlying USB hardware.
+ * The driver works asynchronously and communicates with the application
+ * using callbacks. The application is responsible of the descriptors and
+ * strings required by the USB device class to be implemented and of the
+ * handling of the specific messages sent over the endpoint zero. Standard
+ * messages are handled internally to the driver. The application can use
+ * hooks in order to handle custom messages or override the handling of the
+ * default handling of standard messages.
+ *
+ * @subsection usb_2_2 USB Endpoints
+ * USB endpoints are the objects that the application uses to exchange
+ * data with the host. There are two kind of endpoints:
+ * - <b>IN</b> endpoints are used by the application to transmit data to
+ * the host.<br>
+ * - <b>OUT</b> endpoints are used by the application to receive data from
+ * the host.
+ * .
+ * The driver invokes a callback after finishing an IN or OUT transaction.
+ * States diagram for OUT endpoints in transaction mode:
+ * @dot
+ digraph example {
+ rankdir="LR";
+ node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true",
+ width="0.9", height="0.9"];
+ edge [fontname=Helvetica, fontsize=8];
+
+ disabled [label="EP_DISABLED\nDisabled", style="bold"];
+ receiving [label="EP_BUSY\nReceiving"];
+ idle [label="EP_IDLE\nReady"];
+
+ disabled -> idle [label="\nusbInitEndpointI()"];
+ idle -> receiving [label="\nusbPrepareReceive()\nusbStartReceiveI()"];
+ receiving -> receiving [label="\nmore packets"];
+ receiving -> idle [label="\nreception end\n>out_cb<"];
+ receiving -> disabled [label="\nUSB RESET\nusbDisableEndpointsI()"];
+ idle -> disabled [label="\nUSB RESET\nusbDisableEndpointsI()"];
+ }
+ * @enddot
+ * <br><br>
+ * States diagram for IN endpoints in transaction mode:
+ * @dot
+ digraph example {
+ rankdir="LR";
+ node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true",
+ width="0.9", height="0.9"];
+ edge [fontname=Helvetica, fontsize=8];
+
+ disabled [label="EP_DISABLED\nDisabled", style="bold"];
+ transmitting [label="EP_BUSY\nTransmitting"];
+ idle [label="EP_IDLE\nReady"];
+
+ disabled -> idle [label="\usbInitEndpointI()"];
+ idle -> transmitting [label="\nusbPrepareTransmit()\nusbStartTransmitI()"];
+ transmitting -> transmitting [label="\nmore packets"];
+ transmitting -> idle [label="\ntransmission end\n>in_cb<"];
+ transmitting -> disabled [label="\nUSB RESET\nusbDisableEndpointsI()"];
+ idle -> disabled [label="\nUSB RESET\nusbDisableEndpointsI()"];
+ }
+ * @enddot
+ * <br><br>
+ *
+ * @subsection usb_2_4 USB Callbacks
+ * The USB driver uses callbacks in order to interact with the application.
+ * There are several kinds of callbacks to be handled:
+ * - Driver events callback. As example errors, suspend event, reset event
+ * etc.
+ * - Messages Hook callback. This hook allows the application to implement
+ * handling of custom messages or to override the default handling of
+ * standard messages on endpoint zero.
+ * - Descriptor Requested callback. When the driver endpoint zero handler
+ * receives a GET DESCRIPTOR message and needs to send a descriptor to
+ * the host it queries the application using this callback.
+ * - Start of Frame callback. This callback is invoked each time a SOF
+ * packet is received.
+ * - Endpoint callbacks. Each endpoint informs the application about I/O
+ * conditions using those callbacks.
+ * .
+ *
+ * @ingroup HAL_NORMAL_DRIVERS
+ */
|