source: rtems-central/spec/rtems/region/if/create.yml @ 45b6997

Last change on this file since 45b6997 was 45b6997, checked in by Sebastian Huber <sebastian.huber@…>, on Jan 13, 2021 at 1:05:42 PM

spec: Document all create directives

  • Property mode set to 100644
File size: 4.9 KB
Line 
1SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
2brief: |
3  Creates a region.
4copyrights:
5- Copyright (C) 2021 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/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: []
20description: |
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.
53enabled-by: true
54index-entries:
55- create a region
56interface-type: function
57links:
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
72name: rtems_region_create
73notes: |
74  For control and maintenance of the region, RTEMS allocates a
75  ${/glossary/rncb:/term} from the local RNCB free pool and initializes it.
76params:
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
104return:
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}
131type: interface
Note: See TracBrowser for help on using the repository browser.