1 | SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause |
---|
2 | brief: | |
---|
3 | Creates a region. |
---|
4 | copyrights: |
---|
5 | - Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) |
---|
6 | - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) |
---|
7 | definition: |
---|
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/uintptr_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: [] |
---|
20 | description: | |
---|
21 | This directive creates a region which resides on the local node. The region |
---|
22 | has the user-defined object name specified in ${.:/params[0]/name}. The |
---|
23 | assigned object identifier is returned in ${.:/params[5]/name}. This |
---|
24 | identifier is used to access the region with other region related directives. |
---|
25 | |
---|
26 | The region manages the **contiguous memory area** which starts at |
---|
27 | ${.:/params[1]/name} and is ${.:/params[2]/name} bytes long. The memory area |
---|
28 | shall be large enough to contain some internal region administration data. |
---|
29 | |
---|
30 | The **starting address and length of segments** allocated from the region |
---|
31 | will be an integral multiple of ${.:/params[3]/name}. The specified page |
---|
32 | size will be aligned to an implementation-dependent minimum alignment if |
---|
33 | necessary. |
---|
34 | |
---|
35 | The **attribute set** specified in ${.:/params[4]/name} is built through a |
---|
36 | *bitwise or* of the attribute constants described below. Not all |
---|
37 | combinations of attributes are allowed. Some attributes are mutually |
---|
38 | exclusive. If mutually exclusive attributes are combined, the behaviour is |
---|
39 | undefined. Attributes not mentioned below are not evaluated by this |
---|
40 | directive and have no effect. Default attributes can be selected by using |
---|
41 | the ${../../attr/if/default:/name} constant. |
---|
42 | |
---|
43 | The **task wait queue discipline** is selected by the mutually exclusive |
---|
44 | ${../../attr/if/fifo:/name} and ${../../attr/if/priority:/name} attributes. |
---|
45 | The discipline defines the order in which tasks wait for allocatable segments |
---|
46 | on a currently empty region. |
---|
47 | |
---|
48 | * The **FIFO discipline** is the default and can be emphasized |
---|
49 | through use of the ${../../attr/if/fifo:/name} attribute. |
---|
50 | |
---|
51 | * The **priority discipline** is selected by the |
---|
52 | ${../../attr/if/priority:/name} attribute. |
---|
53 | enabled-by: true |
---|
54 | index-entries: |
---|
55 | - create a region |
---|
56 | interface-type: function |
---|
57 | links: |
---|
58 | - role: interface-placement |
---|
59 | uid: header |
---|
60 | - role: interface-ingroup |
---|
61 | uid: group |
---|
62 | - role: constraint |
---|
63 | uid: /constraint/directive-ctx-devinit |
---|
64 | - role: constraint |
---|
65 | uid: /constraint/directive-ctx-task |
---|
66 | - role: constraint |
---|
67 | uid: /constraint/object-allocator |
---|
68 | - role: constraint |
---|
69 | uid: ../constraint/max |
---|
70 | - role: constraint |
---|
71 | uid: /constraint/obj-unlimited-alloc |
---|
72 | name: rtems_region_create |
---|
73 | notes: | |
---|
74 | For control and maintenance of the region, RTEMS allocates a |
---|
75 | ${/glossary/rncb:/term} from the local RNCB free pool and initializes it. |
---|
76 | params: |
---|
77 | - description: | |
---|
78 | is the object name of the region. |
---|
79 | dir: null |
---|
80 | name: name |
---|
81 | - description: | |
---|
82 | is the starting address of the memory area managed by the region. |
---|
83 | dir: null |
---|
84 | name: starting_address |
---|
85 | - description: | |
---|
86 | is the length in bytes of the memory area managed by the region. |
---|
87 | dir: null |
---|
88 | name: length |
---|
89 | - description: | |
---|
90 | is the alignment of the starting address and length of each allocated |
---|
91 | segment of the region. |
---|
92 | dir: null |
---|
93 | name: page_size |
---|
94 | - description: | |
---|
95 | is the attribute set of the region. |
---|
96 | dir: null |
---|
97 | name: attribute_set |
---|
98 | - description: | |
---|
99 | is the pointer to an object identifier variable. The identifier of the |
---|
100 | created region will be stored in this variable, in case of a successful |
---|
101 | operation. |
---|
102 | dir: out |
---|
103 | name: id |
---|
104 | return: |
---|
105 | return: null |
---|
106 | return-values: |
---|
107 | - description: | |
---|
108 | The requested operation was successful. |
---|
109 | value: ${../../status/if/successful:/name} |
---|
110 | - description: | |
---|
111 | The ${.:/params[0]/name} parameter was invalid. |
---|
112 | value: ${../../status/if/invalid-name:/name} |
---|
113 | - description: | |
---|
114 | The ${.:/params[5]/name} parameter was ${/c/if/null:/name}. |
---|
115 | value: ${../../status/if/invalid-address:/name} |
---|
116 | - description: | |
---|
117 | The ${.:/params[1]/name} parameter was ${/c/if/null:/name}. |
---|
118 | value: ${../../status/if/invalid-address:/name} |
---|
119 | - description: | |
---|
120 | There was no inactive object available to create a region. The number |
---|
121 | of regions available to the application is configured through the |
---|
122 | ${/acfg/if/max-regions:/name} application configuration option. |
---|
123 | value: ${../../status/if/too-many:/name} |
---|
124 | - description: | |
---|
125 | The ${.:/params[3]/name} parameter was invalid. |
---|
126 | value: ${../../status/if/invalid-size:/name} |
---|
127 | - description: | |
---|
128 | The memory area specified in ${.:/params[1]/name} and |
---|
129 | ${.:/params[2]/name} was too small. |
---|
130 | value: ${../../status/if/invalid-size:/name} |
---|
131 | type: interface |
---|