source: rtems-central/spec/rtems/part/if/create.yml @ dc19046

Last change on this file since dc19046 was dc19046, checked in by Sebastian Huber <sebastian.huber@…>, on Dec 1, 2020 at 3:32:20 PM

spec: Clarify rtems_partition_create()

The rtems_partition_create() returns an object identifier and not just a
partition identifier.

  • Property mode set to 100644
File size: 6.1 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 assigned object identifier is returned in
25  ${.:/params[5]/name}.  This identifier is used to access the partition with
26  other partition related directives.
27
28  The **attribute set** specified in ${.:/params[4]/name} is built through
29  a *bitwise or* of the attribute constants described below.  Attributes not
30  mentioned below are not evaluated by this directive and have no effect.
31
32  The partition can have **local** or **global** scope in a multiprocessing
33  network (this attribute does not refer to SMP systems).
34
35  * A **local** scope is the default and can be emphasized through the use of
36    the ${../../attr/if/local:/name} attribute.  A local partition can be only
37    used by the node which created it.
38
39  * A **global** scope is established if the ${../../attr/if/global:/name}
40    attribute is set.  The memory space used for the partition must reside in
41    shared memory.  Setting the global attribute in a single node system has no
42    effect.
43enabled-by: true
44index-entries:
45- create a partition
46interface-type: function
47links:
48- role: interface-placement
49  uid: header
50- role: interface-ingroup
51  uid: group
52name: rtems_partition_create
53notes: |
54  This directive may cause the calling task to be preempted due to an obtain
55  and release of the object allocator mutex.
56
57  The partition buffer area specified by the ${.:/params[1]/name} must be
58  properly aligned.  It must be possible to directly store target architecture
59  pointers and also the user data.  For example, if the user data contains some
60  long double or vector data types, the partition buffer area and the buffer
61  size must take the alignment of these types into account which is usually
62  larger than the pointer alignment.  A cache line alignment may be also a
63  factor.  Use ${alignment:/name} to specify the minimum alignment of a
64  partition buffer type.
65
66  The ${.:/params[3]/name} parameter must be an integral multiple of the
67  pointer size on the target architecture.  Additionally,
68  ${.:/params[3]/name} must be large enough to hold two pointers on the
69  target architecture.  This is required for RTEMS to manage the buffers when
70  they are free.
71
72  For control and maintenance of the partition, RTEMS allocates a
73  ${/glossary/ptcb:/term} from the local PTCB free pool and initializes it.
74  Memory from the partition buffer area is not used by RTEMS to store the PTCB.
75
76  The PTCB for a global partition is allocated on the local node.  Partitions
77  should not be made global unless remote tasks must interact with the
78  partition.  This is to avoid the overhead incurred by the creation of a
79  global partition.  When a global partition is created, the partition's name
80  and identifier must be transmitted to every node in the system for insertion
81  in the local copy of the global object table.
82
83  The total number of global objects, including partitions, is limited by the
84  value of the ${/acfg/if/mp-max-global-objects:/name} application
85  configuration option.
86params:
87- description: is the name of the partition.
88  dir: null
89  name: name
90- description: is the starting address of the buffer area used by the partition.
91  dir: null
92  name: starting_address
93- description: is the length in bytes of the buffer area used by the partition.
94  dir: null
95  name: length
96- description: is the size in bytes of a buffer managed by the partition.
97  dir: null
98  name: buffer_size
99- description: is the attribute set of the partition.
100  dir: null
101  name: attribute_set
102- description: |
103    is the pointer to an object identifier variable.  The identifier of the
104    created partition object will be stored in this variable, in case of a
105    successful operation.
106  dir: out
107  name: id
108return:
109  return: null
110  return-values:
111  - description: |
112      The requested operation was successful.
113    value: ${../../status/if/successful:/name}
114  - description: |
115      The partition name was invalid.
116    value: ${../../status/if/invalid-name:/name}
117  - description: |
118      The ${.:/params[5]/name} parameter was ${/c/if/null:/name}.
119    value: ${../../status/if/invalid-address:/name}
120  - description: |
121      The ${.:/params[2]/name} parameter was 0.
122    value: ${../../status/if/invalid-size:/name}
123  - description: |
124      The ${.:/params[3]/name} parameter was 0.
125    value: ${../../status/if/invalid-size:/name}
126  - description: |
127      The ${.:/params[2]/name} parameter was less than the
128      ${.:/params[3]/name} parameter.
129    value: ${../../status/if/invalid-size:/name}
130  - description: |
131      The ${.:/params[3]/name} parameter was not an integral multiple of
132      the pointer size.
133    value: ${../../status/if/invalid-size:/name}
134  - description: |
135      The ${.:/params[3]/name} parameter was less than two times the
136      pointer size.
137    value: ${../../status/if/invalid-size:/name}
138  - description: |
139      The ${.:/params[1]/name} parameter was not on a pointer size
140      boundary.
141    value: ${../../status/if/invalid-address:/name}
142  - description: |
143      There was no inactive object available to create a new partition.  The
144      number of partitions available to the application is configured through
145      the ${/acfg/if/max-partitions:/name} configuration option.
146    value: ${../../status/if/too-many:/name}
147type: interface
Note: See TracBrowser for help on using the repository browser.