blob: e6d91149ed00003441307c93c032738046033aee (
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
|
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
Creates a region.
copyrights:
- Copyright (C) 2021 embedded brains GmbH & Co. KG
- 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/uintptr_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 region which resides on the local node. The region
has the user-defined object name specified in ${.:/params[0]/name}. The
assigned object identifier is returned in ${.:/params[5]/name}. This
identifier is used to access the region with other region related directives.
The region manages the **contiguous memory area** which starts at
${.:/params[1]/name} and is ${.:/params[2]/name} bytes long. The memory area
shall be large enough to contain some internal region administration data.
The **starting address** and **length of segments** allocated from the region
will be an integral multiple of ${.:/params[3]/name}. The specified page
size will be aligned to an implementation-dependent minimum alignment if
necessary.
The **attribute set** specified in ${.:/params[4]/name} is built through a
*bitwise or* of the attribute constants described below. Not all
combinations of attributes are allowed. Some attributes are mutually
exclusive. If mutually exclusive attributes are combined, the behaviour is
undefined. Attributes not mentioned below are not evaluated by this
directive and have no effect. Default attributes can be selected by using
the ${../../attr/if/default:/name} constant.
The **task wait queue discipline** is selected by the mutually exclusive
${../../attr/if/fifo:/name} and ${../../attr/if/priority:/name} attributes.
The discipline defines the order in which tasks wait for allocatable segments
on a currently empty region.
* The **FIFO discipline** is the default and can be emphasized
through use of the ${../../attr/if/fifo:/name} attribute.
* The **priority discipline** is selected by the
${../../attr/if/priority:/name} attribute.
enabled-by: true
index-entries:
- create a region
interface-type: function
links:
- role: interface-placement
uid: header
- role: interface-ingroup
uid: group
- role: constraint
uid: /constraint/directive-not-pre-qualified
- role: constraint
uid: /constraint/directive-ctx-devinit
- role: constraint
uid: /constraint/directive-ctx-task
- role: constraint
uid: /constraint/object-allocator
- role: constraint
uid: ../constraint/max
- role: constraint
uid: /constraint/obj-unlimited-alloc
name: rtems_region_create
notes: |
For control and maintenance of the region, RTEMS allocates a
${/glossary/rncb:/term} from the local RNCB free pool and initializes it.
params:
- description: |
is the object name of the region.
dir: null
name: name
- description: |
is the starting address of the memory area managed by the region.
dir: null
name: starting_address
- description: |
is the length in bytes of the memory area managed by the region.
dir: null
name: length
- description: |
is the alignment of the starting address and length of each allocated
segment of the region.
dir: null
name: page_size
- description: |
is the attribute set of the region.
dir: null
name: attribute_set
- description: |
is the pointer to an ${../../type/if/id:/name} object. When the directive
call is successful, the identifier of the created region will be stored in
this object.
dir: out
name: id
return:
return: null
return-values:
- description: |
The requested operation was successful.
value: ${../../status/if/successful:/name}
- description: |
The ${.:/params[0]/name} parameter 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[1]/name} parameter was ${/c/if/null:/name}.
value: ${../../status/if/invalid-address:/name}
- description: |
There was no inactive object available to create a region. The number
of regions available to the application is configured through the
${/acfg/if/max-regions:/name} application configuration option.
value: ${../../status/if/too-many:/name}
- description: |
The ${.:/params[3]/name} parameter was invalid.
value: ${../../status/if/invalid-size:/name}
- description: |
The memory area specified in ${.:/params[1]/name} and
${.:/params[2]/name} was too small.
value: ${../../status/if/invalid-size:/name}
type: interface
|
