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

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

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

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 <h2>The OSAL</h2>
+ *          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.<br>
+ *          This section describes the API that OSALs are expected to expose
+ *          to the HAL.
+ *
+ *          <h2>RTOS Requirements</h2>
+ *          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.<br>
+ *          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.
+ *
+ *          <h2>Supported RTOSes</h2>
+ *          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
+ */

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

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

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