From 2b1173e29246cbc82f45490d0b1b1443d7bf897a Mon Sep 17 00:00:00 2001
From: gdisirio <gdisirio@35acf78f-673a-0410-8e92-d51de3d6d3f4>
Date: Thu, 14 Jun 2012 16:45:57 +0000
Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@4276
 35acf78f-673a-0410-8e92-d51de3d6d3f4

---
 docs/rsc/header_chm.html               |  2 +-
 docs/rsc/header_html.html              |  2 +-
 os/hal/dox/i2s.dox                     | 31 +++++++++++++
 os/hal/dox/tm.dox                      |  2 +-
 os/hal/dox/usb.dox                     | 79 +++++-----------------------------
 os/hal/hal.dox                         |  7 +++
 os/hal/include/mmc_spi.h               | 30 +++++++------
 os/hal/include/mmcsd.h                 |  8 +++-
 os/hal/include/usb.h                   |  2 +-
 os/hal/platforms/STM32/OTGv1/usb_lld.c |  2 +-
 os/hal/platforms/STM32/sdc_lld.h       | 30 +++++++------
 os/hal/src/mmc_spi.c                   |  9 +---
 os/hal/src/sdc.c                       |  2 +-
 os/various/chprintf.c                  |  2 +
 os/various/chrtclib.c                  | 14 +++++-
 os/various/chrtclib.h                  | 12 +++---
 os/various/various.dox                 | 20 ++++++++-
 17 files changed, 136 insertions(+), 118 deletions(-)
 create mode 100644 os/hal/dox/i2s.dox

diff --git a/docs/rsc/header_chm.html b/docs/rsc/header_chm.html
index 4ce33e42f..c45a0d363 100644
--- a/docs/rsc/header_chm.html
+++ b/docs/rsc/header_chm.html
@@ -13,7 +13,7 @@
  <tbody>
  <tr style="height: 56px;">
   <td style="padding-left: 0.5em;">
-   <div id="projectname">ChibiOS/RT&#160;<span id="projectnumber">2.3.5</span></div>
+   <div id="projectname">ChibiOS/RT&#160;<span id="projectnumber">2.5.0</span></div>
   </td>
  </tr>
  </tbody>
diff --git a/docs/rsc/header_html.html b/docs/rsc/header_html.html
index 243097201..ed8348931 100644
--- a/docs/rsc/header_html.html
+++ b/docs/rsc/header_html.html
@@ -20,7 +20,7 @@ $(document).ready(initResizable);
  <tbody>
  <tr style="height: 92px;">
   <td style="padding-left: 0.5em;">
-   <div id="projectname">ChibiOS/RT<br><span id="projectnumber">2.3.5</span></div>
+   <div id="projectname">ChibiOS/RT<br><span id="projectnumber">2.5.0</span></div>
   </td>
   <td style="padding-left: 3em;">
 <script type="text/javascript"><!--
diff --git a/os/hal/dox/i2s.dox b/os/hal/dox/i2s.dox
new file mode 100644
index 000000000..2c6cc4ca2
--- /dev/null
+++ b/os/hal/dox/i2s.dox
@@ -0,0 +1,31 @@
+/*
+    ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010,
+                 2011,2012 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 I2S I2S Driver
+ * @brief   Generic I2S Driver.
+ * @details This module implements a generic I2S  driver.
+ * @pre     In order to use the I2S driver the @p HAL_USE_I2S option
+ *          must be enabled in @p halconf.h.
+ *
+ * @section i2s_1 Driver State Machine
+ *
+ * @ingroup IO
+ */
diff --git a/os/hal/dox/tm.dox b/os/hal/dox/tm.dox
index d895a6d30..c4c537776 100644
--- a/os/hal/dox/tm.dox
+++ b/os/hal/dox/tm.dox
@@ -19,7 +19,7 @@
 */
 
 /**
- * @defgroup TM Time Measurement Driver.
+ * @defgroup TM Time Measurement Driver
  *
  * @brief   Time Measurement unit.
  * @details This module implements a time measurement mechanism able to
diff --git a/os/hal/dox/usb.dox b/os/hal/dox/usb.dox
index 7298e191d..748e41afe 100644
--- a/os/hal/dox/usb.dox
+++ b/os/hal/dox/usb.dox
@@ -86,7 +86,7 @@
     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 -> 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< >out_cb< >setup_cb<"];
     configured -> ready [label="\nUSB RESET\n>event_cb<"];
   }
  * @enddot
@@ -115,57 +115,9 @@
  * - <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="\nusbInitEndpointI()"];
-    receiving -> idle [label="\npacket received\n>out_cb<"];
-    idle -> receiving [label="\nusbReadPacketBuffer()\nusbStartReceiveI()"];
-    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="\nusbInitEndpointI()"];
-    idle -> transmitting [label="\nusbWritePacketBuffer()\nusbStartTransmitI()"];
-    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
+ * The driver invokes a callback after finishing an IN or OUT transaction.
+ * States diagram for OUT endpoints in transaction mode:
+ * @dot
   digraph example {
     rankdir="LR";
     node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true",
@@ -183,10 +135,10 @@
     receiving -> disabled [label="\nUSB RESET\nusbDisableEndpointsI()"];
     idle -> disabled [label="\nUSB RESET\nusbDisableEndpointsI()"];
   }
- *   @enddot
- *   <br><br>
- *   States diagram for IN endpoints in transaction mode:
- *   @dot
+ * @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",
@@ -204,19 +156,8 @@
     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.
+ * @enddot
+ * <br><br>
  *
  * @subsection usb_2_4 USB Callbacks
  * The USB driver uses callbacks in order to interact with the application.
diff --git a/os/hal/hal.dox b/os/hal/hal.dox
index 4e21f3940..1ac733957 100644
--- a/os/hal/hal.dox
+++ b/os/hal/hal.dox
@@ -91,3 +91,10 @@
  * @defgroup IO_BLOCK Abstract I/O Block Device
  * @ingroup IO
  */
