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
|
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
Gets a segment from the 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/id:/name} ${.:/params[0]/name}
- ${/c/if/uintptr_t:/name} ${.:/params[1]/name}
- ${../../option/if/option:/name} ${.:/params[2]/name}
- ${../../type/if/interval:/name} ${.:/params[3]/name}
- void **${.:/params[4]/name}
return: ${../../status/if/code:/name}
variants: []
description: |
This directive gets a segment from the region specified by
${.:/params[0]/name}.
The **option set** specified in ${.:/params[2]/name} is built through a
*bitwise or* of the option constants described below. Not all combinations
of options are allowed. Some options are mutually exclusive. If mutually
exclusive options are combined, the behaviour is undefined. Options not
mentioned below are not evaluated by this directive and have no effect.
Default options can be selected by using the ${../../option/if/default:/name}
constant.
The calling task can **wait** or **try to get** a segment from the region
according to the mutually exclusive ${../../option/if/wait:/name} and
${../../option/if/no-wait:/name} options.
* **Waiting to get** a segment from the region is the default and can be
emphasized through the use of the ${../../option/if/wait:/name} option.
The ${.:/params[3]/name} parameter defines how long the calling task is
willing to wait. Use ${../../type/if/no-timeout:/name} to wait potentially
forever, otherwise set a timeout interval in clock ticks.
* **Trying to get** a segment from the region is selected by the
${../../option/if/no-wait:/name} option. If this option is defined, then
the ${.:/params[3]/name} parameter is ignored. When a segment from the
region cannot be immediately allocated, then the
${../../status/if/unsatisfied:/name} status is returned.
With either ${../../option/if/wait:/name} or ${../../option/if/no-wait:/name}
if there is a segment of the requested size is available, then it is returned
in ${.:/params[4]/name} and this directive returns immediately with the
${../../status/if/successful:/name} status code.
If the calling task chooses to return immediately and the region has no
segment of the requested size available, then the directive returns
immediately with the ${../../status/if/unsatisfied:/name} status code. If
the calling task chooses to wait for a segment, then the calling task is
placed on the region wait queue and blocked. If the region was created with
the ${../../attr/if/priority:/name} option specified, then the calling task
is inserted into the wait queue according to its priority. But, if the
region was created with the ${../../attr/if/fifo:/name} option specified,
then the calling task is placed at the rear of the wait queue.
enabled-by: true
index-entries:
- get segment from 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/request-may-block
- role: constraint
uid: /constraint/clock-tick
name: rtems_region_get_segment
notes: |
The actual length of the allocated segment may be larger than the requested
size because a segment size is always a multiple of the region's page size.
params:
- description: |
is the region identifier.
dir: null
name: id
- description: |
is the size in bytes of the segment to allocate.
dir: null
name: size
- description: |
is the option set.
dir: null
name: option_set
- description: |
is the timeout in ${/glossary/clock-tick:/plural} if the
${../../option/if/wait:/name} option is set. Use
${../../type/if/no-timeout:/name} to wait potentially forever.
dir: null
name: timeout
- description: |
is the pointer to a ``void`` pointer object. When the directive call is
successful, the begin address of the allocated segment will be stored in
this object.
dir: out
name: segment
return:
return: null
return-values:
- description: |
The requested operation was successful.
value: ${../../status/if/successful:/name}
- description: |
The ${.:/params[4]/name} parameter was ${/c/if/null:/name}.
value: ${../../status/if/invalid-address:/name}
- description: |
The ${.:/params[1]/name} parameter was zero.
value: ${../../status/if/invalid-size:/name}
- description: |
There was no region associated with the identifier specified by
${.:/params[0]/name}.
value: ${../../status/if/invalid-id:/name}
- description: |
The ${.:/params[1]/name} parameter exceeded the maximum segment size
which is possible for the region.
value: ${../../status/if/invalid-size:/name}
- description: |
The region had no segment of the requested size immediately available.
value: ${../../status/if/unsatisfied:/name}
- description: |
The timeout happened while the calling task was waiting to get a segment
from the region.
value: ${../../status/if/timeout:/name}
type: interface
|
