From c498fdc4d64f1de8706f9d3b224dc244c5e91dc2 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Wed, 4 Jan 2012 14:29:02 +0000 Subject: 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 --- os/hal/include/hal.h | 93 ++++++++++++++++++++++++++++++++++++++++++++++++ os/kernel/include/chvt.h | 15 ++++++++ os/various/various.dox | 41 ++++++++++++++------- readme.txt | 2 +- 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 @@ -72,6 +72,52 @@ /* Driver macros. */ /*===========================================================================*/ +/** + * @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 @@ -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. *

Notes

* 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.
@@ -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 -- cgit v1.2.3