blob: 5a335b8830c717dd6b7f11ab87cd8bcc75bcfc2b (
plain) (
blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
|
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
Creates a partition.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
default:
attributes: null
body: null
params:
- ${../../type/if/name:/name} ${.:/params[0]/name}
- void *${.:/params[1]/name}
- ${/c/if/uintptr_t:/name} ${.:/params[2]/name}
- ${/c/if/size_t:/name} ${.:/params[3]/name}
- ${../../attr/if/attribute:/name} ${.:/params[4]/name}
- ${../../type/if/id:/name} *${.:/params[5]/name}
return: ${../../status/if/code:/name}
variants: []
description: |
This directive creates a partition of fixed size buffers from a physically
contiguous memory space which starts at ``${.:/params[1]/name}`` and is
``${.:/params[2]/name}`` bytes in size. Each allocated buffer is to be of
``${.:/params[3]/name}`` in bytes. The assigned partition identifier is
returned in ``${.:/params[5]/name}``. This partition identifier is used to
access the partition with other partition related directives.
The attribute set is built through a *bitwise or* of the attribute constants
described below. Attributes not mentioned below are not evaluated by this
directive and have no effect.
The partition can have **local** or **global** scope in a multiprocessing
network (this attribute does not refer to SMP systems).
* A **local** scope is the default and can be emphasized through the use of
the ${../../attr/if/local:/name} attribute. A local partition can be only
used by the node which created it.
* A **global** scope is established if the ${../../attr/if/global:/name}
attribute is set. The memory space used for the partition must reside in
shared memory. Setting the global attribute in a single node system has no
effect.
enabled-by: true
index-entries:
- create a partition
interface-type: function
links:
- role: interface-placement
uid: header
- role: interface-ingroup
uid: group
name: rtems_partition_create
notes: |
This directive may cause the calling task to be preempted due to an obtain
and release of the object allocator mutex.
The partition buffer area specified by the ``${.:/params[1]/name}`` must be
properly aligned. It must be possible to directly store target architecture
pointers and also the user data. For example, if the user data contains some
long double or vector data types, the partition buffer area and the buffer
size must take the alignment of these types into account which is usually
larger than the pointer alignment. A cache line alignment may be also a
factor. Use ${alignment:/name} to specify the minimum alignment of a
partition buffer type.
The ``${.:/params[3]/name}`` parameter must be an integral multiple of the
pointer size on the target architecture. Additionally,
``${.:/params[3]/name}`` must be large enough to hold two pointers on the
target architecture. This is required for RTEMS to manage the buffers when
they are free.
For control and maintenance of the partition, RTEMS allocates a
${/glossary/ptcb:/term} from the local PTCB free pool and initializes it.
Memory from the partition buffer area is not used by RTEMS to store the PTCB.
The PTCB for a global partition is allocated on the local node. Partitions
should not be made global unless remote tasks must interact with the
partition. This is to avoid the overhead incurred by the creation of a
global partition. When a global partition is created, the partition's name
and identifier must be transmitted to every node in the system for insertion
in the local copy of the global object table.
The total number of global objects, including partitions, is limited by the
value of the ${/acfg/if/mp-max-global-objects:/name} application
configuration option.
params:
- description: is the name of the partition.
dir: null
name: name
- description: is the starting address of the buffer area used by the partition.
dir: null
name: starting_address
- description: is the length in bytes of the buffer area used by the partition.
dir: null
name: length
- description: is the size in bytes of a buffer managed by the partition.
dir: null
name: buffer_size
- description: is the attribute set of the partition.
dir: null
name: attribute_set
- description: |
is the pointer to an object identifier variable. The identifier of the
created partition object will be stored in this variable, in case of a
successful operation.
dir: null
name: id
return:
return: null
return-values:
- description: |
The requested operation was successful.
value: ${../../status/if/successful:/name}
- description: |
The partition name was invalid.
value: ${../../status/if/invalid-name:/name}
- description: |
The ``${.:/params[5]/name}`` parameter was ${/c/if/null:/name}.
value: ${../../status/if/invalid-address:/name}
- description: |
The ``${.:/params[2]/name}`` parameter was 0.
value: ${../../status/if/invalid-size:/name}
- description: |
The ``${.:/params[3]/name}`` parameter was 0.
value: ${../../status/if/invalid-size:/name}
- description: |
The ``${.:/params[2]/name}`` parameter was less than the
``${.:/params[3]/name}`` parameter.
value: ${../../status/if/invalid-size:/name}
- description: |
The ``${.:/params[3]/name}`` parameter was not an integral multiple of
the pointer size.
value: ${../../status/if/invalid-size:/name}
- description: |
The ``${.:/params[3]/name}`` parameter was less than two times the
pointer size.
value: ${../../status/if/invalid-size:/name}
- description: |
The ``${.:/params[1]/name}`` parameter was not on a pointer size
boundary.
value: ${../../status/if/invalid-address:/name}
type: interface
|