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

15 files changed, 171 insertions, 57 deletions

diff --git a/os/hal/dox/adc.dox b/os/hal/dox/adc.dox
index 9ebfca99c..4f1cf963d 100644
--- a/os/hal/dox/adc.dox
+++ b/os/hal/dox/adc.dox
@@ -20,7 +20,8 @@
 /**

  * @defgroup ADC ADC Driver

  * @brief Generic ADC Driver.

- * @details This module implements a generic ADC driver.

+ * @details This module implements a generic ADC 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.

  *

diff --git a/os/hal/dox/can.dox b/os/hal/dox/can.dox
index 81ee24e8b..550cbc79c 100644
--- a/os/hal/dox/can.dox
+++ b/os/hal/dox/can.dox
@@ -20,7 +20,8 @@
 /**

  * @defgroup CAN CAN Driver

  * @brief Generic CAN Driver.

- * @details This module implements a generic CAN driver.

+ * @details This module implements a generic CAN 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..1cca2a689
--- /dev/null
+++ b/os/hal/dox/gpt.dox
@@ -0,0 +1,76 @@
+/*

+    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 GPT GPT Driver

+ * @brief   Generic GPT Driver.

+ * @details This module implements a generic 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/mac.dox b/os/hal/dox/mac.dox
index 778795f15..903397749 100644
--- a/os/hal/dox/mac.dox
+++ b/os/hal/dox/mac.dox
@@ -20,8 +20,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..9ccdeb2bc 100644
--- a/os/hal/dox/mmc_spi.dox
+++ b/os/hal/dox/mmc_spi.dox
@@ -20,7 +20,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..63e428377 100644
--- a/os/hal/dox/pal.dox
+++ b/os/hal/dox/pal.dox
@@ -19,19 +19,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..1cb13056e 100644
--- a/os/hal/dox/pwm.dox
+++ b/os/hal/dox/pwm.dox
@@ -19,7 +19,7 @@
 

 /**

  * @defgroup PWM PWM Driver

- * @brief Generic PWM Driver.

+ * @brief   Generic PWM Driver.

  * @details This module implements a generic PWM driver.

  * @pre     In order to use the PWM driver the @p HAL_USE_PWM option

  *          must be enabled in @p halconf.h.

@@ -45,8 +45,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/serial.dox b/os/hal/dox/serial.dox
index 071b2dac5..d4f2cf634 100644
--- a/os/hal/dox/serial.dox
+++ b/os/hal/dox/serial.dox
@@ -19,14 +19,14 @@
 

 /**

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

  *

diff --git a/os/hal/dox/serial_usb.dox b/os/hal/dox/serial_usb.dox
index 599ee3c16..0f857052b 100644
--- a/os/hal/dox/serial_usb.dox
+++ b/os/hal/dox/serial_usb.dox
@@ -19,7 +19,7 @@
 

 /**

  * @defgroup SERIAL_USB Serial over USB Driver

- * @brief 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.

diff --git a/os/hal/dox/spi.dox b/os/hal/dox/spi.dox
index 7f68f3c40..7c43fec6e 100644
--- a/os/hal/dox/spi.dox
+++ b/os/hal/dox/spi.dox
@@ -19,8 +19,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 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..53339046d 100644
--- a/os/hal/dox/uart.dox
+++ b/os/hal/dox/uart.dox
@@ -19,26 +19,27 @@
 

 /**

  * @defgroup UART UART Driver

- * @brief Generic 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.

+ *          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
index 1f843efae..e9c6687ce 100644
--- a/os/hal/dox/usb.dox
+++ b/os/hal/dox/usb.dox
@@ -19,8 +19,9 @@
 

 /**

  * @defgroup USB USB Driver

- * @brief Generic USB Driver.

- * @details This module implements a generic USB driver.

+ * @brief   Generic USB Driver.

+ * @details This module implements a generic USB 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.

  *

diff --git a/os/hal/include/usb.h b/os/hal/include/usb.h
index d569a6031..24b492e2f 100644
--- a/os/hal/include/usb.h
+++ b/os/hal/include/usb.h
@@ -385,6 +385,7 @@ typedef const USBDescriptor * (*usbgetdescriptor_t)(USBDriver *usbp,
  * @param[in] usbp      pointer to the @p USBDriver object

  * @param[in] buf       pointer to a buffer for the transaction data

  * @param[in] n         number of bytes to be transferred

+ * @param[in] endcb     callback to be invoked after the transfer or @p NULL

  *

  * @api

  */

