87 lines
3.8 KiB
Plaintext
87 lines
3.8 KiB
Plaintext
/*
|
|
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 <http://www.gnu.org/licenses/>.
|
|
*/
|
|
|
|
/**
|
|
* @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:
|
|
* - <b>IN</b> endpoints are used by the application to transmit data to
|
|
* the host.
|
|
* - <b>OUT</b> endpoints are used by the application to receive data from
|
|
* the host.
|
|
* .
|
|
* In ChibiOS/RT the endpoints can be configured in two distinct ways:
|
|
* - <b>Packet Mode</b>. 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.
|
|
* - <b>Transaction Mode</b>. 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
|
|
*/
|