1 | SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause |
---|
2 | brief: | |
---|
3 | Constructs a task from the specified the task configuration. |
---|
4 | copyrights: |
---|
5 | - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) |
---|
6 | definition: |
---|
7 | default: |
---|
8 | body: null |
---|
9 | params: |
---|
10 | - const ${config:/name} *${.:/params[0]/name} |
---|
11 | - ${../../type/if/id:/name} *${.:/params[1]/name} |
---|
12 | return: ${../../status/if/code:/name} |
---|
13 | variants: [] |
---|
14 | description: null |
---|
15 | enabled-by: true |
---|
16 | interface-type: function |
---|
17 | links: |
---|
18 | - role: interface-placement |
---|
19 | uid: header |
---|
20 | - role: interface-ingroup |
---|
21 | uid: group |
---|
22 | name: rtems_task_construct |
---|
23 | notes: | |
---|
24 | In contrast to tasks created by ${create:/name}, the tasks constructed by |
---|
25 | this directive use a user-provided task storage area. The task storage area |
---|
26 | contains the task stack, the thread-local storage, and the floating-point |
---|
27 | context on architectures with a separate floating-point context. |
---|
28 | |
---|
29 | This directive is intended for applications which do not want to use the |
---|
30 | RTEMS Workspace and instead statically allocate all operating system |
---|
31 | resources. It is not recommended to use ${create:/name} and ${.:/name} |
---|
32 | together in an application. It is also not recommended to use ${.:/name} for |
---|
33 | drivers or general purpose libraries. The reason for these recommendations |
---|
34 | is that the task configuration needs settings which can be only given with a |
---|
35 | through knowledge of the application resources. |
---|
36 | |
---|
37 | An application based solely on static allocation can avoid any runtime memory |
---|
38 | allocators. This can simplfiy the application architecture as well as any |
---|
39 | analysis that may be required. |
---|
40 | |
---|
41 | The stack space estimate done by <rtems/confdefs.h> assumes that all tasks |
---|
42 | are created by ${create:/name}. The estimate can be adjusted to take |
---|
43 | user-provided task storage areas into account through the |
---|
44 | ${/acfg/if/min-tasks-with-user-provided-storage:/name} application |
---|
45 | configuration option. |
---|
46 | |
---|
47 | The ${/acfg/if/max-tasks:/name} should include tasks constructed by |
---|
48 | ${create:/name}. |
---|
49 | params: |
---|
50 | - description: is the task configuration. |
---|
51 | dir: null |
---|
52 | name: config |
---|
53 | - description: | |
---|
54 | is the pointer to an object identifier variable. The identifier of the |
---|
55 | constructed task object will be stored in this variable, in case of a |
---|
56 | successful operation. |
---|
57 | dir: out |
---|
58 | name: id |
---|
59 | return: |
---|
60 | return: null |
---|
61 | return-values: |
---|
62 | - description: | |
---|
63 | The requested operation was successful. |
---|
64 | value: ${../../status/if/successful:/name} |
---|
65 | - description: | |
---|
66 | The ${.:/params[1]/name} parameter was ${/c/if/null:/name}. |
---|
67 | value: ${../../status/if/invalid-address:/name} |
---|
68 | - description: | |
---|
69 | The task name was invalid. |
---|
70 | value: ${../../status/if/invalid-name:/name} |
---|
71 | - description: | |
---|
72 | The initial task priority was invalid. |
---|
73 | value: ${../../status/if/invalid-priority:/name} |
---|
74 | - description: | |
---|
75 | The thread-local storage size is greater than the maximum thread-local |
---|
76 | storage size specified in the task configuration. The thread-local |
---|
77 | storage size is determined by the thread-local variables used by the |
---|
78 | application and ${/acfg/if/max-thread-local-storage-size:/name}. |
---|
79 | value: ${../../status/if/invalid-size:/name} |
---|
80 | - description: | |
---|
81 | The task storage area was too small to provide a task stack of the |
---|
82 | configured minimum size, see ${/acfg/if/min-task-stack-size:/name}. |
---|
83 | The task storage area contains the task stack, the thread-local storage, |
---|
84 | and the floating-point context on architectures with a separate |
---|
85 | floating-point context. |
---|
86 | value: ${../../status/if/invalid-size:/name} |
---|
87 | - description: | |
---|
88 | There was no inactive task object available to construct a task. |
---|
89 | value: ${../../status/if/too-many:/name} |
---|
90 | - description: | |
---|
91 | In multiprocessing configurations, there was no inactive global object |
---|
92 | available to construct a global task. |
---|
93 | value: ${../../status/if/too-many:/name} |
---|
94 | - description: | |
---|
95 | One of the task create extensions failed during the task construction. |
---|
96 | value: ${../../status/if/unsatisfied:/name} |
---|
97 | - description: | |
---|
98 | In SMP configurations, the non-preemption mode was not supported. |
---|
99 | value: ${../../status/if/unsatisfied:/name} |
---|
100 | - description: | |
---|
101 | In SMP configurations, the interrupt level mode was not supported. |
---|
102 | value: ${../../status/if/unsatisfied:/name} |
---|
103 | type: interface |
---|