diff --git a/os/hal/platforms/STM32/platform.dox b/os/hal/platforms/STM32/platform.dox
index 91f0addca..8edf27161 100644
--- a/os/hal/platforms/STM32/platform.dox
+++ b/os/hal/platforms/STM32/platform.dox
@@ -100,6 +100,25 @@
  */

 

 /**

+ * @defgroup STM32_GPT STM32 GPT Support

+ * @details The STM32 GPT driver uses the TIMx peripherals.

+ *

+ * @section stm32_gpt_1 Supported HW resources

+ * - TIM1.

+ * - TIM2.

+ * - TIM3.

+ * - TIM4.

+ * - TIM5.

+ * .

+ * @section stm32_gpt_2 STM32 GPT driver implementation features

+ * - Each timer can be independently enabled and programmed. Unused

+ *   peripherals are left in low power mode.

+ * - Programmable TIMx interrupts priority level.

+ * .

+ * @ingroup STM32_DRIVERS

+ */

+

+/**

  * @defgroup STM32_PAL STM32 GPIO Support

  * @details The STM32 PAL driver uses the GPIO peripherals.

  *

@@ -158,6 +177,7 @@
  * - TIM2.

  * - TIM3.

  * - TIM4.

+ * - TIM5.

  * .

  * @section stm32_pwm_2 STM32 PWM driver implementation features

  * - Each timer can be independently enabled and programmed. Unused

diff --git a/os/hal/src/serial_usb.c b/os/hal/src/serial_usb.c
index 83f1c93ff..0393ad141 100644
--- a/os/hal/src/serial_usb.c
+++ b/os/hal/src/serial_usb.c
@@ -167,12 +167,6 @@ void sduInit(void) {
  *          outside, usually in the hardware initialization code.

  *

  * @param[out] sdup     pointer to a @p SerialUSBDriver structure

- * @param[in] inotify   pointer to a callback function that is invoked when

- *                      some data is read from the Queue. The value can be

- *                      @p NULL.

- * @param[in] onotify   pointer to a callback function that is invoked when

- *                      some data is written in the Queue. The value can be

- *                      @p NULL.

  *

  * @init

  */

@@ -244,6 +238,11 @@ void sduStop(SerialUSBDriver *sdup) {
  *          - CDC_SET_LINE_CODING.

  *          - CDC_SET_CONTROL_LINE_STATE.

  *          .

+ *

+ * @param[in] usbp      pointer to the @p USBDriver object

+ * @return              The hook status.

+ * @retval TRUE         Message handled internally.

+ * @retval FALSE        Message not handled.

  */

 bool_t sduRequestsHook(USBDriver *usbp) {

 

@@ -270,6 +269,9 @@ bool_t sduRequestsHook(USBDriver *usbp) {
  * @brief   Default data transmitted callback.

  * @details The application must use this function as callback for the IN

  *          data endpoint.

+ *

+ * @param[in] usbp      pointer to the @p USBDriver object

+ * @param[in] ep        endpoint number

  */

 void sduDataTransmitted(USBDriver *usbp, usbep_t ep) {

   SerialUSBDriver *sdup = usbp->param;

@@ -294,6 +296,9 @@ void sduDataTransmitted(USBDriver *usbp, usbep_t ep) {
  * @brief   Default data received callback.

  * @details The application must use this function as callback for the OUT

  *          data endpoint.

+ *

+ * @param[in] usbp      pointer to the @p USBDriver object

+ * @param[in] ep        endpoint number

  */

 void sduDataReceived(USBDriver *usbp, usbep_t ep) {

   SerialUSBDriver *sdup = usbp->param;

@@ -319,6 +324,9 @@ void sduDataReceived(USBDriver *usbp, usbep_t ep) {
  * @brief   Default data received callback.

  * @details The application must use this function as callback for the IN

  *          interrupt endpoint.

+ *

+ * @param[in] usbp      pointer to the @p USBDriver object

+ * @param[in] ep        endpoint number

  */

 void sduInterruptTransmitted(USBDriver *usbp, usbep_t ep) {