I2C. Merged code from trunk.

git-svn-id: svn://svn.code.sf.net/p/chibios/svn/branches/i2c_dev@3036 35acf78f-673a-0410-8e92-d51de3d6d3f4

1 files changed, 239 insertions, 0 deletions

diff --git a/os/hal/dox/usb.dox b/os/hal/dox/usb.dox
new file mode 100644
index 000000000..62b3aaf12
--- /dev/null
+++ b/os/hal/dox/usb.dox
@@ -0,0 +1,239 @@
+/*

+    ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010,

+                 2011 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 (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:

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

+ * .

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

+ *   <br><br>

+ *   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="\usbInitEndpointI()"];

+    receiving -> idle [label="\npacket received\n>out_cb<"];

+    idle -> receiving [label="\nusbReadPacketI()"];

+    receiving -> disabled [label="\nUSB RESET\nusbDisableEndpointsI()"];

+    idle -> disabled [label="\nUSB RESET\nusbDisableEndpointsI()"];

+  }

+ *   @enddot

+ *   <br><br>

+ *   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="\usbInitEndpointI()"];

+    idle -> transmitting [label="\nusbWritePacketI()"];

+    transmitting -> idle [label="\npacket sent\n>in_cb<"];

+    transmitting -> disabled [label="\nUSB RESET\nusbDisableEndpointsI()"];

+    idle -> disabled [label="\nUSB RESET\nusbDisableEndpointsI()"];

+  }

+ *   @enddot

+ *   <br><br>

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

+ *   <br><br>

+ *   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="\usbInitEndpointI()"];

+    idle -> receiving [label="\usbStartReceiveI()"];

+    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="\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_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.<br>

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

+ */