source: rtems-central/spec/rtems/task/if/create.yml @ 45b6997

Last change on this file since 45b6997 was 45b6997, checked in by Sebastian Huber <sebastian.huber@…>, on Jan 13, 2021 at 1:05:42 PM

spec: Document all create directives

  • Property mode set to 100644
File size: 11.8 KB
Line 
1SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
2brief: |
3  Creates a task.
4copyrights:
5- Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
6- Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR)
7definition:
8  default:
9    attributes: null
10    body: null
11    params:
12    - ${../../type/if/name:/name} ${.:/params[0]/name}
13    - ${priority:/name} ${.:/params[1]/name}
14    - ${/c/if/size_t:/name} ${.:/params[2]/name}
15    - ${../../mode/if/mode:/name} ${.:/params[3]/name}
16    - ${../../attr/if/attribute:/name} ${.:/params[4]/name}
17    - ${../../type/if/id:/name} *${.:/params[5]/name}
18    return: ${../../status/if/code:/name}
19  variants: []
20description: |
21  This directive creates a task which resides on the local node.  The task has
22  the user-defined object name specified in ${.:/params[0]/name}.  The assigned
23  object identifier is returned in ${.:/params[5]/name}.  This identifier is
24  used to access the task with other task related directives.
25
26  The **initial priority** of the task is specified in ${.:/params[1]/name}.
27  The scheduler of the created task is the scheduler of the calling task at
28  some point during the task creation.  The initial task priority specified in
29  ${.:/params[1]/name} shall be valid for this scheduler.
30
31  The **stack size** of the task is specified in ${.:/params[2]/name}.  If the
32  requested stack size is less than the configured minimum stack size, then
33  RTEMS will use the configured minimum as the stack size for this task.  The
34  configured minimum stack size is defined by the
35  ${/acfg/if/min-task-stack-size:/name} application configuration option.  In
36  addition to being able to specify the task stack size as a integer, there are
37  two constants which may be specified:
38
39  * The ${minimum-stack-size:/name} constant can be specified to use the
40    **recommended minimum stack size** for the target processor.  This value is
41    selected by the RTEMS maintainers conservatively to minimize the risk of
42    blown stacks for most user applications.  Using this constant when
43    specifying the task stack size, indicates that the stack size will be at
44    least ${minimum-stack-size:/name} bytes in size.  If the user configured
45    minimum stack size is larger than the recommended minimum, then it will be
46    used.
47
48  * The ${configured-minimum-stack-size:/name} constant can be specified to use
49    the minimum stack size that was configured by the application.  If not
50    explicitly configured by the application, the default configured minimum
51    stack size is the target processor dependent value
52    ${minimum-stack-size:/name}.  Since this uses the configured minimum stack
53    size value, you may get a stack size that is smaller or larger than the
54    recommended minimum.  This can be used to provide large stacks for all
55    tasks on complex applications or small stacks on applications that are
56    trying to conserve memory.
57
58  The **initial mode set** specified in ${.:/params[3]/name} is built through a
59  *bitwise or* of the mode constants described below.  Not all combinations of
60  modes are allowed.  Some modes are mutually exclusive.  If mutually exclusive
61  modes are combined, the behaviour is undefined.  Default task modes can be
62  selected by using the ${../../mode/if/default:/name} constant.  The task mode
63  set defines
64
65  * the preemption mode of the task: ${../../mode/if/preempt:/name} (default)
66    or ${../../mode/if/no-preempt:/name},
67
68  * the timeslicing mode of the task: ${../../mode/if/timeslice:/name} or
69    ${../../mode/if/no-timeslice:/name} (default),
70
71  * the ${/glossary/asr:/term} processing mode of the task:
72    ${../../mode/if/asr:/name} (default) or ${../../mode/if/no-asr:/name},
73
74  * the interrupt level mode of the task:
75    ${../../mode/if/interrupt-level:/name}.
76
77  The **initial preemption mode** of the task is enabled or disabled.
78
79  * An **enabled preemption** is the default and can be emphasized through the
80    use of the ${../../mode/if/preempt:/name} mode constant.
81
82  * A **disabled preemption** is set by the ${../../mode/if/no-preempt:/name}
83    mode constant.
84
85  The **initial timeslicing mode** of the task is enabled or disabled.
86
87  * A **disabled timeslicing** is the default and can be emphasized through the
88    use of the ${../../mode/if/no-timeslice:/name} mode constant.
89
90  * An **enabled timeslicing** is set by the ${../../mode/if/timeslice:/name}
91    mode constant.
92
93  The **initial ASR processing mode** of the task is enabled or disabled.
94
95  * An **enabled ASR processing** is the default and can be emphasized through
96    the use of the ${../../mode/if/asr:/name} mode constant.
97
98  * A **disabled ASR processing** is set by the ${../../mode/if/no-asr:/name}
99    mode constant.
100
101  The **initial interrupt level mode** of the task is defined by
102  ${../../mode/if/interrupt-level:/name}.
103
104  * Task execution with **interrupts enabled** the default and can be
105    emphasized through the use of the ${../../mode/if/interrupt-level:/name}
106    mode macro with a value of zero (0) for the parameter.  An interrupt level
107    of zero is associated with enabled interrupts on all target processors.
108
109  * Task execution at a **non-zero interrupt level** can be specified by the
110    ${../../mode/if/interrupt-level:/name} mode macro with a non-zero value for
111    the parameter.  The interrupt level portion of the task mode supports a
112    maximum of 256 interrupt levels.  These levels are mapped onto the
113    interrupt levels actually supported by the target processor in a processor
114    dependent fashion.
115
116  The **attribute set** specified in ${.:/params[4]/name} is built through a
117  *bitwise or* of the attribute constants described below.  Not all
118  combinations of attributes are allowed.  Some attributes are mutually
119  exclusive.  If mutually exclusive attributes are combined, the behaviour is
120  undefined.  Attributes not mentioned below are not evaluated by this
121  directive and have no effect.  Default attributes can be selected by using
122  the ${../../attr/if/default:/name} constant.  The attribute set defines
123
124  * the scope of the task: ${../../attr/if/local:/name} (default) or
125    ${../../attr/if/global:/name} and
126
127  * the floating-point unit use of the task:
128    ${../../attr/if/floating-point:/name} or
129    ${../../attr/if/no-floating-point:/name} (default).
130
131  The task has a local or global **scope** in a multiprocessing network
132  (this attribute does not refer to SMP systems).  The scope is selected by the
133  mutually exclusive ${../../attr/if/local:/name} and
134  ${../../attr/if/global:/name} attributes.
135
136  * A **local scope** is the default and can be emphasized through the use of
137    the ${../../attr/if/local:/name} attribute.  A local task can be only used
138    by the node which created it.
139
140  * A **global scope** is established if the ${../../attr/if/global:/name}
141    attribute is set.  Setting the global attribute in a single node system has
142    no effect.the
143
144  The **use of the floating-point unit** is selected by the mutually exclusive
145  ${../../attr/if/floating-point:/name} and
146  ${../../attr/if/no-floating-point:/name} attributes.  On some target
147  processors, the use of the floating-point unit can be enabled or disabled for
148  each task.  Other target processors may have no hardware floating-point unit
149  or enable the use of the floating-point unit for all tasks.  Consult the
150  *RTEMS CPU Architecture Supplement* for the details.
151
152  * A **disabled floating-point unit** is the default and can be emphasized
153    through use of the ${../../attr/if/no-floating-point:/name} attribute.  For
154    performance reasons, it is recommended that tasks not using the
155    floating-point unit should specify this attribute.
156
157  * An **enabled floating-point unit** is selected by the
158    ${../../attr/if/floating-point:/name} attribute.
159enabled-by: true
160index-entries:
161- create a task
162interface-type: function
163links:
164- role: interface-placement
165  uid: header
166- role: interface-ingroup
167  uid: group
168- role: constraint
169  uid: /constraint/directive-ctx-devinit
170- role: constraint
171  uid: /constraint/directive-ctx-task
172- role: constraint
173  uid: /constraint/object-allocator
174- role: constraint
175  uid: ../constraint/max
176- role: constraint
177  uid: /constraint/obj-unlimited-alloc
178- role: constraint
179  uid: ../../constraint/mp-max-global-objects
180name: rtems_task_create
181notes: |
182  The task processor affinity is initialized to the set of online processors.
183
184  When created, a task is placed in the dormant state and can only be made
185  ready to execute using the directive ${start:/name}.
186
187  Application developers should consider the stack usage of the device drivers
188  when calculating the stack size required for tasks which utilize the driver.
189  The task stack size shall account for an target processor dependent interrupt
190  stack frame which may be placed on the stack of the interrupted task while
191  servicing an interrupt.  The stack checker may be used to monitor the stack
192  usage, see ${/acfg/if/stack-checker-enabled:/name}.
193
194  For control and maintenance of the task, RTEMS allocates a
195  ${/glossary/tcb:/term} from the local TCB free pool and initializes it.
196
197  The TCB for a global task is allocated on the local node.  Task should not be
198  made global unless remote tasks must interact with the task.  This is to
199  avoid the system overhead incurred by the creation of a global task.  When a
200  global task is created, the task's name and identifier must be transmitted to
201  every node in the system for insertion in the local copy of the global object
202  table.
203params:
204- description: |
205    is the object name of the task.
206  dir: null
207  name: name
208- description: |
209    is the initial task priority.
210  dir: null
211  name: initial_priority
212- description: |
213    is the task stack size in bytes.
214  dir: null
215  name: stack_size
216- description: |
217    is the initial mode set of the task.
218  dir: null
219  name: initial_modes
220- description: |
221    is the attribute set of the task.
222  dir: null
223  name: attribute_set
224- description: |
225    is the pointer to an object identifier variable.  The identifier of the
226    created task will be stored in this variable, in case of a successful
227    operation.
228  dir: out
229  name: id
230return:
231  return: null
232  return-values:
233  - description: |
234      The requested operation was successful.
235    value: ${../../status/if/successful:/name}
236  - description: |
237      The ${.:/params[0]/name} parameter was invalid.
238    value: ${../../status/if/invalid-name:/name}
239  - description: |
240      The ${.:/params[5]/name} parameter was ${/c/if/null:/name}.
241    value: ${../../status/if/invalid-address:/name}
242  - description: |
243      The ${.:/params[1]/name} was invalid.
244    value: ${../../status/if/invalid-priority:/name}
245  - description: |
246      There was no inactive object available to create a task.  The number of
247      tasks available to the application is configured through the
248      ${/acfg/if/max-tasks:/name} application configuration option.
249    value: ${../../status/if/too-many:/name}
250  - description: |
251      In multiprocessing configurations, there was no inactive global object
252      available to create a global task.  The number of global objects
253      available to the application is configured through the
254      ${/acfg/if/mp-max-global-objects:/name} application configuration option.
255    value: ${../../status/if/too-many:/name}
256  - description: |
257      There was not enough memory to allocate the task storage area.  The task
258      storage area contains the task stack, the thread-local storage, and the
259      floating point context.
260    value: ${../../status/if/unsatisfied:/name}
261  - description: |
262      One of the task create extensions failed to create the task.
263    value: ${../../status/if/unsatisfied:/name}
264  - description: |
265      In SMP configurations, the non-preemption mode was not supported.
266    value: ${../../status/if/unsatisfied:/name}
267  - description: |
268      In SMP configurations, the interrupt level mode was not supported.
269    value: ${../../status/if/unsatisfied:/name}
270type: interface
Note: See TracBrowser for help on using the repository browser.