From 2f003bd7214c54560500b281661281a5c6903cee Mon Sep 17 00:00:00 2001 From: gdisirio Date: Thu, 10 Feb 2011 15:47:43 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@2728 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/hal/dox/usb.dox | 86 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 os/hal/dox/usb.dox (limited to 'os/hal/dox/usb.dox') diff --git a/os/hal/dox/usb.dox b/os/hal/dox/usb.dox new file mode 100644 index 000000000..1f843efae --- /dev/null +++ b/os/hal/dox/usb.dox @@ -0,0 +1,86 @@ +/* + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 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 . +*/ + +/** + * @defgroup USB USB Driver + * @brief Generic USB Driver. + * @details This module implements a generic USB driver. + * @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 + * @else + * @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. + * - 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. + * . + * . + * @subsection usb_2_3 USB Callbacks + * The USB driver uses callbacks in order to interact with the application. + * There are several kind of callbacks to be handled: + * - Driver-wide 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. + * - Descriptor requested callback. When the driver endpoint zero handler + * needs to serve 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 + */ -- cgit v1.2.3