summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorSebastian Huber <sebastian.huber@embedded-brains.de>2020-09-16 16:22:15 +0200
committerSebastian Huber <sebastian.huber@embedded-brains.de>2020-09-16 16:33:04 +0200
commit3b1ae6dc995be529375d5193f4bcc05960820e7d (patch)
tree224bc482ccc4876c303230ae0607e22b9d3fc6d4
parent3bdf817950eadd75a2785b62220eb0b04533b9fd (diff)
downloadrtems-central-3b1ae6dc995be529375d5193f4bcc05960820e7d.tar.bz2
spec: Document rtems_task_construct(), ...
-rw-r--r--spec/acfg/if/max-thread-local-storage-size.yml5
-rw-r--r--spec/rtems/task/if/config.yml9
-rw-r--r--spec/rtems/task/if/construct.yml24
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