source: rtems-central/spec/rtems/message/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: 6.6 KB
Line 
1SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
2brief: |
3  Creates a message queue.
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    - ${/c/if/uint32_t:/name} ${.:/params[1]/name}
14    - ${/c/if/size_t:/name} ${.:/params[2]/name}
15    - ${../../attr/if/attribute:/name} ${.:/params[3]/name}
16    - ${../../type/if/id:/name} *${.:/params[4]/name}
17    return: ${../../status/if/code:/name}
18  variants: []
19description: |
20  This directive creates a message queue which resides on the local node.  The
21  message queue has the user-defined object name specified in
22  ${.:/params[0]/name}.  Memory is allocated from the RTEMS Workspace for the
23  count of messages specified in ${.:/params[1]/name}, each of
24  ${.:/params[2]/name} bytes in length.  The assigned object identifier is
25  returned in ${.:/params[4]/name}.  This identifier is used to access the
26  message queue with other message queue related directives.
27
28  The **attribute set** specified in ${.:/params[3]/name} is built through a
29  *bitwise or* of the attribute constants described below.  Not all
30  combinations of attributes are allowed.  Some attributes are mutually
31  exclusive.  If mutually exclusive attributes are combined, the behaviour is
32  undefined.  Attributes not mentioned below are not evaluated by this
33  directive and have no effect.  Default attributes can be selected by using
34  the ${../../attr/if/default:/name} constant.  The attribute set defines
35
36  * the scope of the message queue: ${../../attr/if/local:/name} (default) or
37    ${../../attr/if/global:/name} and
38
39  * the task wait queue discipline used by the message queue:
40    ${../../attr/if/fifo:/name} (default) or ${../../attr/if/priority:/name}.
41
42  The message queue has a local or global **scope** in a multiprocessing network
43  (this attribute does not refer to SMP systems).  The scope is selected by the
44  mutually exclusive ${../../attr/if/local:/name} and
45  ${../../attr/if/global:/name} attributes.
46
47  * A **local scope** is the default and can be emphasized through the use of
48    the ${../../attr/if/local:/name} attribute.  A local message queue can be
49    only used by the node which created it.
50
51  * A **global scope** is established if the ${../../attr/if/global:/name}
52    attribute is set.  Setting the global attribute in a single node system has
53    no effect.
54
55  The **task wait queue discipline** is selected by the mutually exclusive
56  ${../../attr/if/fifo:/name} and ${../../attr/if/priority:/name} attributes.
57  The discipline defines the order in which tasks wait for a message to receive
58  on a currently empty message queue.
59
60  * The **FIFO discipline** is the default and can be emphasized
61    through use of the ${../../attr/if/fifo:/name} attribute.
62
63  * The **priority discipline** is selected by the
64    ${../../attr/if/priority:/name} attribute.
65enabled-by: true
66index-entries:
67- create a message queue
68interface-type: function
69links:
70- role: interface-placement
71  uid: header
72- role: interface-ingroup
73  uid: group
74- role: constraint
75  uid: /constraint/directive-ctx-devinit
76- role: constraint
77  uid: /constraint/directive-ctx-task
78- role: constraint
79  uid: /constraint/object-allocator
80- role: constraint
81  uid: ../constraint/max
82- role: constraint
83  uid: /constraint/obj-unlimited-alloc
84- role: constraint
85  uid: ../../constraint/mp-max-global-objects
86name: rtems_message_queue_create
87notes: |
88  For message queues with a global scope, the maximum message size is
89  effectively limited to the longest message which the ${/glossary/mpci:/term}
90  is capable of transmitting.
91
92  For control and maintenance of the message queue, RTEMS allocates a
93  ${/glossary/qcb:/term} from the local QCB free pool and initializes it.
94
95  The QCB for a global message queue is allocated on the local node.  Message
96  queues should not be made global unless remote tasks must interact with the
97  message queue.  This is to avoid the system overhead incurred by the creation
98  of a global message queue.  When a global message queue is created, the
99  message queue's name and identifier must be transmitted to every node in the
100  system for insertion in the local copy of the global object table.
101params:
102- description: |
103    is the object name of the message queue.
104  dir: null
105  name: name
106- description: |
107    is the maximum count of pending messages supported by the message queue.
108  dir: null
109  name: count
110- description: |
111    is the maximum size in bytes of a message supported by the message queue.
112  dir: null
113  name: max_message_size
114- description: |
115    is the attribute set of the message queue.
116  dir: null
117  name: attribute_set
118- description: |
119    is the pointer to an object identifier variable.  The identifier of the
120    created message queue will be stored in this variable, in case of a
121    successful operation.
122  dir: out
123  name: id
124return:
125  return: null
126  return-values:
127  - description: |
128      The requested operation was successful.
129    value: ${../../status/if/successful:/name}
130  - description: |
131      The ${.:/params[0]/name} parameter was invalid.
132    value: ${../../status/if/invalid-name:/name}
133  - description: |
134      The ${.:/params[4]/name} parameter was ${/c/if/null:/name}.
135    value: ${../../status/if/invalid-address:/name}
136  - description: |
137      The ${.:/params[1]/name} parameter was invalid.
138    value: ${../../status/if/invalid-number:/name}
139  - description: |
140      The ${.:/params[2]/name} parameter was invalid.
141    value: ${../../status/if/invalid-size:/name}
142  - description: |
143      There was no inactive object available to create a message queue.  The
144      number of message queue available to the application is configured
145      through the ${/acfg/if/max-message-queues:/name} application
146      configuration option.
147    value: ${../../status/if/too-many:/name}
148  - description: |
149      In multiprocessing configurations, there was no inactive global object
150      available to create a global message queue.  The number of global objects
151      available to the application is configured through the
152      ${/acfg/if/mp-max-global-objects:/name} application configuration option.
153    value: ${../../status/if/too-many:/name}
154  - description: |
155      The product of ${.:/params[1]/name} and ${.:/params[2]/name} is greater
156      than the maximum storage size.
157    value: ${../../status/if/invalid-number:/name}
158  - description: |
159      There was not enough memory available in the RTEMS Workspace to allocate
160      the message buffers for the message queue.
161    value: ${../../status/if/unsatisfied:/name}
162type: interface
Note: See TracBrowser for help on using the repository browser.