Merge pull request #1093 from esrlabs/cr-131286

Adding rationale for fixed assignment of activities to threads.

Author: armin-acn

docs/features/frameworks/feo/_assets/example_task_chain.png

@@ -184,8 +184,8 @@ Queuing of topics:
 * Queue enable and queue length are "runtime static" configuration settings
 
 
-Process/Thread Mapping 
-======================
+Process/Thread/Activity Mapping
+===============================
 
 * An application consists of one or more processes
 * One of the processes is the primary process
@@ -208,6 +208,50 @@ Process/Thread Mapping
   achieve Freedom From Interference for safety relevant applications
 
 
+Static mapping of activities to threads
+'''''''''''''''''''''''''''''''''''''''
+
+As pointed out above, FEO activities are required to be mapped to threads in a static way.
+The rationale behind this requirement is:
+
+* Calling activity functions init(), step() and shutdown() from a single pre-defined thread
+  allows implementations to make use of thread-local optimizations such as thread-local variables.
+* Calling an activity's step() function from different threads in different iterations of the
+  task chain may cause execution time jitter e.g. from unpredictable cache misses or different
+  properties of the processor cores the respective threads may be assigned to.
+* Most importantly, a dynamic assignment of activities to threads may result in non-deterministic
+  variations of the task-chain execution time.
+
+To understand how a dynamic thread assignment can cause execution time variations, consider
+the following example (sub-) task chain.
+
+|example_task_chain|
+
+Here, activity 6 depends on, i.e. must be executed after activities 1 to 5. The length of the bars
+is intended to indicate the relative computation time needed by the respective activity on a
+single processor core. It is assumed that all of these activities will be executed in the same process.
+
+In a simple approach, each of the activities 1 to 5 could be assigned to its own thread and
+activity 6 could be executed subsequently in one of these threads as shown in the figure below.
+Each blue "lane" indicates one thread.
+
+|example_task_chain_5_threads|
+
+If each thread runs on a separate core and execution is not interrupted by other tasks, the length of
+the blue box is related to the total execution time of the task chain.
+
+Approximately the same total execution time can be achieved with only 3 threads (on three cores), if the
+tasks are assigned in an optimized way:
+
+|example_task_chain_3_threads_optimized|
+
+If, on the other hand,  activities are assigned to the same 3 threads in a dynamic way, the execution
+time may vary unpredictably, because of the possibly varying execution sequence of activities,
+as can be seen below.
+
+|example_task_chain_3_threads_dynamic|
+
+
 Lifecycle
 =========
 
@@ -383,3 +427,11 @@ timing of activities, supporting safety-critical applications
 in the automotive domain. In this domain the footprint of the framework is curcial especially
 w.r.t impact of computation load and latency.
 
+
+.. |example_task_chain| image:: _assets/example_task_chain.png
+
+.. |example_task_chain_5_threads| image:: _assets/example_task_chain_5_threads.png
+
+.. |example_task_chain_3_threads_optimized| image:: _assets/example_task_chain_3_threads_optimized.png
+
+.. |example_task_chain_3_threads_dynamic| image:: _assets/example_task_chain_3_threads_dynamic.png