/* ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010, 2011,2012 Giovanni Di Sirio. This file is part of ChibiOS/RT. ChibiOS/RT is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. ChibiOS/RT is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see . --- A special exception to the GPL can be applied should you wish to distribute a combined work that includes ChibiOS/RT, without being obliged to provide the source code for any proprietary components. See the file exception.txt for full details of how and when the exception can be applied. */ /** * @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"]; configured [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 -> 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 -> configured [label="\nSET_CONF(n)\n>event_cb<"]; configured -> selected [label="\nSET_CONF(0)\n>event_cb<"]; configured -> configured [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<"]; configured -> 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"]; configured [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 -> 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 -> configured [label="\nSET_CONF(n)\n>event_cb<"]; configured -> selected [label="\nSET_CONF(0)\n>event_cb<"]; configured -> configured [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<"]; configured -> 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. * . * In ChibiOS/RT the endpoints can be configured in two distinct ways: * - Packet Mode. In this mode the driver invokes a callback each * time a packet has been received or transmitted. This mode is especially * suited for those applications handling continuous streams of data. *

* States diagram for OUT endpoints in packet 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 Packet"]; idle [label="EP_IDLE\nPacket in Buffer"]; disabled -> receiving [label="\nusbInitEndpointI()"]; receiving -> idle [label="\npacket received\n>out_cb<"]; idle -> receiving [label="\nusbReadPacketBuffer()\nusbStartReceiveI()"]; receiving -> disabled [label="\nUSB RESET\nusbDisableEndpointsI()"]; idle -> disabled [label="\nUSB RESET\nusbDisableEndpointsI()"]; } * @enddot *

* States diagram for IN endpoints in packet 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\nSending Packet"]; idle [label="EP_IDLE\nBuffer Empty"]; disabled -> idle [label="\nusbInitEndpointI()"]; idle -> transmitting [label="\nusbWritePacketBuffer()\nusbStartTransmitI()"]; transmitting -> idle [label="\npacket sent\n>in_cb<"]; transmitting -> disabled [label="\nUSB RESET\nusbDisableEndpointsI()"]; idle -> disabled [label="\nUSB RESET\nusbDisableEndpointsI()"]; } * @enddot *

* - Transaction Mode. In this mode the driver invokes a callback * only after a large, potentially multi-packet, transfer has been * completed, a callback is invoked only at the end of the transfer. *

* 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_3 USB Packet Buffers * An important difference between packet and transaction modes is that there * is a dedicated endpoint buffer in packet mode while in transaction mode * the application has to specify its own buffer for duration of the whole * transfer.
* Packet buffers cannot be accessed directly by the application because those * could not be necessarily memory mapped, a buffer could be a FIFO or some * other kind of memory accessible in a special way depending on the * underlying hardware architecture, the functions @p usbReadPacketI() and * @p usbWritePacketI() allow to access packet buffers in an abstract way. * * @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 IO */