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