From dffdc36d577c70bac7bf172f00c55aabf173340a Mon Sep 17 00:00:00 2001 From: gdisirio Date: Fri, 12 Dec 2014 10:07:09 +0000 Subject: Added OSAL documentation to HAL document. Fixed typos in the various OSALs. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@7573 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- doc/hal/Doxyfile_chm | 5 ++-- doc/hal/Doxyfile_html | 5 ++-- os/hal/dox/main.dox | 64 ++++++++++++++++++++++++++++++++++++++++++-- os/hal/osal/nil/osal.h | 2 +- os/hal/osal/rt/osal.h | 2 +- os/hal/templates/osal/osal.h | 2 +- 6 files changed, 71 insertions(+), 9 deletions(-) diff --git a/doc/hal/Doxyfile_chm b/doc/hal/Doxyfile_chm index 5c25f4bd2..9a642604d 100644 --- a/doc/hal/Doxyfile_chm +++ b/doc/hal/Doxyfile_chm @@ -790,7 +790,8 @@ INPUT = ./src \ ../../os/hal/dox \ ../../os/hal/src \ ../../os/hal/include \ - ../../os/hal/templates + ../../os/hal/templates \ + ../../os/hal/templates\osal # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -2365,7 +2366,7 @@ PLANTUML_JAR_PATH = # Minimum value: 0, maximum value: 10000, default value: 50. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_GRAPH_MAX_NODES = 20 +DOT_GRAPH_MAX_NODES = 50 # The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the graphs # generated by dot. A depth value of 3 means that only nodes reachable from the diff --git a/doc/hal/Doxyfile_html b/doc/hal/Doxyfile_html index e4a9b25c3..a6f88bc93 100644 --- a/doc/hal/Doxyfile_html +++ b/doc/hal/Doxyfile_html @@ -790,7 +790,8 @@ INPUT = ./src \ ../../os/hal/dox \ ../../os/hal/src \ ../../os/hal/include \ - ../../os/hal/templates + ../../os/hal/templates \ + ../../os/hal/templates\osal # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -2365,7 +2366,7 @@ PLANTUML_JAR_PATH = # Minimum value: 0, maximum value: 10000, default value: 50. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_GRAPH_MAX_NODES = 20 +DOT_GRAPH_MAX_NODES = 50 # The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the graphs # generated by dot. A depth value of 3 means that only nodes reachable from the diff --git a/os/hal/dox/main.dox b/os/hal/dox/main.dox index a704c9c90..a8d0f9a20 100644 --- a/os/hal/dox/main.dox +++ b/os/hal/dox/main.dox @@ -21,9 +21,9 @@ /** * @defgroup IO HAL * @brief Hardware Abstraction Layer. - * @details Under ChibiOS/RT the set of the various device driver interfaces + * @details Under ChibiOS the set of the various device driver interfaces * is called the HAL subsystem: Hardware Abstraction Layer. The HAL is the - * abstract interface between ChibiOS/RT application and hardware. + * abstract interface between ChibiOS applications and hardware. * * @section hal_device_driver_arch HAL Device Drivers Architecture * The HAL contains several kind of modules: @@ -130,3 +130,63 @@ * * @ingroup IO */ + +/** + * @defgroup OSAL OSAL + * @brief Operating System Abstraction Layer. + * @details

The OSAL

+ * The OSAL is the link between ChibiOS/HAL and services + * provided by operating systems like: + * - Critical Zones handling. + * - Interrupts handling. + * - Runtime Errors management. + * - Inter-task synchronization. + * - Task-ISR synchronization. + * - Time management. + * - Events. + * . + * ChibiOS/HAL is designed to tightly integrate with the underlying + * RTOS in order to provide the best experience to developers and + * minimize integration issues.
+ * This section describes the API that OSALs are expected to expose + * to the HAL. + * + *

RTOS Requirements

+ * The OSAL API closely resembles the ChibiOS/RT API, for obvious + * reasons, however an OSAL module can be implemented for any + * reasonably complete RTOS or even a RTOS-less bare metal + * machine, if required.
+ * In order to be able to support an HAL an RTOS should support the + * following minimal set of features: + * - Task-level critical zones API. + * - ISR-level critical zones API, only required on those CPU + * architectures supporting preemptable ISRs like Cortex-Mx + * cores. + * - Ability to invoke API functions from inside a task critical + * zone. Functions that are required to support this feature are + * marked with an "I" or "S" letter at the end of the name. + * - Ability to invoke API functions from inside an ISR critical + * zone. Functions that are required to support this feature are + * marked with an "I" letter at the end of the name. + * - Tasks Queues or Counting Semaphores with Timeout capability. + * - Ability to suspend a task and wakeup it from ISR with Timeout + * capability. + * - Event flags, the mechanism can be simulated using callbacks in + * case the RTOS does not support it. + * - Mutual Exclusion mechanism like Semaphores or Mutexes. + * . + * All the above requirements can be satisfied even on naked HW with + * a very think SW layer. In case that the HAL is required to work + * without an RTOS. + * + *

Supported RTOSes

+ * The RTOSes supported out of the box are: + * - ChibiOS/RT + * - ChibiOS/NIL + * . + * Implementations have also been successfully created on RTOSes not + * belonging to the ChibiOS products family but are not supported + * as a core feature of ChibiOS/HAL. + * + * @ingroup IO + */ diff --git a/os/hal/osal/nil/osal.h b/os/hal/osal/nil/osal.h index 59b13b2f2..c5dd68db9 100644 --- a/os/hal/osal/nil/osal.h +++ b/os/hal/osal/nil/osal.h @@ -549,7 +549,7 @@ static inline void osalOsRescheduleS(void) { * @note The counter can reach its maximum and then restart from zero. * @note This function can be called from any context but its atomicity * is not guaranteed on architectures whose word size is less than - * @systime_t size. + * @p systime_t size. * * @return The system time in ticks. * diff --git a/os/hal/osal/rt/osal.h b/os/hal/osal/rt/osal.h index 004d5f493..fd39e860f 100644 --- a/os/hal/osal/rt/osal.h +++ b/os/hal/osal/rt/osal.h @@ -540,7 +540,7 @@ static inline void osalOsRescheduleS(void) { * @note The counter can reach its maximum and then restart from zero. * @note This function can be called from any context but its atomicity * is not guaranteed on architectures whose word size is less than - * @systime_t size. + * @p systime_t size. * * @return The system time in ticks. * diff --git a/os/hal/templates/osal/osal.h b/os/hal/templates/osal/osal.h index d1df76826..af51fad27 100644 --- a/os/hal/templates/osal/osal.h +++ b/os/hal/templates/osal/osal.h @@ -513,7 +513,7 @@ static inline void osalOsRescheduleS(void) { * @note The counter can reach its maximum and then restart from zero. * @note This function can be called from any context but its atomicity * is not guaranteed on architectures whose word size is less than - * @systime_t size. + * @p systime_t size. * * @return The system time in ticks. * -- cgit v1.2.3