[rtems-central commit] spec: Document rtems_task_construct(), ...

[Sebastian Huber]

Module:    rtems-central
Branch:    master
Commit:    3b1ae6dc995be529375d5193f4bcc05960820e7d
Changeset: http://git.rtems.org/rtems-central/commit/?id=3b1ae6dc995be529375d5193f4bcc05960820e7d

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Wed Sep 16 16:22:15 2020 +0200

spec: Document rtems_task_construct(), ...

---

 spec/acfg/if/max-thread-local-storage-size.yml |  5 +++++
 spec/rtems/task/if/config.yml                  |  9 +++++++++
 spec/rtems/task/if/construct.yml               | 24 ++++++++++++++++++------
 3 files changed, 32 insertions(+), 6 deletions(-)

diff --git a/spec/acfg/if/max-thread-local-storage-size.yml b/spec/acfg/if/max-thread-local-storage-size.yml
index dfb979b..2424f3d 100644
--- a/spec/acfg/if/max-thread-local-storage-size.yml
+++ b/spec/acfg/if/max-thread-local-storage-size.yml
@@ -30,5 +30,10 @@ notes: |
   Use ${/rtems/basedefs/if/align-up:/name} and
   ${/rtems/task/if/storage-alignment:/name} to adjust the size to meet the
   minimum alignment requirement of a thread-local storage area.
+
+  The actual thread-local storage size is determined when the application
+  executable is linked.  The ``rtems-exeinfo`` command line tool included in
+  the RTEMS Tools can be used to obtain the thread-local storage size and
+  alignment of an application executable.
 text: ''
 type: interface
diff --git a/spec/rtems/task/if/config.yml b/spec/rtems/task/if/config.yml
index b2016fb..76e1337 100644
--- a/spec/rtems/task/if/config.yml
+++ b/spec/rtems/task/if/config.yml
@@ -62,6 +62,15 @@ definition:
 
       If the is less than the task storage area size, then the task
       construction by ${construct:/name} fails.
+
+      The actual thread-local storage size is determined when the application
+      executable is linked.  The ``rtems-exeinfo`` command line tool included
+      in the RTEMS Tools can be used to obtain the thread-local storage size
+      and alignment of an application executable.
+
+      The application may configure the maximum thread-local storage size for
+      all threads explicitly through the
+      ${/acfg/if/max-thread-local-storage-size} configuration option.
     kind: member
     name: maximum_thread_local_storage_size
   variants: []
diff --git a/spec/rtems/task/if/construct.yml b/spec/rtems/task/if/construct.yml
index d516807..867aee1 100644
--- a/spec/rtems/task/if/construct.yml
+++ b/spec/rtems/task/if/construct.yml
@@ -26,14 +26,26 @@ notes: |
   contains the task stack, the thread-local storage, and the floating-point
   context on architectures with a separate floating-point context.
 
-  It is not recommended to mix ${create:/name} and ${.:/name} in an
-  application.  This directive is intended for applications which do not want
-  to use the RTEMS Workspace and instead statically allocate all operating
-  system resources.  The stack space estimate done by <rtems/confdefs.h>
-  assumes that all tasks are created by ${create:/name}.  The estimate can be
-  adjusted to take user-provided task storage areas into account through the
+  This directive is intended for applications which do not want to use the
+  RTEMS Workspace and instead statically allocate all operating system
+  resources.  It is not recommended to use ${create:/name} and ${.:/name}
+  together in an application.  It is also not recommended to use ${.:/name} for
+  drivers or general purpose libraries.  The reason for these recommendations
+  is that the task configuration needs settings which can be only given with a
+  through knowledge of the application resources.
+
+  An application based solely on static allocation can avoid any runtime memory
+  allocators.  This can simplfiy the application architecture as well as any
+  analysis that may be required.
+
+  The stack space estimate done by <rtems/confdefs.h> assumes that all tasks
+  are created by ${create:/name}.  The estimate can be adjusted to take
+  user-provided task storage areas into account through the
   ${/acfg/if/min-tasks-with-user-provided-storage:/name} application
   configuration option.
+
+  The ${/acfg/if/max-tasks:/name} should include tasks constructed by
+  ${create:/name}.
 params:
 - description: is the task configuration.
   dir: null