Added time conversions to RT counter code. Documentation improvements.

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

4 files changed, 138 insertions, 13 deletions

diff --git a/os/hal/include/hal.h b/os/hal/include/hal.h
index ceb047db1..b7e6141cc 100644
--- a/os/hal/include/hal.h
+++ b/os/hal/include/hal.h
@@ -73,6 +73,52 @@
 /*===========================================================================*/

 

 /**

+ * @name    Time conversion utilities for the realtime counter

+ * @{

+ */

+/**

+ * @brief   Seconds to realtime ticks.

+ * @details Converts from seconds to realtime ticks number.

+ * @note    The result is rounded upward to the next tick boundary.

+ *

+ * @param[in] sec       number of seconds

+ * @return              The number of ticks.

+ *

+ * @api

+ */

+#define S2RTT(sec) (halGetCounterFrequency() * (sec))

+

+/**

+ * @brief   Milliseconds to realtime ticks.

+ * @details Converts from milliseconds to realtime ticks number.

+ * @note    The result is rounded upward to the next tick boundary.

+ *

+ * @param[in] msec      number of milliseconds

+ * @return              The number of ticks.

+ *

+ * @api

+ */

+#define MS2RTT(msec) (((halGetCounterFrequency() + 999UL) / 1000UL) * (msec))

+

+/**

+ * @brief   Microseconds to realtime ticks.

+ * @details Converts from microseconds to realtime ticks number.

+ * @note    The result is rounded upward to the next tick boundary.

+ *

+ * @param[in] usec      number of microseconds

+ * @return              The number of ticks.

+ *

+ * @api

+ */

+#define US2RTT(usec) (((halGetCounterFrequency() + 999999UL) / 1000000UL) * \

+                      (usec))

+/** @} */

+

+/**

+ * @name    Macro Functions

+ * @{

+ */

+/**

  * @brief   Returns the current value of the system free running counter.

  * @note    This is an optional service that could not be implemented in

  *          all HAL implementations.

@@ -95,6 +141,53 @@
  */

 #define halGetCounterFrequency() hal_lld_get_counter_frequency()

 

+/**

+ * @brief   Realtime window test.

+ * @details This function verifies if the current realtime counter value

+ *          lies within the specified range or not. The test takes care

+ *          of the realtime counter wrapping to zero on overflow.

+ * @note    When start==end then the function returns always true because the

+ *          whole time range is specified.

+ *

+ * @par Example 1

+ * Example of a guarded loop using the realtime counter. The loop implements

+ * a timeout after one second.

+ * @code

+ *   halrtcnt_t start = halGetCounterValue();

+ *   halrtcnt_t timeout  = start + S2RTT(1);

+ *   while (my_condition) {

+ *     if (!halIsCounterWithin(start, timeout)

+ *       return TIMEOUT;

+ *     // Do something.

+ *   }

+ *   // Continue.

+ * @endcode

+ *

+ * @par Example 2

+ * Example of a loop that lasts exactly 50 microseconds.

+ * @code

+ *   halrtcnt_t start = halGetCounterValue();

+ *   halrtcnt_t timeout  = start + US2RTT(50);

+ *   while (halIsCounterWithin(start, timeout)) {

+ *     // Do something.

+ *   }

+ *   // Continue.

+ * @endcode

+ *

+ * @param[in] start     the start of the time window (inclusive)

+ * @param[in] end       the end of the time window (non inclusive)

+ * @retval TRUE         current time within the specified time window.

+ * @retval FALSE        current time not within the specified time window.

+ *

+ * @api

+ */

+#define halIsCounterWithin(start, end)                                      \

+  (end > start ? (halGetCounterValue() >= start) &&                         \

+                 (halGetCounterValue() < end) :                             \

+                 (halGetCounterValue() >= start) ||                         \

+                 (halGetCounterValue() < end))

+/** @} */

+

 /*===========================================================================*/

 /* External declarations.                                                    */

 /*===========================================================================*/

diff --git a/os/kernel/include/chvt.h b/os/kernel/include/chvt.h
index 0038e3d0a..e74a7f713 100644
--- a/os/kernel/include/chvt.h
+++ b/os/kernel/include/chvt.h
@@ -37,6 +37,11 @@
  * @brief   Seconds to system ticks.

  * @details Converts from seconds to system ticks number.

  * @note    The result is rounded upward to the next tick boundary.

+ *

