diff options
author | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2020-08-21 16:04:36 +0200 |
---|---|---|
committer | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2020-09-16 11:39:08 +0200 |
commit | 724df1c5ef711c9399cd8c33b23aee40304d0332 (patch) | |
tree | 3f181d1f7e5d88d667532f8f70f45c13486a1ab3 /spec | |
parent | spec: Specify rtems_task_create_from_config() (diff) | |
download | rtems-central-724df1c5ef711c9399cd8c33b23aee40304d0332.tar.bz2 |
spec: Specify rtems_task_construct()
Previous directive name was rtems_task_create_from_config().
Diffstat (limited to 'spec')
-rw-r--r-- | spec/if/acfg/max-thread-local-storage-size.yml | 4 | ||||
-rw-r--r-- | spec/if/acfg/min-tasks-with-user-provided-storage.yml (renamed from spec/if/acfg/tasks-created-from-config.yml) | 16 | ||||
-rw-r--r-- | spec/if/impl/cpu/heap-alignment.yml (renamed from spec/if/impl/cpu/stack-alignment.yml) | 2 | ||||
-rw-r--r-- | spec/if/rtems/basedefs/align-down.yml | 35 | ||||
-rw-r--r-- | spec/if/rtems/basedefs/align-up.yml | 35 | ||||
-rw-r--r-- | spec/if/rtems/tasks/config.yml | 30 | ||||
-rw-r--r-- | spec/if/rtems/tasks/construct.yml (renamed from spec/if/rtems/tasks/create-from-config.yml) | 19 | ||||
-rw-r--r-- | spec/if/rtems/tasks/storage-alignment.yml | 11 | ||||
-rw-r--r-- | spec/req/rtems/event/send-receive.yml | 8 | ||||
-rw-r--r-- | spec/req/rtems/tasks/construct-errors.yml (renamed from spec/req/rtems/tasks/create-from-config-errors.yml) | 17 | ||||
-rw-r--r-- | spec/req/rtems/tasks/ident.yml | 6 | ||||
-rw-r--r-- | spec/testsuites/validation-0.yml | 11 | ||||
-rw-r--r-- | spec/testsuites/validation/profile.yml | 8 |
13 files changed, 143 insertions, 59 deletions
diff --git a/spec/if/acfg/max-thread-local-storage-size.yml b/spec/if/acfg/max-thread-local-storage-size.yml index 1479bddc..b07b57af 100644 --- a/spec/if/acfg/max-thread-local-storage-size.yml +++ b/spec/if/acfg/max-thread-local-storage-size.yml @@ -26,5 +26,9 @@ notes: | objects used by the application in the statically-linked executable is greater than a non-zero value of this configuration option, then a fatal error will occur during system initialization. + + Use ${../rtems/basedefs/align-up:/name} and + ${../rtems/tasks/storage-alignment:/name} to adjust the size to meet the + minimum alignment requirement of a thread-local storage area. text: '' type: interface diff --git a/spec/if/acfg/tasks-created-from-config.yml b/spec/if/acfg/min-tasks-with-user-provided-storage.yml index e8863ac8..2001c01b 100644 --- a/spec/if/acfg/tasks-created-from-config.yml +++ b/spec/if/acfg/min-tasks-with-user-provided-storage.yml @@ -7,21 +7,21 @@ copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) default-value: 0 description: | - The value of this configuration option defines the count of Classic API Tasks - which are created by ${../rtems/tasks/create-from-config:/name}. + The value of this configuration option defines the minimum count of Classic + API Tasks which are constructed by ${../rtems/tasks/construct:/name}. enabled-by: true index-entries: [] interface-type: appl-config-option links: - role: appl-config-group-member uid: group-classic -name: CONFIGURE_TASKS_CREATED_FROM_CONFIG +name: CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE notes: | - By default, the calculation for the required memory in the RTEMS Workspace for - tasks assumes that all Classic API Tasks are created by + By default, the calculation for the required memory in the RTEMS Workspace + for tasks assumes that all Classic API Tasks are created by ${../rtems/tasks/create:/name}. This configuration option can be used to - reduce the required memory for the system-provided task storage - areas since tasks created by ${../rtems/tasks/create-from-config:/name} use a - user-provided task storage area. + reduce the required memory for the system-provided task storage areas since + tasks constructed by ${../rtems/tasks/construct:/name} use a user-provided + task storage area. text: '' type: interface diff --git a/spec/if/impl/cpu/stack-alignment.yml b/spec/if/impl/cpu/heap-alignment.yml index ae6b754c..2f09e1d4 100644 --- a/spec/if/impl/cpu/stack-alignment.yml +++ b/spec/if/impl/cpu/heap-alignment.yml @@ -6,6 +6,6 @@ interface-type: unspecified-define links: - role: interface-placement uid: header -name: CPU_STACK_ALIGNMENT +name: CPU_HEAP_ALIGNMENT reference: null type: interface diff --git a/spec/if/rtems/basedefs/align-down.yml b/spec/if/rtems/basedefs/align-down.yml new file mode 100644 index 00000000..a309b03f --- /dev/null +++ b/spec/if/rtems/basedefs/align-down.yml @@ -0,0 +1,35 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +brief: | + Returns the specified value aligned down to the specified alignment. +copyrights: +- Copyright (C) 2016 embedded brains GmbH (http://www.embedded-brains.de) +definition: + default: | + ( ( ${.:/params[0]/name} ) & ~( ( ${.:/params[1]/name} ) - 1 ) ) + variants: [] +description: null +enabled-by: true +interface-type: macro +links: +- role: interface-placement + uid: header +- role: interface-ingroup + uid: group +name: RTEMS_ALIGN_DOWN +notes: null +params: +- description: | + is the value to align down. + dir: null + name: _value +- description: | + is the desired alignment in bytes. The alignment shall be a power of two, + otherwise the returned value is undefined. The alignment parameter is + evaluated twice. + dir: null + name: _alignment +return: + return: | + The specified value aligned down to the specified alignment is returned. + return-values: [] +type: interface diff --git a/spec/if/rtems/basedefs/align-up.yml b/spec/if/rtems/basedefs/align-up.yml new file mode 100644 index 00000000..cb3a46dd --- /dev/null +++ b/spec/if/rtems/basedefs/align-up.yml @@ -0,0 +1,35 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +brief: | + Returns the specified value aligned up to the specified alignment. +copyrights: +- Copyright (C) 2016 embedded brains GmbH (http://www.embedded-brains.de) +definition: + default: | + ( ( ( ${.:/params[0]/name} ) + ( ${.:/params[1]/name} ) - 1 ) & ~( ( ${.:/params[1]/name} ) - 1 ) ) + variants: [] +description: null +enabled-by: true +interface-type: macro +links: +- role: interface-placement + uid: header +- role: interface-ingroup + uid: group +name: RTEMS_ALIGN_UP +notes: null +params: +- description: | + is the value to align up. + dir: null + name: _value +- description: | + is the desired alignment in bytes. The alignment shall be a power of two, + otherwise the returned value is undefined. The alignment parameter is + evaluated twice. + dir: null + name: _alignment +return: + return: | + The specified value aligned up to the specified alignment is returned. + return-values: [] +type: interface diff --git a/spec/if/rtems/tasks/config.yml b/spec/if/rtems/tasks/config.yml index 91943ff1..f09fc1a1 100644 --- a/spec/if/rtems/tasks/config.yml +++ b/spec/if/rtems/tasks/config.yml @@ -1,8 +1,7 @@ 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 the configuration of a task created by - ${create-from-config:/name}. + This structure defines the configuration of a task constructed by + ${construct:/name}. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) definition: @@ -31,9 +30,10 @@ definition: 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. + The task storage area begin address and size should be aligned by + ${storage-alignment:/name}. To avoid memory waste, use + ${../basedefs/aligned:/name} and ${storage-alignment:/name} to enforce + the recommended alignment of a statically allocated task storage area. kind: member name: storage_area variants: [] @@ -53,11 +53,15 @@ definition: task storage area. definition: ${../../c/size_t:/name} ${.:name} description: | + Use ${../basedefs/align-up:/name} and ${storage-alignment:/name} to + adjust the size to meet the minimum alignment requirement of a + thread-local storage area used to construct a task. + If the value is less than the actual thread-local storage size, then the - task creation by ${create-from-config:/name} fails. + task construction by ${construct:/name} fails. - If the is less than the task storage area size, then the task creation by - ${create-from-config:/name} fails. + If the is less than the task storage area size, then the task + construction by ${construct:/name} fails. kind: member name: maximum_thread_local_storage_size variants: [] @@ -66,10 +70,12 @@ definition: This member defines the optional handler to free the task storage area. definition: void ( *${.:name} )( void * ) 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 + It is called on exactly two mutually exclusive occasions. Firstly, when + the task construction aborts due to a failed task create extension, or + secondly, when 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}. + this handler. If handler is ${../../c/null:/name}, then no action will + be performed. kind: member name: storage_free variants: [] diff --git a/spec/if/rtems/tasks/create-from-config.yml b/spec/if/rtems/tasks/construct.yml index f592686e..329b4b83 100644 --- a/spec/if/rtems/tasks/create-from-config.yml +++ b/spec/if/rtems/tasks/construct.yml @@ -19,10 +19,10 @@ links: uid: header - role: interface-ingroup uid: group -name: rtems_task_create_from_config +name: rtems_task_construct 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 + In contrast to tasks created by ${create:/name}, the tasks constructed 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. @@ -32,16 +32,15 @@ notes: | 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}. + ${../../acfg/min-tasks-with-user-provided-storage:/name} application + configuration option. 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 + constructed task object will be stored in this variable, in case of a successful operation. dir: out name: id @@ -74,14 +73,14 @@ return: floating-point context. value: ${../status/invalid-size:/name} - description: | - There was no inactive task object available to create a task. + There was no inactive task object available to construct a task. value: ${../status/too-many:/name} - description: | In multiprocessing configurations, there was no inactive global object - available to create a global task. + available to construct a global task. value: ${../status/too-many:/name} - description: | - One of the task create extensions failed during the task creation. + One of the task create extensions failed during the task construction. value: ${../status/unsatisfied:/name} - description: | In SMP configurations, the non-preemption mode was not supported. diff --git a/spec/if/rtems/tasks/storage-alignment.yml b/spec/if/rtems/tasks/storage-alignment.yml index 50b64991..6a8f677c 100644 --- a/spec/if/rtems/tasks/storage-alignment.yml +++ b/spec/if/rtems/tasks/storage-alignment.yml @@ -1,12 +1,11 @@ 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. + This constant defines the recommended alignment of a task storage area in + bytes. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) definition: - default: | - ${../basedefs/aligned:/name}( ${../../impl/cpu/stack-alignment:/name} ) + default: ${../../impl/cpu/heap-alignment:/name} variants: [] description: null enabled-by: true @@ -17,5 +16,7 @@ links: - role: interface-ingroup uid: group name: RTEMS_TASK_STORAGE_ALIGNMENT -notes: null +notes: | + Use it with ${../basedefs/aligned:/name} to define the alignment of a + statically allocated task storage area. type: interface diff --git a/spec/req/rtems/event/send-receive.yml b/spec/req/rtems/event/send-receive.yml index 9465a7aa..5723e57e 100644 --- a/spec/req/rtems/event/send-receive.yml +++ b/spec/req/rtems/event/send-receive.yml @@ -461,14 +461,14 @@ test-prepare: | test-setup: brief: null code: | - static char task_stack[ RTEMS_MINIMUM_STACK_SIZE ]; + static char task_storage[ RTEMS_MINIMUM_STACK_SIZE ]; static const rtems_task_config task_config = { .name = rtems_build_name( 'W', 'O', 'R', 'K' ), .initial_priority = PRIO_LOW, - .stack_area = task_stack, - .stack_size = sizeof( task_stack ), + .storage_area = task_storage, + .storage_size = sizeof( task_storage ), .initial_modes = RTEMS_DEFAULT_MODES, - .attribute_set = RTEMS_DEFAULT_ATTRIBUTES + .attributes = RTEMS_DEFAULT_ATTRIBUTES }; rtems_status_code sc; diff --git a/spec/req/rtems/tasks/create-from-config-errors.yml b/spec/req/rtems/tasks/construct-errors.yml index 8802e422..2e24ac94 100644 --- a/spec/req/rtems/tasks/create-from-config-errors.yml +++ b/spec/req/rtems/tasks/construct-errors.yml @@ -5,7 +5,7 @@ enabled-by: true functional-type: action links: - role: interface-function - uid: /if/rtems/tasks/create-from-config + uid: /if/rtems/tasks/construct post-conditions: - name: Status states: @@ -19,7 +19,7 @@ post-conditions: T_rsc_success( sc ); text: | The status shall be RTEMS_SUCCESSFUL. The value of the object identifier - referenced by the id parameter shall identify the created task. + referenced by the id parameter shall identify the constructed task. - name: InvAddress test-code: | T_rsc( ctx->status, RTEMS_INVALID_ADDRESS ); @@ -134,7 +134,7 @@ pre-conditions: rtems_status_code sc; rtems_id id; - sc = rtems_task_create_from_config( &valid_task_config, &id ); + sc = rtems_task_construct( &valid_task_config, &id ); if ( sc == RTEMS_SUCCESSFUL ) { Objects_Control *obj; @@ -230,7 +230,7 @@ test-action: | ctx->config.maximum_thread_local_storage_size + ctx->stack_size, ctx->config.attributes ); - ctx->status = rtems_task_create_from_config( &ctx->config, ctx->id ); + ctx->status = rtems_task_construct( &ctx->config, ctx->id ); test-brief: null test-cleanup: | Chain_Node *node; @@ -303,9 +303,9 @@ test-stop: null test-support: | static _Thread_local int tls_variable; - #define MAX_TLS_SIZE 128 + #define MAX_TLS_SIZE RTEMS_ALIGN_UP( 128, RTEMS_TASK_STORAGE_ALIGNMENT ) - RTEMS_TASK_STORAGE_ALIGNMENT static char task_storage[ + RTEMS_ALIGNED( RTEMS_TASK_STORAGE_ALIGNMENT ) static char task_storage[ RTEMS_TASK_STORAGE_SIZE( MAX_TLS_SIZE + RTEMS_MINIMUM_STACK_SIZE, RTEMS_FLOATING_POINT @@ -327,14 +327,13 @@ test-support: | (void) executing; (void) created; - return - ReqRtemsTasksCreateFromConfigErrors_Instance.create_extension_status; + return ReqRtemsTasksConstructErrors_Instance.create_extension_status; } static const rtems_extensions_table extensions = { .thread_create = ThreadCreate }; -test-target: testsuites/validation/tc-tasks-create-from-config-errors.c +test-target: testsuites/validation/tc-task-construct-errors.c test-teardown: brief: null code: | diff --git a/spec/req/rtems/tasks/ident.yml b/spec/req/rtems/tasks/ident.yml index 43e0d23e..9b4df1d4 100644 --- a/spec/req/rtems/tasks/ident.yml +++ b/spec/req/rtems/tasks/ident.yml @@ -84,10 +84,10 @@ test-setup: static const rtems_task_config task_config = { .name = ClassicObjectIdentName, .initial_priority = 1, - .stack_area = task_storage, - .stack_size = sizeof( task_storage ), + .storage_area = task_storage, + .storage_size = sizeof( task_storage ), .initial_modes = RTEMS_DEFAULT_MODES, - .attribute_set = RTEMS_DEFAULT_ATTRIBUTES + .attributes = RTEMS_DEFAULT_ATTRIBUTES }; rtems_status_code sc; diff --git a/spec/testsuites/validation-0.yml b/spec/testsuites/validation-0.yml index 0a20e76d..bf4042b7 100644 --- a/spec/testsuites/validation-0.yml +++ b/spec/testsuites/validation-0.yml @@ -54,10 +54,12 @@ test-code: | rtems_fatal( RTEMS_FATAL_SOURCE_EXIT, (uint32_t) exit_code ); } - #define MAX_TLS_SIZE 64 + #define MAX_TLS_SIZE RTEMS_ALIGN_UP( 64, RTEMS_TASK_STORAGE_ALIGNMENT ) + #define ATTRIBUTES RTEMS_FLOATING_POINT - RTEMS_TASK_STORAGE_ALIGNMENT static char runner_task_storage[ + RTEMS_ALIGNED( RTEMS_TASK_STORAGE_ALIGNMENT ) + static char runner_task_storage[ RTEMS_TASK_STORAGE_SIZE( MAX_TLS_SIZE + RTEMS_MINIMUM_STACK_SIZE, ATTRIBUTES @@ -79,7 +81,7 @@ test-code: | rtems_id id; rtems_status_code sc; - sc = rtems_task_create_from_config( &runner_task_config, &id ); + sc = rtems_task_construct( &runner_task_config, &id ); if ( sc != RTEMS_SUCCESSFUL ) { rtems_fatal( RTEMS_FATAL_SOURCE_EXIT, 1 ); } @@ -112,6 +114,9 @@ test-code: | #define CONFIGURE_MAXIMUM_TASKS 3 + #define CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE \ + CONFIGURE_MAXIMUM_TASKS + #define CONFIGURE_MAXIMUM_TIMERS 3 #define CONFIGURE_MAXIMUM_USER_EXTENSIONS 3 diff --git a/spec/testsuites/validation/profile.yml b/spec/testsuites/validation/profile.yml index 75f3fef5..8cc3d674 100644 --- a/spec/testsuites/validation/profile.yml +++ b/spec/testsuites/validation/profile.yml @@ -35,7 +35,7 @@ test-code: | rtems_fatal(RTEMS_FATAL_SOURCE_APPLICATION, 123); } - static char init_task_stack[RTEMS_MINIMUM_STACK_SIZE]; + static char init_task_storage[RTEMS_MINIMUM_STACK_SIZE]; static char buffer[512]; @@ -75,10 +75,10 @@ test-code: | static const rtems_task_config task_config = { .name = NAME, .initial_priority = 1, - .stack_area = init_task_stack, - .stack_size = sizeof(init_task_stack), + .storage_area = init_task_storage, + .storage_size = sizeof(init_task_storage), .initial_modes = RTEMS_DEFAULT_MODES, - .attribute_set = RTEMS_DEFAULT_ATTRIBUTES + .attributes = RTEMS_DEFAULT_ATTRIBUTES }; rtems_id id; rtems_status_code sc; |