[rtems-central commit] spec: Specify rtems_task_construct()
Sebastian Huber
sebh at rtems.org
Wed Sep 16 09:39:20 UTC 2020
Module: rtems-central
Branch: master
Commit: 724df1c5ef711c9399cd8c33b23aee40304d0332
Changeset: http://git.rtems.org/rtems-central/commit/?id=724df1c5ef711c9399cd8c33b23aee40304d0332
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Fri Aug 21 16:04:36 2020 +0200
spec: Specify rtems_task_construct()
Previous directive name was rtems_task_create_from_config().
---
spec/if/acfg/max-thread-local-storage-size.yml | 4 +++
...ml => min-tasks-with-user-provided-storage.yml} | 16 +++++-----
.../{stack-alignment.yml => heap-alignment.yml} | 2 +-
spec/if/rtems/basedefs/align-down.yml | 35 ++++++++++++++++++++++
spec/if/rtems/basedefs/align-up.yml | 35 ++++++++++++++++++++++
spec/if/rtems/tasks/config.yml | 30 +++++++++++--------
.../{create-from-config.yml => construct.yml} | 19 ++++++------
spec/if/rtems/tasks/storage-alignment.yml | 11 +++----
spec/req/rtems/event/send-receive.yml | 8 ++---
...from-config-errors.yml => construct-errors.yml} | 17 +++++------
spec/req/rtems/tasks/ident.yml | 6 ++--
spec/testsuites/validation-0.yml | 11 +++++--
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 1479bdd..b07b57a 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
similarity index 61%
rename from spec/if/acfg/tasks-created-from-config.yml
rename to spec/if/acfg/min-tasks-with-user-provided-storage.yml
index e8863ac..2001c01 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
similarity index 91%
rename from spec/if/impl/cpu/stack-alignment.yml
rename to spec/if/impl/cpu/heap-alignment.yml
index ae6b754..2f09e1d 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 0000000..a309b03
--- /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 0000000..cb3a46d
--- /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 91943ff..f09fc1a 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
similarity index 85%
rename from spec/if/rtems/tasks/create-from-config.yml
rename to spec/if/rtems/tasks/construct.yml
index f592686..329b4b8 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 50b6499..6a8f677 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 9465a7a..5723e57 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
similarity index 95%
rename from spec/req/rtems/tasks/create-from-config-errors.yml
rename to spec/req/rtems/tasks/construct-errors.yml
index 8802e42..2e24ac9 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 43e0d23..9b4df1d 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 0a20e76..bf4042b 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 75f3fef..8cc3d67 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;
More information about the vc
mailing list