+
+/**
+ * @defgroup MMCSD MMC/SD Block Devices common ancestor
+ * @details This module implements a common ancestor for all device drivers
+ *          accessing MMC or SD cards.
+ * @ingroup IO
+ */
diff --git a/os/hal/include/mmc_spi.h b/os/hal/include/mmc_spi.h
index 307ffd3ca..a008292f5 100644
--- a/os/hal/include/mmc_spi.h
+++ b/os/hal/include/mmc_spi.h
@@ -119,6 +119,21 @@ typedef struct {
   const SPIConfig       *hscfg;
 } MMCConfig;
 
+/**
+ * @brief   @p MMCDriver specific methods.
+ */
+#define _mmc_driver_methods                                                 \
+  _mmcsd_block_device_methods
+
+/**
+ * @extends MMCSDBlockDeviceVMT
+ *
+ * @brief   @p MMCDriver virtual methods table.
+ */
+struct MMCDriverVMT {
+  _mmc_driver_methods
+};
+
 /**
  * @extends MMCSDBlockDevice
  *
@@ -128,7 +143,8 @@ typedef struct {
   /**
    * @brief Virtual Methods Table.
    */
-  const struct MMCSDBlockDeviceVMT *vmt;
+  const struct MMCDriverVMT *vmt;
+  _mmcsd_block_device_data
   /**
    * @brief Driver state.
    */
@@ -157,18 +173,6 @@ typedef struct {
    * @brief Addresses use blocks instead of bytes.
    */
   bool_t                block_addresses;
-  /**
-   * @brief Card CID.
-   */
-  uint32_t                  cid[4];
-  /**
-   * @brief Card CSD.
-   */
-  uint32_t                  csd[4];
-  /**
-   * @brief Total number of blocks in card.
-   */
-  uint32_t              capacity;
 } MMCDriver;
 
 /*===========================================================================*/
diff --git a/os/hal/include/mmcsd.h b/os/hal/include/mmcsd.h
index 7595e1202..a05c2602f 100644
--- a/os/hal/include/mmcsd.h
+++ b/os/hal/include/mmcsd.h
@@ -183,7 +183,13 @@
  *          without implementation.
  */
 #define _mmcsd_block_device_data                                            \
