source: rtems-central/spec/rtems/part/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: 6.9 KB
Line 
1SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
2brief: |
3  Creates a partition.
4copyrights:
5- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
6- Copyright (C) 1988, 2008 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    - void *${.:/params[1]/name}
14    - ${/c/if/uintptr_t:/name} ${.:/params[2]/name}
15    - ${/c/if/size_t:/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 partition of fixed size buffers from a physically
22  contiguous memory space which starts at ${.:/params[1]/name} and is
23  ${.:/params[2]/name} bytes in size.  Each allocated buffer is to be of
24  ${.:/params[3]/name} in bytes.  The partition has the user-defined object
25  name specified in ${.:/params[0]/name}.  The assigned object identifier is
26  returned in ${.:/params[5]/name}.  This identifier is used to access the
27  partition with other partition related directives.
28
29  The **attribute set** specified in ${.:/params[4]/name} is built through a
30  *bitwise or* of the attribute constants described below.  Not all
31  combinations of attributes are allowed.  Some attributes are mutually
32  exclusive.  If mutually exclusive attributes are combined, the behaviour is
33  undefined.  Attributes not mentioned below are not evaluated by this
34  directive and have no effect.  Default attributes can be selected by using
35  the ${../../attr/if/default:/name} constant.
36
37  The partition has a local or global **scope** in a multiprocessing network
38  (this attribute does not refer to SMP systems).  The scope is selected by the
39  mutually exclusive ${../../attr/if/local:/name} and
40  ${../../attr/if/global:/name} attributes.
41
42  * A **local scope** is the default and can be emphasized through the use of
43    the ${../../attr/if/local:/name} attribute.  A local partition can be only
44    used by the node which created it.
45
46  * A **global scope** is established if the ${../../attr/if/global:/name}
47    attribute is set.  The memory space used for the partition must reside in
48    shared memory.  Setting the global attribute in a single node system has no
49    effect.
50enabled-by: true
51index-entries:
52- create a partition
53interface-type: function
54links:
55- role: interface-placement
56  uid: header
57- role: interface-ingroup
58  uid: group
59- role: constraint
60  uid: /constraint/directive-ctx-devinit
61- role: constraint
62  uid: /constraint/directive-ctx-task
63- role: constraint
64  uid: /constraint/object-allocator
65- role: constraint
66  uid: ../constraint/max
67- role: constraint
68  uid: /constraint/obj-unlimited-alloc
69- role: constraint
70  uid: ../../constraint/mp-max-global-objects
71name: rtems_partition_create
72notes: |
73  The partition buffer area specified by the ${.:/params[1]/name} must be
74  properly aligned.  It must be possible to directly store target architecture
75  pointers and also the user data.  For example, if the user data contains some
76  long double or vector data types, the partition buffer area and the buffer
77  size must take the alignment of these types into account which is usually
78  larger than the pointer alignment.  A cache line alignment may be also a
79  factor.  Use ${alignment:/name} to specify the minimum alignment of a
80  partition buffer type.
81
82  The ${.:/params[3]/name} parameter must be an integral multiple of the
83  pointer size on the target architecture.  Additionally,
84  ${.:/params[3]/name} must be large enough to hold two pointers on the
85  target architecture.  This is required for RTEMS to manage the buffers when
86  they are free.
87
88  For control and maintenance of the partition, RTEMS allocates a
89  ${/glossary/ptcb:/term} from the local PTCB free pool and initializes it.
90  Memory from the partition buffer area is not used by RTEMS to store the PTCB.
91
92  The PTCB for a global partition is allocated on the local node.  Partitions
93  should not be made global unless remote tasks must interact with the
94  partition.  This is to avoid the overhead incurred by the creation of a
95  global partition.  When a global partition is created, the partition's name
96  and identifier must be transmitted to every node in the system for insertion
97  in the local copy of the global object table.
98params:
99- description: is the object name of the partition.
100  dir: null
101  name: name
102- description: is the starting address of the buffer area used by the partition.
103  dir: null
104  name: starting_address
105- description: is the length in bytes of the buffer area used by the partition.
106  dir: null
107  name: length
108- description: is the size in bytes of a buffer managed by the partition.
109  dir: null
110  name: buffer_size
111- description: is the attribute set of the partition.
112  dir: null
113  name: attribute_set
114- description: |
115    is the pointer to an object identifier variable.  The identifier of the
116    created partition will be stored in this variable, in case of a successful
117    operation.
118  dir: out
119  name: id
120return:
121  return: null
122  return-values:
123  - description: |
124      The requested operation was successful.
125    value: ${../../status/if/successful:/name}
126  - description: |
127      The ${.:/params[0]/name} parameter was invalid.
128    value: ${../../status/if/invalid-name:/name}
129  - description: |
130      The ${.:/params[5]/name} parameter was ${/c/if/null:/name}.
131    value: ${../../status/if/invalid-address:/name}
132  - description: |
133      The ${.:/params[2]/name} parameter was 0.
134    value: ${../../status/if/invalid-size:/name}
135  - description: |
136      The ${.:/params[3]/name} parameter was 0.
137    value: ${../../status/if/invalid-size:/name}
138  - description: |
139      The ${.:/params[2]/name} parameter was less than the
140      ${.:/params[3]/name} parameter.
141    value: ${../../status/if/invalid-size:/name}
142  - description: |
143      The ${.:/params[3]/name} parameter was not an integral multiple of
144      the pointer size.
145    value: ${../../status/if/invalid-size:/name}
146  - description: |
147      The ${.:/params[3]/name} parameter was less than two times the
148      pointer size.
149    value: ${../../status/if/invalid-size:/name}
150  - description: |
151      The ${.:/params[1]/name} parameter was not on a pointer size
152      boundary.
153    value: ${../../status/if/invalid-address:/name}
154  - description: |
155      There was no inactive object available to create a partition.  The number
156      of partitions available to the application is configured through the
157      ${/acfg/if/max-partitions:/name} application configuration option.
158    value: ${../../status/if/too-many:/name}
159  - description: |
160      In multiprocessing configurations, there was no inactive global object
161      available to create a global semaphore.  The number of global objects
162      available to the application is configured through the
163      ${/acfg/if/mp-max-global-objects:/name} application configuration option.
164    value: ${../../status/if/too-many:/name}
165type: interface
Note: See TracBrowser for help on using the repository browser.