From a3e9966359c432405c8ab1eb49a27133e5271ba2 Mon Sep 17 00:00:00 2001 From: Giovanni Di Sirio Date: Mon, 21 Jan 2019 19:42:49 +0000 Subject: More renaming for consistency. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@12571 110e8d01-0319-4d1e-a829-52ad28d1bb01 --- os/hal/dox/hal_usb.dox | 180 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 os/hal/dox/hal_usb.dox (limited to 'os/hal/dox/hal_usb.dox') 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: + * - IN endpoints are used by the application to transmit data to + * the host.
+ * - OUT 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 + *

+ * 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 + *

+ * + * @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 + */ -- cgit v1.2.3