diff options
author | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2020-09-10 15:21:24 +0200 |
---|---|---|
committer | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2020-09-11 17:25:23 +0200 |
commit | 51f9a65fce42a4d1cbed71738840d29f3a1257f6 (patch) | |
tree | ef67579c35733faea0207104b5134a0d0540202d /spec/if/rtems | |
parent | fc32261c208546ed7af52aaba04354553080cccb (diff) |
spec: Specify rtems_task_create_from_config()
Diffstat (limited to 'spec/if/rtems')
-rw-r--r-- | spec/if/rtems/tasks/build.yml | 73 | ||||
-rw-r--r-- | spec/if/rtems/tasks/config.yml | 62 | ||||
-rw-r--r-- | spec/if/rtems/tasks/create-from-config.yml | 92 | ||||
-rw-r--r-- | spec/if/rtems/tasks/storage-alignment.yml | 21 | ||||
-rw-r--r-- | spec/if/rtems/tasks/storage-size.yml | 41 |
5 files changed, 199 insertions, 90 deletions
diff --git a/spec/if/rtems/tasks/build.yml b/spec/if/rtems/tasks/build.yml deleted file mode 100644 index 8d06585f..00000000 --- a/spec/if/rtems/tasks/build.yml +++ /dev/null @@ -1,73 +0,0 @@ -SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: | - Builds a task according to the task configuration. -copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) -definition: - default: - body: null - params: - - const ${config:/name} *${.:/params[0]/name} - - ${../types/id:/name} *${.:/params[1]/name} - return: ${../status/code:/name} - variants: [] -description: null -enabled-by: true -interface-type: function -links: -- role: interface-placement - uid: header -- role: interface-ingroup - uid: group -name: rtems_task_build -notes: null -params: -- description: is the task configuration. - dir: null - name: config -- description: | - is the pointer to an object identifier variable. The identifier of the new - task object will be stored in this variable, in case of a successful - operation. - dir: out - name: id -return: - return: null - return-values: - - description: | - The requested operation was successful. - value: ${../status/successful:/name} - - description: | - The ${.:/params[1]/name} parameter was ${/if/c/null:/name}. - value: ${../status/invalid-address:/name} - - description: | - The task name was invalid. - value: ${../status/invalid-name:/name} - - description: | - The initial task priority was invalid. - value: ${../status/invalid-priority:/name} - - description: | - The multiprocessing support was not configured. - value: ${../status/mp-not-configured:/name} - - description: | - There was no inactive task object available to build a new task. - value: ${../status/too-many:/name} - - description: | - In multiprocessing configurations, there was no inactive global object - available to build a new task. - value: ${../status/too-many:/name} - - description: | - The provided task storage area was too small. The task storage area - includes the task stack, the thread-local storage, and the floating point - context. - value: ${../status/unsatisfied:/name} - - description: | - One of the task create extensions failed to create the new task. - value: ${../status/unsatisfied:/name} - - description: | - In SMP configurations, the non-preemption mode was not supported. - value: ${../status/unsatisfied:/name} - - description: | - In SMP configurations, the interrupt level mode was not supported. - value: ${../status/unsatisfied:/name} -type: interface diff --git a/spec/if/rtems/tasks/config.yml b/spec/if/rtems/tasks/config.yml index a1d4480f..91943ff1 100644 --- a/spec/if/rtems/tasks/config.yml +++ b/spec/if/rtems/tasks/config.yml @@ -1,12 +1,14 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | - This structure defines a task configuration used to build a task. + This structure defines a task configuration used to build a task. This + structure defines the configuration of a task created by + ${create-from-config:/name}. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) definition: - default: brief: | - This member is the name of the task. + This member defines the name of the task. definition: ${../types/name:/name} ${.:name} description: null kind: member @@ -14,7 +16,7 @@ definition: variants: [] - default: brief: | - This member is the initial priority of the task. + This member defines the initial priority of the task. definition: ${priority:/name} ${.:name} description: null kind: member @@ -22,32 +24,58 @@ definition: variants: [] - default: brief: | - This member is task stack area begin address for the task. + This member shall point to the task storage area begin. definition: void *${.:name} - description: null + description: | + The task storage area will contain the task stack, the thread-local + storage, and the floating-point context on architectures with a separate + floating-point context. + + There are no alignment requirements for the task storage area. To avoid + memory waste, use the ${storage-alignment:/name} variable attribute to + enforce the recommended alignment of the task storage area. kind: member - name: stack_area + name: storage_area variants: [] - default: brief: | - This member is task stack area size in bytes for the task. - definition: ${/if/c/size_t:/name} ${.:name} - description: null + This member defines size of the task storage area in bytes. + definition: ${../../c/size_t:/name} ${.:name} + description: | + Use the ${storage-size:/name} macro to determine the recommended task + storage area size. kind: member - name: stack_size + name: storage_size variants: [] - default: brief: | - This member is the function to free the task stack area if the task gets - deleted. + This member defines the maximum thread-local storage size supported by the + task storage area. + definition: ${../../c/size_t:/name} ${.:name} + description: | + If the value is less than the actual thread-local storage size, then the + task creation by ${create-from-config:/name} fails. + + If the is less than the task storage area size, then the task creation by + ${create-from-config:/name} fails. + kind: member + name: maximum_thread_local_storage_size + variants: [] +- default: + brief: | + This member defines the optional handler to free the task storage area. definition: void ( *${.:name} )( void * ) - description: null + description: | + It is called when the task creation aborts due to a failed task create + extension or the task is deleted. It is called from task context under + protection of the object allocator lock. It is allowed to call free() in + this handler. The handler may be ${../../c/null:/name}. kind: member - name: stack_free + name: storage_free variants: [] - default: brief: | - This member is set of initial modes of the task. + This member defines the initial modes of the task. definition: ${../modes/mode:/name} ${.:name} description: null kind: member @@ -55,11 +83,11 @@ definition: variants: [] - default: brief: | - This member is set of attributes of the task. + This member defines the attributes of the task. definition: ${../attr/attribute:/name} ${.:name} description: null kind: member - name: attribute_set + name: attributes variants: [] definition-kind: typedef-only description: null diff --git a/spec/if/rtems/tasks/create-from-config.yml b/spec/if/rtems/tasks/create-from-config.yml new file mode 100644 index 00000000..f592686e --- /dev/null +++ b/spec/if/rtems/tasks/create-from-config.yml @@ -0,0 +1,92 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +brief: | + Creates a task from the specified the task configuration. +copyrights: +- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +definition: + default: + body: null + params: + - const ${config:/name} *${.:/params[0]/name} + - ${../types/id:/name} *${.:/params[1]/name} + return: ${../status/code:/name} + variants: [] +description: null +enabled-by: true +interface-type: function +links: +- role: interface-placement + uid: header +- role: interface-ingroup + uid: group +name: rtems_task_create_from_config +notes: | + In contrast to tasks created by ${create:/name}, the tasks created by this + directive use a user-provided task storage area. The task storage area + 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 + ${../../acfg/tasks-created-from-config:/name} application configuration + option or a custom task stack allocator, see + ${../../acfg/task-stack-allocator:/name}. +params: +- description: is the task configuration. + dir: null + name: config +- description: | + is the pointer to an object identifier variable. The identifier of the + created task object will be stored in this variable, in case of a + successful operation. + dir: out + name: id +return: + return: null + return-values: + - description: | + The requested operation was successful. + value: ${../status/successful:/name} + - description: | + The ${.:/params[1]/name} parameter was ${/if/c/null:/name}. + value: ${../status/invalid-address:/name} + - description: | + The task name was invalid. + value: ${../status/invalid-name:/name} + - description: | + The initial task priority was invalid. + value: ${../status/invalid-priority:/name} + - description: | + The thread-local storage size is greater than the maximum thread-local + storage size specified in the task configuration. The thread-local + storage size is determined by the thread-local variables used by the + application and ${../../acfg/max-thread-local-storage-size:/name}. + value: ${../status/invalid-size:/name} + - description: | + The task storage area was too small to provide a task stack of the + configured minimum size, see ${../../acfg/min-task-stack-size:/name}. + The task storage area contains the task stack, the thread-local storage, + and the floating-point context on architectures with a separate + floating-point context. + value: ${../status/invalid-size:/name} + - description: | + There was no inactive task object available to create a task. + value: ${../status/too-many:/name} + - description: | + In multiprocessing configurations, there was no inactive global object + available to create a global task. + value: ${../status/too-many:/name} + - description: | + One of the task create extensions failed during the task creation. + value: ${../status/unsatisfied:/name} + - description: | + In SMP configurations, the non-preemption mode was not supported. + value: ${../status/unsatisfied:/name} + - description: | + In SMP configurations, the interrupt level mode was not supported. + value: ${../status/unsatisfied:/name} +type: interface diff --git a/spec/if/rtems/tasks/storage-alignment.yml b/spec/if/rtems/tasks/storage-alignment.yml new file mode 100644 index 00000000..50b64991 --- /dev/null +++ b/spec/if/rtems/tasks/storage-alignment.yml @@ -0,0 +1,21 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +brief: | + This variable attribute defines the recommended alignment of a task storage + area. +copyrights: +- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +definition: + default: | + ${../basedefs/aligned:/name}( ${../../impl/cpu/stack-alignment:/name} ) + variants: [] +description: null +enabled-by: true +interface-type: define +links: +- role: interface-placement + uid: header +- role: interface-ingroup + uid: group +name: RTEMS_TASK_STORAGE_ALIGNMENT +notes: null +type: interface diff --git a/spec/if/rtems/tasks/storage-size.yml b/spec/if/rtems/tasks/storage-size.yml new file mode 100644 index 00000000..3ae85838 --- /dev/null +++ b/spec/if/rtems/tasks/storage-size.yml @@ -0,0 +1,41 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +brief: | + Returns the recommended task storage area size for the specified size and task + attributes. +copyrights: +- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +definition: + default: | + ( ( ${.:/params[0]/name} ) + + ( ( ( ${.:/params[1]/name} ) & ${../attr/floating-point:/name} ) != 0 ? + ${../../impl/context/fp-size:/name} : 0 ) ) + variants: + - definition: | + ( ( ${.:/params[0]/name} ) + ${../../impl/context/fp-size:/name} ) + enabled-by: + - ${../../impl/cpu/all-tasks-are-fp:/name} == ${../basedefs/true:/name} +description: null +enabled-by: true +interface-type: macro +links: +- role: interface-placement + uid: header +- role: interface-ingroup + uid: group +name: RTEMS_TASK_STORAGE_SIZE +notes: null +params: +- description: | + is the size dedicated to the task stack and thread-local storage in bytes. + dir: null + name: _size +- description: | + is the attribute set of the task using the storage area. + dir: null + name: _attributes +return: + return: | + The recommended task storage area size calculated from the input parameters + is returned. + return-values: [] +type: interface |