-  _base_block_device_data
+  _base_block_device_data                                                   \
+  /* Card CID.*/                                                            \
+  uint32_t              cid[4];                                             \
+  /* Card CSD.*/                                                            \
+  uint32_t              csd[4];                                             \
+  /* Total number of blocks in card.*/                                      \
+  uint32_t              capacity;
 
 /**
  * @extends BaseBlockDeviceVMT
diff --git a/os/hal/include/usb.h b/os/hal/include/usb.h
index 751128c7c..ddf8cb321 100644
--- a/os/hal/include/usb.h
+++ b/os/hal/include/usb.h
@@ -423,7 +423,7 @@ typedef const USBDescriptor * (*usbgetdescriptor_t)(USBDriver *usbp,
  *          initialized in transaction mode.
  * @post    The endpoint is ready for @p usbStartReceiveI().
  * @note    The receive transaction size is equal to the space in the queue
- *          rounded to the lower multiple of a packet size. So make sure there
+ *          rounded to the lower multiple of a packet size. Make sure there
  *          is room for at least one packet in the queue before starting
  *          the receive operation.
  *
diff --git a/os/hal/platforms/STM32/OTGv1/usb_lld.c b/os/hal/platforms/STM32/OTGv1/usb_lld.c
index 1132416ee..2efd4dfea 100644
--- a/os/hal/platforms/STM32/OTGv1/usb_lld.c
+++ b/os/hal/platforms/STM32/OTGv1/usb_lld.c
@@ -989,7 +989,7 @@ void usb_lld_prepare_transmit(USBDriver *usbp, usbep_t ep,
  * @brief   Prepares for a receive transaction on an OUT endpoint.
  * @post    The endpoint is ready for @p usbStartReceiveI().
  * @note    The receive transaction size is equal to the space in the queue
- *          rounded to the lower multiple of a packet size. So make sure there
+ *          rounded to the lower multiple of a packet size. Make sure there
  *          is room for at least one packet in the queue before starting
  *          the receive operation.
  *
diff --git a/os/hal/platforms/STM32/sdc_lld.h b/os/hal/platforms/STM32/sdc_lld.h
index a2cb6472d..7511bf581 100644
--- a/os/hal/platforms/STM32/sdc_lld.h
+++ b/os/hal/platforms/STM32/sdc_lld.h
@@ -197,6 +197,21 @@ typedef struct {
   uint32_t dummy;
 } SDCConfig;
 
+/**
+ * @brief   @p SDCDriver specific methods.
+ */
+#define _sdc_driver_methods                                                 \
+  _mmcsd_block_device_methods
+
+/**
+ * @extends MMCSDBlockDeviceVMT
+ *
+ * @brief   @p SDCDriver virtual methods table.
+ */
+struct SDCDriverVMT {
+  _sdc_driver_methods
+};
+
 /**
  * @brief   Structure representing an SDC driver.
  */
