Update documentation for asyncFreeRtos

resolves: BS-2650

Change-Id: I7f3542ceea547ece3af5119826c41aa00fa65bc2

libs/bsw/asyncFreeRtos/doc/index.rst

@@ -1,35 +1,36 @@
 asyncFreeRtos
 =============
 
-Overview
---------
+This module provides a collection of classes that serve as an intermediate layer
+between the asynchronous operations API and their implementation in **FreeRTOS**.
+The supported asynchronous operations include:
 
-The module implements the generic ``async`` API for FreeRTOS.
+* Non-blocking immediate execution
+* Non-blocking scheduling of single-time execution
+* Non-blocking scheduling of cyclic execution
+* Thread synchronization using ``wait()`` and ``notify()`` mechanisms
+* Secure sections with ``Lock``
+
+The implementation of these asynchronous operations is achieved by wrapping native
+**FreeRTOS** functions into classes like ``async::TaskContext`` and ``async::FutureSupport``.
+Additional classes, such as ``async::FreeRtosAdapter`` and ``async::StaticRunnable``,
+offer a public API for initializing tasks that can later be executed asynchronously.
 
 The main features of this implementation are:
 
-* A configurable maximum number of tasks can be configured (as contexts) using simple
-  initialization types that also allocate tasks stacks statically
-* A context maps to a FreeRTOS task
-* A context can be represented by a number (starting with 0). A higher context number
-  indicates a higher prio of the corresponding task.
-* The idle task has the reserved value (and priority) 0.
-* The timer task is the task with the highest priority in the system.
-* All other tasks priorities are between idle and timer task priority.
-* All tasks can be configured by simple configuration objects that also statically
-  allocate the required stacks.
-* A hook concept for registering to task switch events is available
-* A simple interface for synchronizing FreeRTOS with interrupts is available
-* Implementations of legacy interfaces `looper` and `ITimeoutManager2` are available
-  for each configured task (they can be optionally disabled)
+* A single ``async::Task`` instance corresponds to a single **FreeRTOS** task (via TaskHandle_t, a pointer to the **FreeRTOS** structure).
+* The ``async::Task`` context is represented by an integer ID. A higher context ID indicates a higher priority for the corresponding task.
+* The idle task has a reserved context ID and priority of 0.
+* The timer task is assigned the highest priority in the system.
+* All other task priorities are assigned values between the idle and timer task priorities.
+* Task configuration specifies both the context ID and the required stack size.
+* A Runnable is executed within the context of one of the initialized instances of ``async::Task``.
+* A hook mechanism is available for registering task switch events.
+* An interface is provided for synchronizing **FreeRTOS** with interrupts.
 
 .. toctree::
     :maxdepth: 1
     :glob:
-    :hidden:
 
-    user/adapter_api
-    user/async_api
-    user/scenarios/index
-    user/static_config
+    */index
 

libs/bsw/asyncFreeRtos/doc/user/asynchronous_execution.rst

@@ -0,0 +1,93 @@
+.. _async_execution:
+
+Asynchonous execution
+=====================
+
+The asyncronous execution family consists of three functions:
+
+* ``async::execute()``
+* ``async::schedule()``
+* ``async::scheduleAtFixedRate()``
+
+Each of the above function would call a corresponding non-blocking method from
+``FreeRtosAdapter`` class. A more detailed description of the functions may be found in ``async`` module.
+
+Features
+--------
+
+Execute
++++++++
+
+The following sequences illustrate the expected behavior of calls to execute from different contexts:
+
+* | **Execute in a higher-priority context than the current context.**
+  | The current task is expected to be immediately preempted to execute the higher-priority `runnable`.
+
+* | **Execute in the same context as the current context.**
+  | Even in this case, it is an asynchronous operation. The `runnable` is expected to be
+    executed only after the complete execution of the current `runnable`.
+
+* | **Execute in a lower-priority context than the current context.**
+  | The lower-priority `runnable` is expected to be executed only after the execution of all
+    higher-priority `runnables` has completed.
+
+Schedule
+++++++++
+
+The following sequences illustrate the expected behavior of calls to ``schedule`` or
+``scheduleAtFixedRate`` from different contexts:
+
+* | **Schedule in a higher-priority context.**
+  | Timers of the higher-priority task are expected to be handled immediately, preempting the
+    lower-priority task.
+
+* | **Schedule in the same context.**
+  | Timers of the current context are expected to be handled after the execution of the current
+    `runnable`, avoiding immediate execution in this specific case.
+
+* | **Schedule in a lower-priority context.**
+  | Timer handling is expected to be triggered within the lower-priority context only after all
+    higher-priority handling has been completed.
+
+Related types
++++++++++++++
+
+* ``async::FreeRtosAdapter``
+* ``async::TimeoutType``
+
+Examples
+++++++++
+
+Define a class that implements the ``IRunnable`` interface:
+
+.. code-block:: cpp
+
+    #include <async/Async.h>
+
+    class RunnableImpl : public ::async::IRunnable
+    {
+    public:
+        void execute() override
+        {
+            fprintf(stdout, "Executing TestRunnable!\n");
+        }
+    };
+
+In client code allocate the runnable object and asynchronously execute it:
+
+.. code-block:: cpp
+
+    static RunnableImpl runnable;
+    static ::async::TimeoutType timeout;
+
+    void executeRunnable(::async::ContextType& context)
+    {
+        // asynchronously execute the runnable:
+        ::async::execute(context, runnable);
+
+        // schedule the runnable for single-time execution after 1 second from now:
+        ::async::schedule(context, runnable, timeout, 1, ::async::TimeUnit::SECONDS);
+
+        // schedule the runnable for cyclic execution with period 2 seconds:
+        ::async::scheduleAtFixedRate(context, runnable, timeout, 2, ::async::TimeUnit::SECONDS);
+    }

libs/bsw/asyncFreeRtos/doc/user/index.rst

@@ -0,0 +1,10 @@
+User Documentation
+==================
+
+.. toctree::
+    :maxdepth: 1
+
+    startup_sequence
+    names_hooking
+    asynchronous_execution
+    synchornization_mechanisms

libs/bsw/asyncFreeRtos/doc/user/names_hooking.rst

@@ -0,0 +1,19 @@
+.. _names_hooking:
+
+Names hooking
+=============
+
+The client of ``asyncFreeRtos`` module must provide implementation for the following functions,
+that define certain macroses in the configuration file **FreeRTOSConfig.h** of **FreeRTOS**:
+
+* ``asyncEnterTask()``
+* ``asyncLeaveTask()``
+* ``asyncEnterIsrGroup()``
+* ``asyncLeaveIsrGroup()``
+* ``asyncTickHook()``
+* ``asyncInitialized()``
+
+Related types
+-------------
+
+* ``StaticContextHook``