+ * @param[in] sec       number of seconds

+ * @return              The number of ticks.

+ *

+ * @api

  */

 #define S2ST(sec)   ((systime_t)((sec) * CH_FREQUENCY))

 

@@ -44,6 +49,11 @@
  * @brief   Milliseconds t0 system ticks.

  * @details Converts from milliseconds to system ticks number.

  * @note    The result is rounded upward to the next tick boundary.

+ *

+ * @param[in] msec      number of milliseconds

+ * @return              The number of ticks.

+ *

+ * @api

  */

 #define MS2ST(msec) ((systime_t)(((((msec) - 1L) * CH_FREQUENCY) / 1000L) + 1L))

 

@@ -51,6 +61,11 @@
  * @brief   Microseconds to system ticks.

  * @details Converts from microseconds to system ticks number.

  * @note    The result is rounded upward to the next tick boundary.

+ *

+ * @param[in] usec      number of microseconds

+ * @return              The number of ticks.

+ *

+ * @api

  */

 #define US2ST(usec) ((systime_t)(((((usec) - 1L) * CH_FREQUENCY) / 1000000L) + 1L))

 /** @} */

diff --git a/os/various/various.dox b/os/various/various.dox
index 9ae895af4..e35bed3c2 100644
--- a/os/various/various.dox
+++ b/os/various/various.dox
@@ -20,9 +20,10 @@
 

 /**

  * @defgroup various Various

- * @brief Utilities Library.

+ *

+ * @brief   Utilities Library.

  * @details This is a collection of useful library code that is not part of

- * the base kernel services.

+ *          the base kernel services.

  * <h2>Notes</h2>

  * The library code does not follow the same naming convention of the

  * system APIs in order to make very clear that it is not "core" code.<br>

@@ -32,38 +33,54 @@
 

 /**

  * @defgroup cpp_library C++ Wrapper

- * @brief C++ wrapper module.

+ *

+ * @brief   C++ wrapper module.

  * @details This module allows to use the ChibiOS/RT functionalities

- * from C++ as classes and objects rather the traditional "C" APIs.

+ *          from C++ as classes and objects rather the traditional "C" APIs.

  *

  * @ingroup various

  */

 

 /**

  * @defgroup memory_streams Memory Streams

- * @brief Memory Streams.

+ *

+ * @brief   Memory Streams.

  * @details This module allows to use a memory area (RAM or ROM) using a

- * @ref data_streams interface.

+ *          @ref data_streams interface.

  *

  * @ingroup various

  */

 

 /**

  * @defgroup event_timer Periodic Events Timer

- * @brief Periodic Event Timer.

+ *

+ * @brief   Periodic Event Timer.

  * @details This timer generates an event at regular intervals. The

- * listening threads can use the event to perform time related activities.

- * Multiple threads can listen to the same timer.

+ *          listening threads can use the event to perform time related

+ *          activities. Multiple threads can listen to the same timer.

  *

  * @ingroup various

  */

 

 /**

  * @defgroup SHELL Command Shell

- * @brief Small extendible command line shell.

+ *

+ * @brief   Small extendible command line shell.

  * @details This module implements a generic extendible command line interface.

- * The CLI just requires an I/O channel (@p BaseChannel), more commands can be

- * added to the shell using the configuration structure.

+ *          The CLI just requires an I/O channel (@p BaseChannel), more

+ *          commands can be added to the shell using the configuration

+ *          structure.

+ *

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

+ *          STMicroelectronics MEMS device. The communication is performed

+ *          through a standard SPI driver.

  *

  * @ingroup various

  */

diff --git a/readme.txt b/readme.txt
index 7d818161a..ddca8e345 100644
--- a/readme.txt
+++ b/readme.txt
@@ -79,7 +79,7 @@
 - FIX: Fixed SYSCFG clock not started in STM32L1/F4 HALs (bug 3449139).

 - FIX: Fixed wrong definitions in STM32L-Discovery board file (bug 3449076).

 - OPT: Improved the exception exit code in the GCC Cortex-Mx ports.

-- NEW: Addred to the HAL driver the handling of an abstract realtime free

+- NEW: Added to the HAL driver the handling of an abstract realtime free

   running counter, added the capability to all the STM32 HALs.

 - NEW: Modified ARM and ARMCMx build rules to allow parallel build. Now the

   log outputs one dummy compilation command in order to allow paths discovery