diff options
Diffstat (limited to 'os/hal/dox')
| -rw-r--r-- | os/hal/dox/adc.dox | 10 | ||||
| -rw-r--r-- | os/hal/dox/can.dox | 6 | ||||
| -rw-r--r-- | os/hal/dox/gpt.dox | 78 | ||||
| -rw-r--r-- | os/hal/dox/hal.dox | 24 | ||||
| -rw-r--r-- | os/hal/dox/i2c.dox | 8 | ||||
| -rw-r--r-- | os/hal/dox/icu.dox | 115 | ||||
| -rw-r--r-- | os/hal/dox/mac.dox | 7 | ||||
| -rw-r--r-- | os/hal/dox/mmc_spi.dox | 5 | ||||
| -rw-r--r-- | os/hal/dox/pal.dox | 29 | ||||
| -rw-r--r-- | os/hal/dox/pwm.dox | 13 | ||||
| -rw-r--r-- | os/hal/dox/sdc.dox | 109 | ||||
| -rw-r--r-- | os/hal/dox/serial.dox | 43 | ||||
| -rw-r--r-- | os/hal/dox/serial_usb.dox | 56 | ||||
| -rw-r--r-- | os/hal/dox/spi.dox | 9 | ||||
| -rw-r--r-- | os/hal/dox/uart.dox | 44 | ||||
| -rw-r--r-- | os/hal/dox/usb.dox | 239 |
16 files changed, 720 insertions, 75 deletions
diff --git a/os/hal/dox/adc.dox b/os/hal/dox/adc.dox index 9ebfca99c..bb8ff014f 100644 --- a/os/hal/dox/adc.dox +++ b/os/hal/dox/adc.dox @@ -1,5 +1,6 @@ /*
- ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio.
+ ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010,
+ 2011 Giovanni Di Sirio.
This file is part of ChibiOS/RT.
@@ -20,7 +21,8 @@ /**
* @defgroup ADC ADC Driver
* @brief Generic ADC Driver.
- * @details This module implements a generic ADC driver.
+ * @details This module implements a generic ADC (Analog to Digital Converter)
+ * driver supporting a variety of buffer and conversion modes.
* @pre In order to use the ADC driver the @p HAL_USE_ADC option
* must be enabled in @p halconf.h.
*
@@ -52,7 +54,7 @@ active -> ready [label="\nadcStopConversion()\nsync return"];
active -> active [label="\nasync callback (half buffer)\nasync callback (full buffer circular)\n>acg_endcb<"];
active -> complete [label="\nasync callback (full buffer)\n>acg_endcb<"];
- complete -> active [label="\nadcStartConversionI()\nthen\ncallback return()"];
+ complete -> active [label="\nadcStartConversionI()\nthen\ncallback return"];
complete -> ready [label="\ncallback return"];
}
* @enddot
@@ -78,7 +80,7 @@ active -> ready [label="\nadcStopConversion()\nsync return"];
active -> active [label="\nasync callback (half buffer)\nasync callback (full buffer circular)\n>acg_endcb<"];
active -> complete [label="\nasync callback (full buffer)\n>acg_endcb<"];
- complete -> active [label="\nadcStartConversionI()\nthen\ncallback return()"];
+ complete -> active [label="\nadcStartConversionI()\nthen\ncallback return"];
complete -> ready [label="\ncallback return"];
}
* @enddot
diff --git a/os/hal/dox/can.dox b/os/hal/dox/can.dox index 81ee24e8b..1a0c81c0d 100644 --- a/os/hal/dox/can.dox +++ b/os/hal/dox/can.dox @@ -1,5 +1,6 @@ /*
- ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio.
+ ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010,
+ 2011 Giovanni Di Sirio.
This file is part of ChibiOS/RT.
@@ -20,7 +21,8 @@ /**
* @defgroup CAN CAN Driver
* @brief Generic CAN Driver.
- * @details This module implements a generic CAN driver.
+ * @details This module implements a generic CAN (Controller Area Network)
+ * driver allowing the exchange of information at frame level.
* @pre In order to use the CAN driver the @p HAL_USE_CAN option
* must be enabled in @p halconf.h.
*
diff --git a/os/hal/dox/gpt.dox b/os/hal/dox/gpt.dox new file mode 100644 index 000000000..d51ad6af3 --- /dev/null +++ b/os/hal/dox/gpt.dox @@ -0,0 +1,78 @@ +/*
+ 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 GPT GPT Driver
+ * @brief Generic GPT Driver.
+ * @details This module implements a generic GPT (General Purpose Timer)
+ * driver. The timer can be programmed in order to trigger callbacks
+ * after a specified time period or continuously with a specified
+ * interval.
+ * @pre In order to use the GPT driver the @p HAL_USE_GPT option
+ * must be enabled in @p halconf.h.
+ *
+ * @section gpt_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).
+ * @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="GPT_STOP\nLow Power"];
+ uninit [label="GPT_UNINIT", style="bold"];
+ ready [label="GPT_READY\nClock Enabled"];
+ continuous [label="GPT_CONT..S\nContinuous\nMode"];
+ oneshot [label="GPT_ONESHOT\nOne Shot\nMode"];
+
+ uninit -> stop [label=" gptInit()", constraint=false];
+ stop -> stop [label="\ngptStop()"];
+ stop -> ready [label="\ngptStart()"];
+ ready -> stop [label="\ngptStop()"];
+ ready -> ready [label="\ngptStart()"];
+ ready -> continuous [label="\ngptStartContinuous()"];
+ continuous -> ready [label="\ngptStopTimer()"];
+ continuous -> continuous [label=">callback<"];
+ ready -> oneshot [label="\ngptStartOneShot()\ngptPolledDelay()"];
+ oneshot -> ready [label="\n>callback<\nor\nDelay Over"];
+ }
+ * @enddot
+ *
+ * @section gpt_2 GPT Operations.
+ * This driver abstracts a generic timer composed of:
+ * - A clock prescaler.
+ * - A main up counter.
+ * - A comparator register that resets the main counter to zero when the limit
+ * is reached. A callback is invoked when this happens.
+ * .
+ * The timer can operate in three different modes:
+ * - <b>Continuous Mode</b>, a periodic callback is invoked until the driver
+ * is explicitly stopped.
+ * - <b>One Shot Mode</b>, a callback is invoked after the programmed period
+ * and then the timer automatically stops.
+ * - <b>Delay Mode</b>, the timer is used for inserting a brief delay into
+ * the execution flow, no callback is invoked in this mode.
+ * .
+ * @ingroup IO
+ */
diff --git a/os/hal/dox/hal.dox b/os/hal/dox/hal.dox index 02d09c0d8..15b4401fb 100644 --- a/os/hal/dox/hal.dox +++ b/os/hal/dox/hal.dox @@ -1,5 +1,6 @@ /*
- ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio.
+ ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010,
+ 2011 Giovanni Di Sirio.
This file is part of ChibiOS/RT.
@@ -19,16 +20,17 @@ /**
* @defgroup HAL HAL Driver
- * @brief Hardware Abstraction Layer.
- * @details The HAL driver performs the system initialization and includes
- * the platform support code shared by the other drivers. This driver does
- * contain any API function except for a general initialization function
- * @p halInit() that must be invoked before any HAL service can be used,
- * usually the HAL initialization should be performed immediately before the
- * kernel initialization.<br>
- * Some HAL driver implementations also offer a custom early clock
- * setum function that can be invoked before the C runtime initialization
- * in order to accellerate the startup time.
+ * @brief Hardware Abstraction Layer.
+ * @details The HAL (Hardware Abstraction Layer) driver performs the system
+ * initialization and includes the platform support code shared by
+ * the other drivers. This driver does contain any API function
+ * except for a general initialization function @p halInit() that
+ * must be invoked before any HAL service can be used, usually the
+ * HAL initialization should be performed immediately before the
+ * kernel initialization.<br>
+ * Some HAL driver implementations also offer a custom early clock
+ * setup function that can be invoked before the C runtime
+ * initialization in order to accelerate the startup time.
*
* @ingroup IO
*/
diff --git a/os/hal/dox/i2c.dox b/os/hal/dox/i2c.dox index 151c7a66e..1ffd2da47 100644 --- a/os/hal/dox/i2c.dox +++ b/os/hal/dox/i2c.dox @@ -1,5 +1,6 @@ /*
- ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio.
+ ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010,
+ 2011 Giovanni Di Sirio.
This file is part of ChibiOS/RT.
@@ -19,8 +20,9 @@ /**
* @defgroup I2C I2C Driver
- * @brief Generic I2C Driver.
- * @details This module implements a generic I2C driver.
+ * @brief Generic I2C Driver.
+ * @details This module implements a generic I2C (Inter-Integrated Circuit)
+ * driver.
* @pre In order to use the I2C driver the @p HAL_USE_I2C option
* must be enabled in @p halconf.h.
*
diff --git a/os/hal/dox/icu.dox b/os/hal/dox/icu.dox new file mode 100644 index 000000000..c90dc237d --- /dev/null +++ b/os/hal/dox/icu.dox @@ -0,0 +1,115 @@ +/*
+ 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 ICU ICU Driver
+ * @brief Generic ICU Driver.
+ * @details This module implements a generic ICU (Input Capture Unit) driver.
+ * @pre In order to use the ICU driver the @p HAL_USE_ICU option
+ * must be enabled in @p halconf.h.
+ *
+ * @section icu_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=Sans, fontsize=8, fixedsize="true", width="0.9", height="0.9"];
+ edge [fontname=Sans, fontsize=8];
+
+ stop [label="ICU_STOP\nLow Power"];
+ uninit [label="ICU_UNINIT", style="bold"];
+ ready [label="ICU_READY\nClock Enabled"];
+ waiting [label="ICU_WAITING"];
+ active [label="ICU_ACTIVE"];
+ idle [label="ICU_IDLE"];
+
+ uninit -> stop [label=" icuInit()", constraint=false];
+ stop -> stop [label="\nicuStop()"];
+ stop -> ready [label="\nicuStart()"];
+ ready -> stop [label="\nicuStop()"];
+ ready -> ready [label="\nicuStart()\nicuDisable()"];
+ ready -> waiting [label="\nicuEnable()"];
+ waiting -> active [label="\nStart Front"];
+ waiting -> ready [label="\nicuDisable()"];
+ active -> idle [label="\nStop Front\n>width_cb<"];
+ active -> ready [label="\nicuDisable()\nicuDisableI()"];
+ idle -> active [label="\nStart Front\n>period_cb<"];
+ idle -> ready [label="\nicuDisable()\nicuDisableI()"];
+ }
+ * @enddot
+ * @else
+ * @dot
+ digraph example {
+ rankdir="LR";
+
+ node [shape=circle, fontname=Sans, fontsize=8, fixedsize="true", width="0.9", height="0.9"];
+ edge [fontname=Sans, fontsize=8];
+
+ stop [label="ICU_STOP\nLow Power"];
+ uninit [label="ICU_UNINIT", style="bold"];
+ ready [label="ICU_READY\nClock Enabled"];
+ waiting [label="ICU_WAITING"];
+ active [label="ICU_ACTIVE"];
+ idle [label="ICU_IDLE"];
+
+ uninit -> stop [label=" icuInit()", constraint=false];
+ stop -> stop [label="\nicuStop()"];
+ stop -> ready [label="\nicuStart()"];
+ ready -> stop [label="\nicuStop()"];
+ ready -> ready [label="\nicuStart()\nicuDisable()"];
+ ready -> waiting [label="\nicuEnable()"];
+ waiting -> active [label="\nStart Front"];
+ waiting -> ready [label="\nicuDisable()"];
+ active -> idle [label="\nStop Front\n>width_cb<"];
+ active -> ready [label="\nicuDisable()\nicuDisableI()"];
+ idle -> active [label="\nStart Front\n>period_cb<"];
+ idle -> ready [label="\nicuDisable()\nicuDisableI()"];
+ }
+ * @enddot
+ * @endif
+ *
+ * @section icu_2 ICU Operations.
+ * This driver abstracts a generic Input Capture Unit composed of:
+ * - A clock prescaler.
+ * - A main up counter.
+ * - Two capture registers triggered by the rising and falling edges on
+ * the sampled input.
+ * .
+ * The ICU unit can be programmed to synchronize on the rising or falling
+ * edge of the sample input:
+ * - <b>ICU_INPUT_ACTIVE_HIGH</b>, a rising edge is the start signal.
+ * - <b>ICU_INPUT_ACTIVE_LOW</b>, a falling edge is the start signal.
+ * .
+ * After the activation the ICU unit can be in one of the following
+ * states at any time:
+ * - <b>ICU_WAITING</b>, waiting the first start signal.
+ * - <b>ICU_ACTIVE</b>, after a start signal.
+ * - <b>ICU_IDLE</b>, after a stop signal.
+ * .
+ * Callbacks are invoked when start or stop signals occur.
+ *
+ * @ingroup IO
+ */
diff --git a/os/hal/dox/mac.dox b/os/hal/dox/mac.dox index 778795f15..01a89d825 100644 --- a/os/hal/dox/mac.dox +++ b/os/hal/dox/mac.dox @@ -1,5 +1,6 @@ /*
- ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio.
+ ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010,
+ 2011 Giovanni Di Sirio.
This file is part of ChibiOS/RT.
@@ -20,8 +21,8 @@ /**
* @defgroup MAC MAC Driver
* @brief Generic MAC driver.
- * @details This module implements a generic interface for MAC (Media
- * Access Control) drivers, as example Ethernet controllers.
+ * @details This module implements a generic MAC (Media Access Control)
+ * driver for Ethernet controllers.
* @pre In order to use the MAC driver the @p HAL_USE_MAC option
* must be enabled in @p halconf.h.
*
diff --git a/os/hal/dox/mmc_spi.dox b/os/hal/dox/mmc_spi.dox index e18ff1a8a..480240c00 100644 --- a/os/hal/dox/mmc_spi.dox +++ b/os/hal/dox/mmc_spi.dox @@ -1,5 +1,6 @@ /*
- ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio.
+ ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010,
+ 2011 Giovanni Di Sirio.
This file is part of ChibiOS/RT.
@@ -20,7 +21,7 @@ /**
* @defgroup MMC_SPI MMC over SPI Driver
* @brief Generic MMC driver.
- * @details This module implements a portable MMC driver that uses a SPI
+ * @details This module implements a portable MMC/SD driver that uses a SPI
* driver as physical layer.
* @pre In order to use the MMC_SPI driver the @p HAL_USE_MMC_SPI option
* must be enabled in @p halconf.h.
diff --git a/os/hal/dox/pal.dox b/os/hal/dox/pal.dox index 4c7fe685a..5ffc763a8 100644 --- a/os/hal/dox/pal.dox +++ b/os/hal/dox/pal.dox @@ -1,5 +1,6 @@ /*
- ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio.
+ ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010,
+ 2011 Giovanni Di Sirio.
This file is part of ChibiOS/RT.
@@ -19,19 +20,21 @@ /**
* @defgroup PAL PAL Driver
- * @brief I/O Ports Abstraction Layer
+ * @brief I/O Ports Abstraction Layer
* @details This module defines an abstract interface for digital I/O ports.
- * Note that most I/O ports functions are just macros. The macros
- * have default software implementations that can be redefined in a
- * PAL Low Level Driver if the target hardware supports special features like,
- * as example, atomic bit set/reset/masking. Please refer to the ports specific
- * documentation for details.<br>
- * The @ref PAL has the advantage to make the access to the I/O ports platform
- * independent and still be optimized for the specific architectures.<br>
- * Note that the PAL Low Level Driver may also offer non standard macro and
- * functions in order to support specific features but, of course, the use of
- * such interfaces would not be portable. Such interfaces shall be marked with
- * the architecture name inside the function names.
+ * Note that most I/O ports functions are just macros. The macros
+ * have default software implementations that can be redefined in a
+ * PAL Low Level Driver if the target hardware supports special
+ * features like, for example, atomic bit set/reset/masking. Please
+ * refer to the ports specific documentation for details.<br>
+ * The @ref PAL has the advantage to make the access to the I/O
+ * ports platform independent and still be optimized for the specific
+ * architectures.<br>
+ * Note that the PAL Low Level Driver may also offer non standard
+ * macro and functions in order to support specific features but,
+ * of course, the use of such interfaces would not be portable.
+ * Such interfaces shall be marked with the architecture name inside
+ * the function names.
* @pre In order to use the PAL driver the @p HAL_USE_PAL option
* must be enabled in @p halconf.h.
*
diff --git a/os/hal/dox/pwm.dox b/os/hal/dox/pwm.dox index 6fbe2efa1..fbf61ca9f 100644 --- a/os/hal/dox/pwm.dox +++ b/os/hal/dox/pwm.dox @@ -1,5 +1,6 @@ /*
- ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio.
+ ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010,
+ 2011 Giovanni Di Sirio.
This file is part of ChibiOS/RT.
@@ -19,8 +20,9 @@ /**
* @defgroup PWM PWM Driver
- * @brief Generic PWM Driver.
- * @details This module implements a generic PWM driver.
+ * @brief Generic PWM Driver.
+ * @details This module implements a generic PWM (Pulse Width Modulation)
+ * driver.
* @pre In order to use the PWM driver the @p HAL_USE_PWM option
* must be enabled in @p halconf.h.
*
@@ -45,8 +47,9 @@ }
* @enddot
*
- * @section pwm_1 PWM Operations.
- * This driver abstracts a generic PWM times composed of:
+ * @section pwm_2 PWM Operations.
+ * This driver abstracts a generic PWM timer composed of:
+ * - A clock prescaler.
* - A main up counter.
* - A comparator register that resets the main counter to zero when the limit
* is reached. An optional callback can be generated when this happens.
diff --git a/os/hal/dox/sdc.dox b/os/hal/dox/sdc.dox new file mode 100644 index 000000000..df88796af --- /dev/null +++ b/os/hal/dox/sdc.dox @@ -0,0 +1,109 @@ +/*
+ 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 SDC SDC Driver
+ * @brief Generic SD Card Driver.
+ * @details This module implements a generic SDC (Secure Digital Card) driver.
+ * @pre In order to use the SDC driver the @p HAL_USE_SDC option
+ * must be enabled in @p halconf.h.
+ *
+ * @section sdc_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=Sans, fontsize=8, fixedsize="true", width="0.9", height="0.9"];
+ edge [fontname=Sans, fontsize=8];
+
+ stop [label="SDC_STOP\nLow Power"];
+ uninit [label="SDC_UNINIT", style="bold"];
+ ready [label="SDC_READY\nClock Enabled"];
+ connecting [label="SDC_CONN.ING\nConnecting"];
+ disconnecting [label="SDC_DISC.ING\nDisconnecting"];
+ active [label="SDC_ACTIVE\nCard Ready"];
+ reading [label="SDC_READING\nReading"];
+ writing [label="SDC_WRITING\nWriting"];
+
+ uninit -> stop [label=" sdcInit()", constraint=false];
+ stop -> stop [label="\nsdcStop()"];
+ stop -> ready [label="\nsdcStart()"];
+ ready -> stop [label="\nsdcStop()"];
+ ready -> ready [label="\nsdcStart()\nsdcDisconnect()"];
+ ready -> connecting [label="\nsdcConnect()"];
+ connecting -> active [label="\nconnection\nsuccessful"];
+ connecting -> active [label="\nsdcConnect()", dir="back"];
+ connecting -> ready [label="\nconnection\nfailed"];
+ disconnecting -> active [label="\nsdcDisconnect()", dir="back"];
+ ready -> disconnecting [label="\ndisconnection\nfinished", dir="back"];
+ active -> reading [label="\nsdcRead()"];
+ reading -> active [label="\nread finished\nread error"];
+ active -> writing [label="\nsdcWrite()"];
+ writing -> active [label="\nwrite finished\nwrite error"];
+ }
+ * @enddot
+ * @else
+ * @dot
+ digraph example {
+ rankdir="LR";
+
+ node [shape=circle, fontname=Sans, fontsize=8, fixedsize="true", width="0.9", height="0.9"];
+ edge [fontname=Sans, fontsize=8];
+
+ stop [label="SDC_STOP\nLow Power"];
+ uninit [label="SDC_UNINIT", style="bold"];
+ ready [label="SDC_READY\nClock Enabled"];
+ connecting [label="SDC_CONN.ING\nConnecting"];
+ disconnecting [label="SDC_DISC.ING\nDisconnecting"];
+ active [label="SDC_ACTIVE\nCard Ready"];
+ reading [label="SDC_READING\nReading"];
+ writing [label="SDC_WRITING\nWriting"];
+
+ uninit -> stop [label=" sdcInit()", constraint=false];
+ stop -> stop [label="\nsdcStop()"];
+ stop -> ready [label="\nsdcStart()"];
+ ready -> stop [label="\nsdcStop()"];
+ ready -> ready [label="\nsdcStart()\nsdcDisconnect()"];
+ ready -> connecting [label="\nsdcConnect()"];
+ connecting -> active [label="\nconnection\nsuccessful"];
+ connecting -> active [label="\nsdcConnect()", dir="back"];
+ connecting -> ready [label="\nconnection\nfailed"];
+ disconnecting -> active [label="\nsdcDisconnect()", dir="back"];
+ ready -> disconnecting [label="\ndisconnection\nfinished", dir="back"];
+ active -> reading [label="\nsdcRead()"];
+ reading -> active [label="\nread finished\nread error"];
+ active -> writing [label="\nsdcWrite()"];
+ writing -> active [label="\nwrite finished\nwrite error"];
+ }
+ * @enddot
+ * @endif
+ *
+ * @section sdc_2 SDC Operations.
+ * This driver allows to read or write single or multiple 512 bytes blocks
+ * on a SD Card.
+ *
+ * @ingroup IO
+ */
diff --git a/os/hal/dox/serial.dox b/os/hal/dox/serial.dox index 071b2dac5..5b68f9c9c 100644 --- a/os/hal/dox/serial.dox +++ b/os/hal/dox/serial.dox @@ -1,5 +1,6 @@ /*
- ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio.
+ ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010,
+ 2011 Giovanni Di Sirio.
This file is part of ChibiOS/RT.
@@ -19,16 +20,42 @@ /**
* @defgroup SERIAL Serial Driver
- * @brief Generic Serial Driver.
+ * @brief Generic Serial Driver.
* @details This module implements a generic full duplex serial driver. The
- * driver implements a @p SerialDriver interface and uses I/O Queues for
- * communication between the upper and the lower driver. Event flags are used
- * to notify the application about incoming data, outgoing data and other I/O
- * events.<br>
- * The module also contains functions that make the implementation of the
- * interrupt service routines much easier.
+ * driver implements a @p SerialDriver interface and uses I/O Queues
+ * for communication between the upper and the lower driver. Event
+ * flags are used to notify the application about incoming data,
+ * outgoing data and other I/O events.<br>
+ * The module also contains functions that make the implementation
+ * of the interrupt service routines much easier.
* @pre In order to use the SERIAL driver the @p HAL_USE_SERIAL option
* must be enabled in @p halconf.h.
*
+ *
+ * @section serial_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).
+ * @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];
+
+ uninit [label="SD_UNINIT", style="bold"];
+ stop [label="SD_STOP\nLow Power"];
+ ready [label="SD_READY\nClock Enabled"];
+
+ uninit -> stop [label=" sdInit()"];
+ stop -> stop [label="\nsdStop()"];
+ stop -> ready [label="\nsdStart()"];
+ ready -> stop [label="\nsdStop()"];
+ ready -> ready [label="\nsdStart()"];
+ ready -> ready [label="\nAny I/O operation"];
+ }
+ * @enddot
+ *
* @ingroup IO
*/
diff --git a/os/hal/dox/serial_usb.dox b/os/hal/dox/serial_usb.dox new file mode 100644 index 000000000..c477b5288 --- /dev/null +++ b/os/hal/dox/serial_usb.dox @@ -0,0 +1,56 @@ +/*
+ 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 SERIAL_USB Serial over USB Driver
+ * @brief Serial over USB Driver.
+ * @details This module implements an USB Communication Device Class
+ * (CDC) as a normal serial communication port accessible from
+ * the device application.
+ * @pre In order to use the USB over Serial driver the
+ * @p HAL_USE_SERIAL_USB option must be enabled in @p halconf.h.
+ *
+ * @section usb_serial_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).
+ * @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];
+
+ uninit [label="SDU_UNINIT", style="bold"];
+ stop [label="SDU_STOP\nLow Power"];
+ ready [label="SDU_READY\nClock Enabled"];
+
+ uninit -> stop [label=" sduInit()"];
+ stop -> stop [label="\nsduStop()"];
+ stop -> ready [label="\nsduStart()"];
+ ready -> stop [label="\nsduStop()"];
+ ready -> ready [label="\nsduStart()"];
+ ready -> ready [label="\nAny I/O operation"];
+ }
+ * @enddot
+ *
+ * @ingroup IO
+ */
diff --git a/os/hal/dox/spi.dox b/os/hal/dox/spi.dox index 7f68f3c40..047ff646e 100644 --- a/os/hal/dox/spi.dox +++ b/os/hal/dox/spi.dox @@ -1,5 +1,6 @@ /*
- ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio.
+ ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010,
+ 2011 Giovanni Di Sirio.
This file is part of ChibiOS/RT.
@@ -19,8 +20,10 @@ /**
* @defgroup SPI SPI Driver
- * @brief Generic SPI Driver.
- * @details This module implements a generic SPI driver.
+ * @brief Generic SPI Driver.
+ * @details This module implements a generic SPI (Serial Peripheral Interface)
+ * driver allowing bidirectional and monodirectional transfers,
+ * complex atomic transactions are supported as well.
* @pre In order to use the SPI driver the @p HAL_USE_SPI option
* must be enabled in @p halconf.h.
*
diff --git a/os/hal/dox/uart.dox b/os/hal/dox/uart.dox index 192ce4d91..7fea38dcb 100644 --- a/os/hal/dox/uart.dox +++ b/os/hal/dox/uart.dox @@ -1,5 +1,6 @@ /*
- ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio.
+ ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010,
+ 2011 Giovanni Di Sirio.
This file is part of ChibiOS/RT.
@@ -19,26 +20,27 @@ /**
* @defgroup UART UART Driver
- * @brief Generic UART Driver.
- * @details This driver abstracts a generic UART peripheral, the API is
- * designed to be:
- * - Unbuffered and copy-less, transfers are always directly performed
- * from/to the application-level buffers without extra copy operations.
- * - Asynchronous, the API is always non blocking.
- * - Callbacks capable, operations completion and other events are notified
- * via callbacks.
- * .
- * Special hardware features like deep hardware buffers, DMA transfers
- * are hidden to the user but fully supportable by the low level
- * implementations.<br>
- * This driver model is best used where communication events are meant to
- * drive an higher level state machine, as example:
- * - RS485 drivers.
- * - Multipoint network drivers.
- * - Serial protocol decoders.
- * .
- * If your application requires a synchronoyus buffered driver then the
- * @ref SERIAL should be used instead.
+ * @brief Generic UART Driver.
+ * @details This driver abstracts a generic UART (Universal Asynchronous
+ * Receiver Transmitter) peripheral, the API is designed to be:
+ * - Unbuffered and copy-less, transfers are always directly performed
+ * from/to the application-level buffers without extra copy
+ * operations.
+ * - Asynchronous, the API is always non blocking.
+ * - Callbacks capable, operations completion and other events are
+ * notified using callbacks.
+ * .
+ * Special hardware features like deep hardware buffers, DMA transfers
+ * are hidden to the user but fully supportable by the low level
+ * implementations.<br>
+ * This driver model is best used where communication events are
+ * meant to drive an higher level state machine, as example:
+ * - RS485 drivers.
+ * - Multipoint network drivers.
+ * - Serial protocol decoders.
+ * .
+ * If your application requires a synchronoyus buffered driver then
+ * the @ref SERIAL should be used instead.
* @pre In order to use the UART driver the @p HAL_USE_UART option
* must be enabled in @p halconf.h.
*
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
+ */
|