@@ -204,7 +219,8 @@ struct SDCDriver {
   /**
    * @brief Virtual Methods Table.
    */
-  const struct MMCSDBlockDeviceVMT *vmt;
+  const struct SDCDriverVMT *vmt;
+  _mmcsd_block_device_data
   /**
    * @brief Driver state.
    */
@@ -221,22 +237,10 @@ struct SDCDriver {
    * @brief Errors flags.
    */
   sdcflags_t                errors;
-  /**
-   * @brief Card CID.
-   */
-  uint32_t                  cid[4];
-  /**
-   * @brief Card CSD.
-   */
-  uint32_t                  csd[4];
   /**
    * @brief Card RCA.
    */
   uint32_t                  rca;
-  /**
-   * @brief Total number of blocks in card.
-   */
-  uint32_t                  capacity;
   /* End of the mandatory fields.*/
   /**
    * @brief Thread waiting for I/O completion IRQ.
diff --git a/os/hal/src/mmc_spi.c b/os/hal/src/mmc_spi.c
index a6dda0dc1..cb045bcb4 100644
--- a/os/hal/src/mmc_spi.c
+++ b/os/hal/src/mmc_spi.c
@@ -57,7 +57,7 @@ bool_t mmc_write(void *instance, uint32_t startblk,
 /**
  * @brief   Virtual methods table.
  */
-static const struct MMCSDBlockDeviceVMT mmc_vmt = {
+static const struct MMCDriverVMT mmc_vmt = {
   (bool_t (*)(void *))mmc_lld_is_card_inserted,
   (bool_t (*)(void *))mmc_lld_is_write_protected,
   (bool_t (*)(void *))mmcConnect,
@@ -406,13 +406,6 @@ void mmcInit(void) {
  * @brief   Initializes an instance.
  *
  * @param[out] mmcp         pointer to the @p MMCDriver object
- * @param[in] spip          pointer to the SPI driver to be used as interface
- * @param[in] lscfg         low speed configuration for the SPI driver
- * @param[in] hscfg         high speed configuration for the SPI driver
- * @param[in] is_protected  function that returns the card write protection
- *                          setting
- * @param[in] is_inserted   function that returns the card insertion sensor
- *                          status
  *
  * @init
  */
diff --git a/os/hal/src/sdc.c b/os/hal/src/sdc.c
index dd0170b4f..728f05566 100644
--- a/os/hal/src/sdc.c
+++ b/os/hal/src/sdc.c
@@ -46,7 +46,7 @@
 /**
  * @brief   Virtual methods table.
  */
-static const struct MMCSDBlockDeviceVMT sdc_vmt = {
+static const struct SDCDriverVMT sdc_vmt = {
   (bool_t (*)(void *))sdc_lld_is_card_inserted,
   (bool_t (*)(void *))sdc_lld_is_write_protected,
   (bool_t (*)(void *))sdcConnect,
diff --git a/os/various/chprintf.c b/os/various/chprintf.c
index 7b02ab3ba..78a4a8ac1 100644
--- a/os/various/chprintf.c
+++ b/os/various/chprintf.c
@@ -264,3 +264,5 @@ unsigned_common:
     }
   }
 }
+
+/** @} */
diff --git a/os/various/chrtclib.c b/os/various/chrtclib.c
index f76f91d65..1a0a5487d 100644
--- a/os/various/chrtclib.c
+++ b/os/various/chrtclib.c
@@ -22,6 +22,14 @@
    aka barthess.
  */
 
+/**
+ * @file    chrtclib.c
+ * @brief   RTC time conversion utilities code.
+ *
+ * @addtogroup chrtclib
+ * @{
+ */
+
 #include <time.h>
 
 #include "ch.h"
@@ -31,7 +39,7 @@
 
 #if (defined(STM32F4XX) || defined(STM32F2XX) || defined(STM32L1XX) || \
      defined(STM32F1XX) || defined(STM32F10X_MD) || defined(STM32F10X_LD) || \
-     defined(STM32F10X_HD))
+     defined(STM32F10X_HD) || defined(__DOXYGEN__))
 #if STM32_RTC_IS_CALENDAR
 /**
  * @brief   Converts from STM32 BCD to canonicalized time format.
@@ -194,6 +202,7 @@ time_t rtcGetTimeUnixSec(RTCDriver *rtcp) {
  * @brief   Sets RTC time.
  *
  * @param[in] rtcp      pointer to RTC driver structure
+ * @param[in] tv_sec    time specification
  * @return              Unix time value in seconds.
  *
  * @api
@@ -285,6 +294,7 @@ time_t rtcGetTimeUnixSec(RTCDriver *rtcp) {
  * @brief   Sets RTC time.
  *
  * @param[in] rtcp      pointer to RTC driver structure
+ * @param[in] tv_sec    time specification
  * @return              Unix time value in seconds.
  *
  * @api
@@ -342,3 +352,5 @@ uint32_t rtcGetTimeFat(RTCDriver *rtcp) {
   fattime |= (timp->tm_year - 80) << 25;
   return fattime;
 }
+
+/** @} */
diff --git a/os/various/chrtclib.h b/os/various/chrtclib.h
index 7b3493636..c41706f87 100644
--- a/os/various/chrtclib.h
+++ b/os/various/chrtclib.h
@@ -22,19 +22,19 @@
    aka barthess.
  */
 
-#ifndef CHRTCLIB_H_
-#define CHRTCLIB_H_
-
-#include <time.h>
-
 /**
  * @file    chrtclib.h
- * @brief   Various time conversion functionality.
+ * @brief   RTC time conversion utilities header.
  *
  * @addtogroup chrtclib
  * @{
  */
 
+#ifndef CHRTCLIB_H_
+#define CHRTCLIB_H_
+
+#include <time.h>
+
 /*===========================================================================*/
 /* External declarations.                                                    */
 /*===========================================================================*/
diff --git a/os/various/various.dox b/os/various/various.dox
index d221c9af5..ac833a7e0 100644
--- a/os/various/various.dox
+++ b/os/various/various.dox
@@ -75,7 +75,25 @@
  */
 
 /**
- * @defgroup lis302dl Interface module for LIS302DL MEMS.
+ * @defgroup chrtclib RTC time conversion utilities
+ *
+ * @brief   RTC time conversion utilities.
+ *
+ * @ingroup various
+ */
+
+/**
+ * @defgroup chprintf System formatted print
+ *
+ * @brief   System formatted print service.
+ * @details This module implements printf()-like function able to send data
+ *          to any module implementing a @p BaseSequentialStream interface.
+ *
+ * @ingroup various
+ */
+
+/**
+ * @defgroup lis302dl Interface module for LIS302DL MEMS
  *
  * @brief   Interface module for LIS302DL MEMS.
  * @details This module implements a generic interface for the LIS302DL
-- 
cgit v1.2.3