[af77e87] | 1 | SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause |
---|
[45b6997] | 2 | brief: | |
---|
| 3 | Creates a message queue. |
---|
[af77e87] | 4 | copyrights: |
---|
[45b6997] | 5 | - Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) |
---|
[af77e87] | 6 | - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) |
---|
| 7 | definition: |
---|
| 8 | default: |
---|
[d3edaca] | 9 | attributes: null |
---|
[af77e87] | 10 | body: null |
---|
| 11 | params: |
---|
[3bdf817] | 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} |
---|
[af77e87] | 18 | variants: [] |
---|
[45b6997] | 19 | description: | |
---|
| 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. |
---|
[af77e87] | 65 | enabled-by: true |
---|
[45b6997] | 66 | index-entries: |
---|
| 67 | - create a message queue |
---|
[af77e87] | 68 | interface-type: function |
---|
| 69 | links: |
---|
| 70 | - role: interface-placement |
---|
| 71 | uid: header |
---|
| 72 | - role: interface-ingroup |
---|
[cead53e] | 73 | uid: group |
---|
[45b6997] | 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 |
---|
[af77e87] | 86 | name: rtems_message_queue_create |
---|
[45b6997] | 87 | notes: | |
---|
| 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. |
---|
[af77e87] | 101 | params: |
---|
[45b6997] | 102 | - description: | |
---|
| 103 | is the object name of the message queue. |
---|
[af77e87] | 104 | dir: null |
---|
| 105 | name: name |
---|
[45b6997] | 106 | - description: | |
---|
| 107 | is the maximum count of pending messages supported by the message queue. |
---|
[af77e87] | 108 | dir: null |
---|
| 109 | name: count |
---|
[45b6997] | 110 | - description: | |
---|
| 111 | is the maximum size in bytes of a message supported by the message queue. |
---|
[af77e87] | 112 | dir: null |
---|
| 113 | name: max_message_size |
---|
[45b6997] | 114 | - description: | |
---|
| 115 | is the attribute set of the message queue. |
---|
[af77e87] | 116 | dir: null |
---|
| 117 | name: attribute_set |
---|
[45b6997] | 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 |
---|
[af77e87] | 123 | name: id |
---|
| 124 | return: |
---|
| 125 | return: null |
---|
[45b6997] | 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} |
---|
[af77e87] | 162 | type: interface |
---|