From 3b1ae6dc995be529375d5193f4bcc05960820e7d Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Wed, 16 Sep 2020 16:22:15 +0200 Subject: 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 dfb979ba..2424f3de 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 b2016fb3..76e1337d 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 d5168070..867aee1d 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 - 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 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 -- cgit v1.2.3