blob: 2a71937603bdf93d2e7eb3d6ca65efd8d1373997 (
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
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
|
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
Creates a message queue.
copyrights:
- Copyright (C) 2021 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}
- ${/c/if/uint32_t:/name} ${.:/params[1]/name}
- ${/c/if/size_t:/name} ${.:/params[2]/name}
- ${../../attr/if/attribute:/name} ${.:/params[3]/name}
- ${../../type/if/id:/name} *${.:/params[4]/name}
return: ${../../status/if/code:/name}
variants: []
description: |
This directive creates a message queue which resides on the local node. The
message queue has the user-defined object name specified in
${.:/params[0]/name}. Memory is allocated from the RTEMS Workspace for the
count of messages specified in ${.:/params[1]/name}, each of
${.:/params[2]/name} bytes in length. The assigned object identifier is
returned in ${.:/params[4]/name}. This identifier is used to access the
message queue with other message queue related directives.
The **attribute set** specified in ${.:/params[3]/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 attribute set defines
* the scope of the message queue: ${../../attr/if/local:/name} (default) or
${../../attr/if/global:/name} and
* the task wait queue discipline used by the message queue:
${../../attr/if/fifo:/name} (default) or ${../../attr/if/priority:/name}.
The message queue has a local or global **scope** in a multiprocessing network
(this attribute does not refer to SMP systems). The scope is selected by the
mutually exclusive ${../../attr/if/local:/name} and
${../../attr/if/global:/name} attributes.
* A **local scope** is the default and can be emphasized through the use of
the ${../../attr/if/local:/name} attribute. A local message queue can be
only used by the node which created it.
* A **global scope** is established if the ${../../attr/if/global:/name}
attribute is set. Setting the global attribute in a single node system has
no effect.
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 a message to receive
on a currently empty message queue.
* 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 message queue
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/mp-send
- role: constraint
uid: ../constraint/max
- role: constraint
uid: /constraint/obj-unlimited-alloc
- role: constraint
uid: ../../constraint/mp-max-global-objects
name: rtems_message_queue_create
notes: |
For message queues with a global scope, the maximum message size is
effectively limited to the longest message which the ${/glossary/mpci:/term}
is capable of transmitting.
For control and maintenance of the message queue, RTEMS allocates a
${/glossary/qcb:/term} from the local QCB free pool and initializes it.
The QCB for a global message queue is allocated on the local node. Message
queues should not be made global unless remote tasks must interact with the
message queue. This is to avoid the system overhead incurred by the creation
of a global message queue. When a global message queue is created, the
message queue's name and identifier must be transmitted to every node in the
system for insertion in the local copy of the global object table.
params:
- description: |
is the object name of the message queue.
dir: null
name: name
- description: |
is the maximum count of pending messages supported by the message queue.
dir: null
name: count
- description: |
is the maximum size in bytes of a message supported by the message queue.
dir: null
name: max_message_size
- description: |
is the attribute set of the message queue.
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 message queue 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[4]/name} parameter was ${/c/if/null:/name}.
value: ${../../status/if/invalid-address:/name}
- description: |
The ${.:/params[1]/name} parameter was invalid.
value: ${../../status/if/invalid-number:/name}
- description: |
The ${.:/params[2]/name} parameter was invalid.
value: ${../../status/if/invalid-size:/name}
- description: |
There was no inactive object available to create a message queue. The
number of message queue available to the application is configured
through the ${/acfg/if/max-message-queues:/name} application
configuration option.
value: ${../../status/if/too-many:/name}
- description: |
In multiprocessing configurations, there was no inactive global object
available to create a global message queue. The number of global objects
available to the application is configured through the
${/acfg/if/mp-max-global-objects:/name} application configuration option.
value: ${../../status/if/too-many:/name}
- description: |
The product of ${.:/params[1]/name} and ${.:/params[2]/name} is greater
than the maximum storage size.
value: ${../../status/if/invalid-number:/name}
- description: |
There was not enough memory available in the RTEMS Workspace to allocate
the message buffers for the message queue.
value: ${../../status/if/unsatisfied:/name}
type: interface
|
