[73a0175] | 1 | /* SPDX-License-Identifier: BSD-2-Clause */ |
---|
| 2 | |
---|
[4b487363] | 3 | /** |
---|
[257668d] | 4 | * @file |
---|
[067a96a] | 5 | * |
---|
[73a0175] | 6 | * @brief This header file defines the Message Manager API. |
---|
| 7 | */ |
---|
| 8 | |
---|
| 9 | /* |
---|
| 10 | * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) |
---|
| 11 | * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) |
---|
| 12 | * |
---|
| 13 | * Redistribution and use in source and binary forms, with or without |
---|
| 14 | * modification, are permitted provided that the following conditions |
---|
| 15 | * are met: |
---|
| 16 | * 1. Redistributions of source code must retain the above copyright |
---|
| 17 | * notice, this list of conditions and the following disclaimer. |
---|
| 18 | * 2. Redistributions in binary form must reproduce the above copyright |
---|
| 19 | * notice, this list of conditions and the following disclaimer in the |
---|
| 20 | * documentation and/or other materials provided with the distribution. |
---|
| 21 | * |
---|
| 22 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" |
---|
| 23 | * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
---|
| 24 | * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
---|
| 25 | * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE |
---|
| 26 | * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
---|
| 27 | * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
---|
| 28 | * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
---|
| 29 | * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
---|
| 30 | * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
---|
| 31 | * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
---|
| 32 | * POSSIBILITY OF SUCH DAMAGE. |
---|
[067a96a] | 33 | */ |
---|
| 34 | |
---|
[73a0175] | 35 | /* |
---|
| 36 | * This file is part of the RTEMS quality process and was automatically |
---|
| 37 | * generated. If you find something that needs to be fixed or |
---|
| 38 | * worded better please post a report or patch to an RTEMS mailing list |
---|
| 39 | * or raise a bug report: |
---|
[ac7d5ef0] | 40 | * |
---|
[73a0175] | 41 | * https://www.rtems.org/bugs.html |
---|
| 42 | * |
---|
| 43 | * For information on updating and regenerating please refer to the How-To |
---|
| 44 | * section in the Software Requirements Engineering chapter of the |
---|
| 45 | * RTEMS Software Engineering manual. The manual is provided as a part of |
---|
| 46 | * a release. For development sources please refer to the online |
---|
| 47 | * documentation at: |
---|
| 48 | * |
---|
| 49 | * https://docs.rtems.org |
---|
[ac7d5ef0] | 50 | */ |
---|
| 51 | |
---|
[73a0175] | 52 | /* Generated from spec:/rtems/message/if/header */ |
---|
| 53 | |
---|
[092f142a] | 54 | #ifndef _RTEMS_RTEMS_MESSAGE_H |
---|
| 55 | #define _RTEMS_RTEMS_MESSAGE_H |
---|
[ac7d5ef0] | 56 | |
---|
[73a0175] | 57 | #include <stddef.h> |
---|
| 58 | #include <stdint.h> |
---|
[3a4ae6c] | 59 | #include <rtems/rtems/attr.h> |
---|
[257668d] | 60 | #include <rtems/rtems/options.h> |
---|
| 61 | #include <rtems/rtems/status.h> |
---|
| 62 | #include <rtems/rtems/types.h> |
---|
[4a4f41e] | 63 | #include <rtems/score/coremsgbuffer.h> |
---|
[ac7d5ef0] | 64 | |
---|
[993a888] | 65 | #ifdef __cplusplus |
---|
| 66 | extern "C" { |
---|
| 67 | #endif |
---|
[ac7d5ef0] | 68 | |
---|
[73a0175] | 69 | /* Generated from spec:/rtems/message/if/group */ |
---|
| 70 | |
---|
[f9293df] | 71 | /** |
---|
[73a0175] | 72 | * @defgroup RTEMSAPIClassicMessage Message Manager |
---|
[993a888] | 73 | * |
---|
[73a0175] | 74 | * @ingroup RTEMSAPIClassic |
---|
[ac7d5ef0] | 75 | * |
---|
[73a0175] | 76 | * @brief The Message Manager provides communication and synchronization |
---|
| 77 | * capabilities using RTEMS message queues. |
---|
[ac7d5ef0] | 78 | */ |
---|
[73a0175] | 79 | |
---|
| 80 | /* Generated from spec:/rtems/message/if/config */ |
---|
[ac7d5ef0] | 81 | |
---|
[4a4f41e] | 82 | /** |
---|
[73a0175] | 83 | * @ingroup RTEMSAPIClassicMessage |
---|
| 84 | * |
---|
[4a4f41e] | 85 | * @brief This structure defines the configuration of a message queue |
---|
| 86 | * constructed by rtems_message_queue_construct(). |
---|
| 87 | */ |
---|
| 88 | typedef struct { |
---|
| 89 | /** |
---|
| 90 | * @brief This member defines the name of the message queue. |
---|
| 91 | */ |
---|
| 92 | rtems_name name; |
---|
| 93 | |
---|
| 94 | /** |
---|
| 95 | * @brief This member defines the maximum number of pending messages supported |
---|
| 96 | * by the message queue. |
---|
| 97 | */ |
---|
| 98 | uint32_t maximum_pending_messages; |
---|
| 99 | |
---|
| 100 | /** |
---|
| 101 | * @brief This member defines the maximum message size supported by the message |
---|
| 102 | * queue. |
---|
| 103 | */ |
---|
| 104 | size_t maximum_message_size; |
---|
| 105 | |
---|
| 106 | /** |
---|
| 107 | * @brief This member shall point to the message buffer storage area begin. |
---|
| 108 | * |
---|
| 109 | * The message buffer storage area for the message queue shall be an array of |
---|
| 110 | * the type defined by RTEMS_MESSAGE_QUEUE_BUFFER() with a maximum message size |
---|
| 111 | * equal to the maximum message size of this configuration. |
---|
| 112 | */ |
---|
| 113 | void *storage_area; |
---|
| 114 | |
---|
| 115 | /** |
---|
| 116 | * @brief This member defines size of the message buffer storage area in bytes. |
---|
| 117 | */ |
---|
| 118 | size_t storage_size; |
---|
| 119 | |
---|
| 120 | /** |
---|
| 121 | * @brief This member defines the optional handler to free the message buffer |
---|
| 122 | * storage area. |
---|
| 123 | * |
---|
| 124 | * It is called when the message queue is deleted. It is called from task |
---|
| 125 | * context under protection of the object allocator lock. It is allowed to |
---|
| 126 | * call free() in this handler. If handler is NULL, then no action will be |
---|
| 127 | * performed. |
---|
| 128 | */ |
---|
| 129 | void ( *storage_free )( void * ); |
---|
| 130 | |
---|
| 131 | /** |
---|
| 132 | * @brief This member defines the attributes of the message queue. |
---|
| 133 | */ |
---|
| 134 | rtems_attribute attributes; |
---|
| 135 | } rtems_message_queue_config; |
---|
| 136 | |
---|
[73a0175] | 137 | /* Generated from spec:/rtems/message/if/create */ |
---|
| 138 | |
---|
[4a4f41e] | 139 | /** |
---|
[73a0175] | 140 | * @ingroup RTEMSAPIClassicMessage |
---|
[4a4f41e] | 141 | * |
---|
[73a0175] | 142 | * @brief Creates a message queue. |
---|
[4a4f41e] | 143 | * |
---|
[73a0175] | 144 | * @param name is the object name of the message queue. |
---|
| 145 | * |
---|
| 146 | * @param count is the maximum count of pending messages supported by the |
---|
| 147 | * message queue. |
---|
| 148 | * |
---|
| 149 | * @param max_message_size is the maximum size in bytes of a message supported |
---|
| 150 | * by the message queue. |
---|
| 151 | * |
---|
| 152 | * @param attribute_set is the attribute set of the message queue. |
---|
| 153 | * |
---|
| 154 | * @param[out] id is the pointer to an object identifier variable. When the |
---|
| 155 | * directive call is successful, the identifier of the created message queue |
---|
| 156 | * will be stored in this variable. |
---|
| 157 | * |
---|
| 158 | * This directive creates a message queue which resides on the local node. The |
---|
| 159 | * message queue has the user-defined object name specified in ``name``. |
---|
| 160 | * Memory is allocated from the RTEMS Workspace for the count of messages |
---|
| 161 | * specified in ``count``, each of ``max_message_size`` bytes in length. The |
---|
| 162 | * assigned object identifier is returned in ``id``. This identifier is used |
---|
| 163 | * to access the message queue with other message queue related directives. |
---|
| 164 | * |
---|
| 165 | * The **attribute set** specified in ``attribute_set`` is built through a |
---|
| 166 | * *bitwise or* of the attribute constants described below. Not all |
---|
| 167 | * combinations of attributes are allowed. Some attributes are mutually |
---|
| 168 | * exclusive. If mutually exclusive attributes are combined, the behaviour is |
---|
| 169 | * undefined. Attributes not mentioned below are not evaluated by this |
---|
| 170 | * directive and have no effect. Default attributes can be selected by using |
---|
| 171 | * the #RTEMS_DEFAULT_ATTRIBUTES constant. The attribute set defines |
---|
| 172 | * |
---|
| 173 | * * the scope of the message queue: #RTEMS_LOCAL (default) or #RTEMS_GLOBAL |
---|
| 174 | * and |
---|
| 175 | * |
---|
| 176 | * * the task wait queue discipline used by the message queue: #RTEMS_FIFO |
---|
| 177 | * (default) or #RTEMS_PRIORITY. |
---|
| 178 | * |
---|
| 179 | * The message queue has a local or global **scope** in a multiprocessing |
---|
| 180 | * network (this attribute does not refer to SMP systems). The scope is |
---|
| 181 | * selected by the mutually exclusive #RTEMS_LOCAL and #RTEMS_GLOBAL |
---|
| 182 | * attributes. |
---|
| 183 | * |
---|
| 184 | * * A **local scope** is the default and can be emphasized through the use of |
---|
| 185 | * the #RTEMS_LOCAL attribute. A local message queue can be only used by the |
---|
| 186 | * node which created it. |
---|
| 187 | * |
---|
| 188 | * * A **global scope** is established if the #RTEMS_GLOBAL attribute is set. |
---|
| 189 | * Setting the global attribute in a single node system has no effect. |
---|
| 190 | * |
---|
| 191 | * The **task wait queue discipline** is selected by the mutually exclusive |
---|
| 192 | * #RTEMS_FIFO and #RTEMS_PRIORITY attributes. The discipline defines the order |
---|
| 193 | * in which tasks wait for a message to receive on a currently empty message |
---|
| 194 | * queue. |
---|
| 195 | * |
---|
| 196 | * * The **FIFO discipline** is the default and can be emphasized through use |
---|
| 197 | * of the #RTEMS_FIFO attribute. |
---|
| 198 | * |
---|
| 199 | * * The **priority discipline** is selected by the #RTEMS_PRIORITY attribute. |
---|
| 200 | * |
---|
| 201 | * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. |
---|
| 202 | * |
---|
| 203 | * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was invalid. |
---|
| 204 | * |
---|
| 205 | * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. |
---|
| 206 | * |
---|
| 207 | * @retval ::RTEMS_INVALID_NUMBER The ``count`` parameter was invalid. |
---|
| 208 | * |
---|
| 209 | * @retval ::RTEMS_INVALID_SIZE The ``max_message_size`` parameter was invalid. |
---|
| 210 | * |
---|
| 211 | * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a |
---|
| 212 | * message queue. The number of message queue available to the application |
---|
| 213 | * is configured through the #CONFIGURE_MAXIMUM_MESSAGE_QUEUES application |
---|
| 214 | * configuration option. |
---|
| 215 | * |
---|
| 216 | * @retval ::RTEMS_TOO_MANY In multiprocessing configurations, there was no |
---|
| 217 | * inactive global object available to create a global message queue. The |
---|
| 218 | * number of global objects available to the application is configured |
---|
| 219 | * through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration |
---|
| 220 | * option. |
---|
| 221 | * |
---|
| 222 | * @retval ::RTEMS_INVALID_NUMBER The product of ``count`` and |
---|
| 223 | * ``max_message_size`` is greater than the maximum storage size. |
---|
| 224 | * |
---|
| 225 | * @retval ::RTEMS_UNSATISFIED There was not enough memory available in the |
---|
| 226 | * RTEMS Workspace to allocate the message buffers for the message queue. |
---|
| 227 | * |
---|
| 228 | * @par Notes |
---|
| 229 | * @parblock |
---|
| 230 | * For message queues with a global scope, the maximum message size is |
---|
| 231 | * effectively limited to the longest message which the MPCI is capable of |
---|
| 232 | * transmitting. |
---|
| 233 | * |
---|
| 234 | * For control and maintenance of the message queue, RTEMS allocates a QCB from |
---|
| 235 | * the local QCB free pool and initializes it. |
---|
| 236 | * |
---|
| 237 | * The QCB for a global message queue is allocated on the local node. Message |
---|
| 238 | * queues should not be made global unless remote tasks must interact with the |
---|
| 239 | * message queue. This is to avoid the system overhead incurred by the |
---|
| 240 | * creation of a global message queue. When a global message queue is created, |
---|
| 241 | * the message queue's name and identifier must be transmitted to every node in |
---|
| 242 | * the system for insertion in the local copy of the global object table. |
---|
| 243 | * @endparblock |
---|
| 244 | * |
---|
| 245 | * @par Constraints |
---|
| 246 | * @parblock |
---|
| 247 | * The following constraints apply to this directive: |
---|
| 248 | * |
---|
| 249 | * * The directive may be called from within device driver initialization |
---|
| 250 | * context. |
---|
| 251 | * |
---|
| 252 | * * The directive may be called from within task context. |
---|
| 253 | * |
---|
| 254 | * * The directive may obtain and release the object allocator mutex. This may |
---|
| 255 | * cause the calling task to be preempted. |
---|
| 256 | * |
---|
| 257 | * * When the directive operates on a global object, the directive sends a |
---|
| 258 | * message to remote nodes. This may preempt the calling task. |
---|
| 259 | * |
---|
| 260 | * * The number of message queues available to the application is configured |
---|
| 261 | * through the #CONFIGURE_MAXIMUM_MESSAGE_QUEUES application configuration |
---|
| 262 | * option. |
---|
| 263 | * |
---|
| 264 | * * Where the object class corresponding to the directive is configured to use |
---|
| 265 | * unlimited objects, the directive may allocate memory from the RTEMS |
---|
| 266 | * Workspace. |
---|
| 267 | * |
---|
| 268 | * * The number of global objects available to the application is configured |
---|
| 269 | * through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration |
---|
| 270 | * option. |
---|
| 271 | * @endparblock |
---|
[4a4f41e] | 272 | */ |
---|
[73a0175] | 273 | rtems_status_code rtems_message_queue_create( |
---|
| 274 | rtems_name name, |
---|
| 275 | uint32_t count, |
---|
| 276 | size_t max_message_size, |
---|
| 277 | rtems_attribute attribute_set, |
---|
| 278 | rtems_id *id |
---|
| 279 | ); |
---|
| 280 | |
---|
| 281 | /* Generated from spec:/rtems/message/if/construct */ |
---|
[4a4f41e] | 282 | |
---|
| 283 | /** |
---|
[73a0175] | 284 | * @ingroup RTEMSAPIClassicMessage |
---|
| 285 | * |
---|
[4a4f41e] | 286 | * @brief Constructs a message queue from the specified the message queue |
---|
| 287 | * configuration. |
---|
| 288 | * |
---|
| 289 | * @param config is the message queue configuration. |
---|
| 290 | * |
---|
[73a0175] | 291 | * @param[out] id is the pointer to an object identifier variable. When the |
---|
| 292 | * directive call is successful, the identifier of the constructed message |
---|
| 293 | * queue will be stored in this variable. |
---|
[4a4f41e] | 294 | * |
---|
| 295 | * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. |
---|
| 296 | * |
---|
[73a0175] | 297 | * @retval ::RTEMS_INVALID_ADDRESS The ``config`` parameter was NULL. |
---|
[4a4f41e] | 298 | * |
---|
| 299 | * @retval ::RTEMS_INVALID_NAME The message queue name in the configuration was |
---|
| 300 | * invalid. |
---|
| 301 | * |
---|
[73a0175] | 302 | * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. |
---|
| 303 | * |
---|
[4a4f41e] | 304 | * @retval ::RTEMS_INVALID_NUMBER The maximum number of pending messages in the |
---|
| 305 | * configuration was zero. |
---|
| 306 | * |
---|
| 307 | * @retval ::RTEMS_INVALID_SIZE The maximum message size in the configuration |
---|
| 308 | * was zero. |
---|
| 309 | * |
---|
| 310 | * @retval ::RTEMS_TOO_MANY There was no inactive message queue object |
---|
| 311 | * available to construct a message queue. |
---|
| 312 | * |
---|
| 313 | * @retval ::RTEMS_TOO_MANY In multiprocessing configurations, there was no |
---|
| 314 | * inactive global object available to construct a global message queue. |
---|
| 315 | * |
---|
| 316 | * @retval ::RTEMS_INVALID_SIZE The maximum message size in the configuration |
---|
| 317 | * was too big and resulted in integer overflows in calculations carried out |
---|
| 318 | * to determine the size of the message buffer area. |
---|
| 319 | * |
---|
| 320 | * @retval ::RTEMS_INVALID_NUMBER The maximum number of pending messages in the |
---|
| 321 | * configuration was too big and resulted in integer overflows in |
---|
| 322 | * calculations carried out to determine the size of the message buffer area. |
---|
| 323 | * |
---|
| 324 | * @retval ::RTEMS_UNSATISFIED The message queue storage area begin pointer in |
---|
| 325 | * the configuration was NULL. |
---|
| 326 | * |
---|
| 327 | * @retval ::RTEMS_UNSATISFIED The message queue storage area size in the |
---|
| 328 | * configuration was not equal to the size calculated from the maximum number |
---|
| 329 | * of pending messages and the maximum message size. |
---|
[73a0175] | 330 | * |
---|
| 331 | * @par Notes |
---|
| 332 | * @parblock |
---|
| 333 | * In contrast to message queues created by rtems_message_queue_create(), the |
---|
| 334 | * message queues constructed by this directive use a user-provided message |
---|
| 335 | * buffer storage area. |
---|
| 336 | * |
---|
| 337 | * This directive is intended for applications which do not want to use the |
---|
| 338 | * RTEMS Workspace and instead statically allocate all operating system |
---|
| 339 | * resources. An application based solely on static allocation can avoid any |
---|
| 340 | * runtime memory allocators. This can simplify the application architecture |
---|
| 341 | * as well as any analysis that may be required. |
---|
| 342 | * |
---|
| 343 | * The value for #CONFIGURE_MESSAGE_BUFFER_MEMORY should not include memory for |
---|
| 344 | * message queues constructed by rtems_message_queue_construct(). |
---|
| 345 | * @endparblock |
---|
| 346 | * |
---|
| 347 | * @par Constraints |
---|
| 348 | * @parblock |
---|
| 349 | * The following constraints apply to this directive: |
---|
| 350 | * |
---|
| 351 | * * The directive may be called from within device driver initialization |
---|
| 352 | * context. |
---|
| 353 | * |
---|
| 354 | * * The directive may be called from within task context. |
---|
| 355 | * |
---|
| 356 | * * The directive may obtain and release the object allocator mutex. This may |
---|
| 357 | * cause the calling task to be preempted. |
---|
| 358 | * |
---|
| 359 | * * When the directive operates on a global object, the directive sends a |
---|
| 360 | * message to remote nodes. This may preempt the calling task. |
---|
| 361 | * |
---|
| 362 | * * The number of message queues available to the application is configured |
---|
| 363 | * through the #CONFIGURE_MAXIMUM_MESSAGE_QUEUES application configuration |
---|
| 364 | * option. |
---|
| 365 | * |
---|
| 366 | * * Where the object class corresponding to the directive is configured to use |
---|
| 367 | * unlimited objects, the directive may allocate memory from the RTEMS |
---|
| 368 | * Workspace. |
---|
| 369 | * |
---|
| 370 | * * The number of global objects available to the application is configured |
---|
| 371 | * through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration |
---|
| 372 | * option. |
---|
| 373 | * @endparblock |
---|
[4a4f41e] | 374 | */ |
---|
| 375 | rtems_status_code rtems_message_queue_construct( |
---|
| 376 | const rtems_message_queue_config *config, |
---|
| 377 | rtems_id *id |
---|
| 378 | ); |
---|
| 379 | |
---|
[73a0175] | 380 | /* Generated from spec:/rtems/message/if/ident */ |
---|
[ac7d5ef0] | 381 | |
---|
[067a96a] | 382 | /** |
---|
[73a0175] | 383 | * @ingroup RTEMSAPIClassicMessage |
---|
| 384 | * |
---|
| 385 | * @brief Identifies a message queue by the object name. |
---|
| 386 | * |
---|
| 387 | * @param name is the object name to look up. |
---|
| 388 | * |
---|
| 389 | * @param node is the node or node set to search for a matching object. |
---|
| 390 | * |
---|
| 391 | * @param[out] id is the pointer to an object identifier variable. When the |
---|
| 392 | * directive call is successful, the object identifier of an object with the |
---|
| 393 | * specified name will be stored in this variable. |
---|
| 394 | * |
---|
| 395 | * This directive obtains a message queue identifier associated with the |
---|
| 396 | * message queue name specified in ``name``. |
---|
| 397 | * |
---|
| 398 | * The node to search is specified in ``node``. It shall be |
---|
| 399 | * |
---|
| 400 | * * a valid node number, |
---|
| 401 | * |
---|
| 402 | * * the constant #RTEMS_SEARCH_ALL_NODES to search in all nodes, |
---|
| 403 | * |
---|
| 404 | * * the constant #RTEMS_SEARCH_LOCAL_NODE to search in the local node only, or |
---|
| 405 | * |
---|
| 406 | * * the constant #RTEMS_SEARCH_OTHER_NODES to search in all nodes except the |
---|
| 407 | * local node. |
---|
| 408 | * |
---|
| 409 | * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. |
---|
| 410 | * |
---|
| 411 | * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. |
---|
| 412 | * |
---|
| 413 | * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was 0. |
---|
| 414 | * |
---|
| 415 | * @retval ::RTEMS_INVALID_NAME There was no object with the specified name on |
---|
| 416 | * the specified nodes. |
---|
| 417 | * |
---|
| 418 | * @retval ::RTEMS_INVALID_NODE In multiprocessing configurations, the |
---|
| 419 | * specified node was invalid. |
---|
| 420 | * |
---|
| 421 | * @par Notes |
---|
| 422 | * @parblock |
---|
| 423 | * If the message queue name is not unique, then the message queue identifier |
---|
| 424 | * will match the first message queue with that name in the search order. |
---|
| 425 | * However, this message queue identifier is not guaranteed to correspond to |
---|
| 426 | * the desired message queue. |
---|
| 427 | * |
---|
| 428 | * The objects are searched from lowest to the highest index. If ``node`` is |
---|
| 429 | * #RTEMS_SEARCH_ALL_NODES, all nodes are searched with the local node being |
---|
| 430 | * searched first. All other nodes are searched from lowest to the highest |
---|
| 431 | * node number. |
---|
| 432 | * |
---|
| 433 | * If node is a valid node number which does not represent the local node, then |
---|
| 434 | * only the message queues exported by the designated node are searched. |
---|
| 435 | * |
---|
| 436 | * This directive does not generate activity on remote nodes. It accesses only |
---|
| 437 | * the local copy of the global object table. |
---|
| 438 | * |
---|
| 439 | * The message queue identifier is used with other message related directives |
---|
| 440 | * to access the message queue. |
---|
| 441 | * @endparblock |
---|
| 442 | * |
---|
| 443 | * @par Constraints |
---|
| 444 | * @parblock |
---|
| 445 | * The following constraints apply to this directive: |
---|
| 446 | * |
---|
| 447 | * * The directive may be called from within any runtime context. |
---|
| 448 | * |
---|
| 449 | * * The directive will not cause the calling task to be preempted. |
---|
| 450 | * @endparblock |
---|
[ac7d5ef0] | 451 | */ |
---|
| 452 | rtems_status_code rtems_message_queue_ident( |
---|
[73a0175] | 453 | rtems_name name, |
---|
| 454 | uint32_t node, |
---|
| 455 | rtems_id *id |
---|
[ac7d5ef0] | 456 | ); |
---|
| 457 | |
---|
[73a0175] | 458 | /* Generated from spec:/rtems/message/if/delete */ |
---|
| 459 | |
---|
[067a96a] | 460 | /** |
---|
[73a0175] | 461 | * @ingroup RTEMSAPIClassicMessage |
---|
[ac7d5ef0] | 462 | * |
---|
[73a0175] | 463 | * @brief Deletes the message queue. |
---|
[4efe1955] | 464 | * |
---|
[73a0175] | 465 | * @param id is the message queue identifier. |
---|
[4efe1955] | 466 | * |
---|
[73a0175] | 467 | * This directive deletes the message queue specified by ``id``. As a result of |
---|
| 468 | * this directive, all tasks blocked waiting to receive a message from this |
---|
| 469 | * queue will be readied and returned a status code which indicates that the |
---|
| 470 | * message queue was deleted. |
---|
| 471 | * |
---|
| 472 | * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. |
---|
| 473 | * |
---|
| 474 | * @retval ::RTEMS_INVALID_ID There was no message queue associated with the |
---|
| 475 | * identifier specified by ``id``. |
---|
| 476 | * |
---|
| 477 | * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The message queue resided on a |
---|
| 478 | * remote node. |
---|
| 479 | * |
---|
| 480 | * @par Notes |
---|
| 481 | * @parblock |
---|
| 482 | * When the message queue is deleted, any messages in the queue are returned to |
---|
| 483 | * the free message buffer pool. Any information stored in those messages is |
---|
| 484 | * lost. The message buffers allocated for the message queue are reclaimed. |
---|
| 485 | * |
---|
| 486 | * The QCB for the deleted message queue is reclaimed by RTEMS. |
---|
| 487 | * |
---|
| 488 | * When a global message queue is deleted, the message queue identifier must be |
---|
| 489 | * transmitted to every node in the system for deletion from the local copy of |
---|
| 490 | * the global object table. |
---|
| 491 | * |
---|
| 492 | * The message queue must reside on the local node, even if the message queue |
---|
| 493 | * was created with the #RTEMS_GLOBAL attribute. |
---|
| 494 | * |
---|
| 495 | * Proxies, used to represent remote tasks, are reclaimed when the message |
---|
| 496 | * queue is deleted. |
---|
| 497 | * @endparblock |
---|
| 498 | * |
---|
| 499 | * @par Constraints |
---|
| 500 | * @parblock |
---|
| 501 | * The following constraints apply to this directive: |
---|
| 502 | * |
---|
| 503 | * * The directive may be called from within device driver initialization |
---|
| 504 | * context. |
---|
| 505 | * |
---|
| 506 | * * The directive may be called from within task context. |
---|
| 507 | * |
---|
| 508 | * * The directive may obtain and release the object allocator mutex. This may |
---|
| 509 | * cause the calling task to be preempted. |
---|
| 510 | * |
---|
| 511 | * * When the directive operates on a global object, the directive sends a |
---|
| 512 | * message to remote nodes. This may preempt the calling task. |
---|
| 513 | * |
---|
| 514 | * * The calling task does not have to be the task that created the object. |
---|
| 515 | * Any local task that knows the object identifier can delete the object. |
---|
| 516 | * |
---|
| 517 | * * Where the object class corresponding to the directive is configured to use |
---|
| 518 | * unlimited objects, the directive may free memory to the RTEMS Workspace. |
---|
| 519 | * @endparblock |
---|
[ac7d5ef0] | 520 | */ |
---|
[73a0175] | 521 | rtems_status_code rtems_message_queue_delete( rtems_id id ); |
---|
| 522 | |
---|
| 523 | /* Generated from spec:/rtems/message/if/send */ |
---|
[ac7d5ef0] | 524 | |
---|
[067a96a] | 525 | /** |
---|
[73a0175] | 526 | * @ingroup RTEMSAPIClassicMessage |
---|
| 527 | * |
---|
| 528 | * @brief Puts the message at the rear of the queue. |
---|
| 529 | * |
---|
| 530 | * @param id is the queue identifier. |
---|
| 531 | * |
---|
| 532 | * @param buffer is the begin address of the message buffer to send. |
---|
| 533 | * |
---|
| 534 | * @param size is the size in bytes of the message buffer to send. |
---|
| 535 | * |
---|
| 536 | * This directive sends the message ``buffer`` of ``size`` bytes in length to |
---|
| 537 | * the queue specified by ``id``. If a task is waiting at the queue, then the |
---|
| 538 | * message is copied to the waiting task's buffer and the task is unblocked. If |
---|
| 539 | * no tasks are waiting at the queue, then the message is copied to a message |
---|
| 540 | * buffer which is obtained from this message queue's message buffer pool. The |
---|
| 541 | * message buffer is then placed at the rear of the queue. |
---|
| 542 | * |
---|
| 543 | * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. |
---|
| 544 | * |
---|
| 545 | * @retval ::RTEMS_INVALID_ID There was no queue associated with the identifier |
---|
| 546 | * specified by ``id``. |
---|
| 547 | * |
---|
| 548 | * @retval ::RTEMS_INVALID_ADDRESS The ``buffer`` parameter was NULL. |
---|
| 549 | * |
---|
| 550 | * @retval ::RTEMS_INVALID_SIZE The size of the message exceeded the maximum |
---|
| 551 | * message size of the queue as defined by rtems_message_queue_create() or |
---|
| 552 | * rtems_message_queue_construct(). |
---|
| 553 | * |
---|
| 554 | * @retval ::RTEMS_TOO_MANY The maximum number of pending messages supported by |
---|
| 555 | * the queue as defined by rtems_message_queue_create() or |
---|
| 556 | * rtems_message_queue_construct() has been reached. |
---|
| 557 | * |
---|
| 558 | * @par Constraints |
---|
| 559 | * @parblock |
---|
| 560 | * The following constraints apply to this directive: |
---|
| 561 | * |
---|
| 562 | * * The directive may be called from within task context. |
---|
| 563 | * |
---|
| 564 | * * The directive may be called from within interrupt context. |
---|
| 565 | * |
---|
[55c6cb1d] | 566 | * * The directive may unblock a task. This may cause the calling task to be |
---|
| 567 | * preempted. |
---|
[73a0175] | 568 | * |
---|
| 569 | * * When the directive operates on a remote object, the directive sends a |
---|
| 570 | * message to the remote node and waits for a reply. This will preempt the |
---|
| 571 | * calling task. |
---|
| 572 | * @endparblock |
---|
[ac7d5ef0] | 573 | */ |
---|
| 574 | rtems_status_code rtems_message_queue_send( |
---|
[d3b72ca3] | 575 | rtems_id id, |
---|
| 576 | const void *buffer, |
---|
| 577 | size_t size |
---|
[ac7d5ef0] | 578 | ); |
---|
| 579 | |
---|
[73a0175] | 580 | /* Generated from spec:/rtems/message/if/urgent */ |
---|
| 581 | |
---|
[067a96a] | 582 | /** |
---|
[73a0175] | 583 | * @ingroup RTEMSAPIClassicMessage |
---|
| 584 | * |
---|
| 585 | * @brief Puts the message at the front of the queue. |
---|
| 586 | * |
---|
| 587 | * @param id is the queue identifier. |
---|
| 588 | * |
---|
| 589 | * @param buffer is the begin address of the message buffer to send urgently. |
---|
| 590 | * |
---|
| 591 | * @param size is the size in bytes of the message buffer to send urgently. |
---|
| 592 | * |
---|
| 593 | * This directive sends the message ``buffer`` of ``size`` bytes in length to |
---|
| 594 | * the queue specified by ``id``. If a task is waiting at the queue, then the |
---|
| 595 | * message is copied to the waiting task's buffer and the task is unblocked. If |
---|
| 596 | * no tasks are waiting at the queue, then the message is copied to a message |
---|
| 597 | * buffer which is obtained from this message queue's message buffer pool. The |
---|
| 598 | * message buffer is then placed at the front of the queue. |
---|
| 599 | * |
---|
| 600 | * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. |
---|
| 601 | * |
---|
| 602 | * @retval ::RTEMS_INVALID_ID There was no queue associated with the identifier |
---|
| 603 | * specified by ``id``. |
---|
| 604 | * |
---|
| 605 | * @retval ::RTEMS_INVALID_ADDRESS The ``buffer`` parameter was NULL. |
---|
| 606 | * |
---|
| 607 | * @retval ::RTEMS_INVALID_SIZE The size of the message exceeded the maximum |
---|
| 608 | * message size of the queue as defined by rtems_message_queue_create() or |
---|
| 609 | * rtems_message_queue_construct(). |
---|
| 610 | * |
---|
| 611 | * @retval ::RTEMS_TOO_MANY The maximum number of pending messages supported by |
---|
| 612 | * the queue as defined by rtems_message_queue_create() or |
---|
| 613 | * rtems_message_queue_construct() has been reached. |
---|
| 614 | * |
---|
| 615 | * @par Constraints |
---|
| 616 | * @parblock |
---|
| 617 | * The following constraints apply to this directive: |
---|
[ac7d5ef0] | 618 | * |
---|
[73a0175] | 619 | * * The directive may be called from within task context. |
---|
[4efe1955] | 620 | * |
---|
[73a0175] | 621 | * * The directive may be called from within interrupt context. |
---|
[4efe1955] | 622 | * |
---|
[55c6cb1d] | 623 | * * The directive may unblock a task. This may cause the calling task to be |
---|
| 624 | * preempted. |
---|
[73a0175] | 625 | * |
---|
| 626 | * * When the directive operates on a remote object, the directive sends a |
---|
| 627 | * message to the remote node and waits for a reply. This will preempt the |
---|
| 628 | * calling task. |
---|
| 629 | * @endparblock |
---|
[ac7d5ef0] | 630 | */ |
---|
| 631 | rtems_status_code rtems_message_queue_urgent( |
---|
[d3b72ca3] | 632 | rtems_id id, |
---|
| 633 | const void *buffer, |
---|
| 634 | size_t size |
---|
[ac7d5ef0] | 635 | ); |
---|
| 636 | |
---|
[73a0175] | 637 | /* Generated from spec:/rtems/message/if/broadcast */ |
---|
| 638 | |
---|
[067a96a] | 639 | /** |
---|
[73a0175] | 640 | * @ingroup RTEMSAPIClassicMessage |
---|
| 641 | * |
---|
| 642 | * @brief Broadcasts the messages to the tasks waiting at the queue. |
---|
| 643 | * |
---|
| 644 | * @param id is the queue identifier. |
---|
| 645 | * |
---|
| 646 | * @param buffer is the begin address of the message buffer to broadcast. |
---|
| 647 | * |
---|
| 648 | * @param size is the size in bytes of the message buffer to broadcast. |
---|
| 649 | * |
---|
| 650 | * @param[out] count is the pointer to an uint32_t variable. When the |
---|
| 651 | * directive call is successful, the number of unblocked tasks will be stored |
---|
| 652 | * in this variable. |
---|
| 653 | * |
---|
| 654 | * This directive causes all tasks that are waiting at the queue specified by |
---|
| 655 | * ``id`` to be unblocked and sent the message contained in ``buffer``. Before |
---|
| 656 | * a task is unblocked, the message ``buffer`` of ``size`` byes in length is |
---|
| 657 | * copied to that task's message buffer. The number of tasks that were |
---|
| 658 | * unblocked is returned in ``count``. |
---|
| 659 | * |
---|
| 660 | * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. |
---|
| 661 | * |
---|
| 662 | * @retval ::RTEMS_INVALID_ID There was no queue associated with the identifier |
---|
| 663 | * specified by ``id``. |
---|
| 664 | * |
---|
| 665 | * @retval ::RTEMS_INVALID_ADDRESS The ``buffer`` parameter was NULL. |
---|
| 666 | * |
---|
| 667 | * @retval ::RTEMS_INVALID_ADDRESS The ``count`` parameter was NULL. |
---|
| 668 | * |
---|
| 669 | * @retval ::RTEMS_INVALID_SIZE The size of the message exceeded the maximum |
---|
| 670 | * message size of the queue as defined by rtems_message_queue_create() or |
---|
| 671 | * rtems_message_queue_construct(). |
---|
| 672 | * |
---|
| 673 | * @par Notes |
---|
| 674 | * The execution time of this directive is directly related to the number of |
---|
| 675 | * tasks waiting on the message queue, although it is more efficient than the |
---|
| 676 | * equivalent number of invocations of rtems_message_queue_send(). |
---|
[ac7d5ef0] | 677 | * |
---|
[73a0175] | 678 | * @par Constraints |
---|
| 679 | * @parblock |
---|
| 680 | * The following constraints apply to this directive: |
---|
[4efe1955] | 681 | * |
---|
[73a0175] | 682 | * * The directive may be called from within task context. |
---|
[4efe1955] | 683 | * |
---|
[73a0175] | 684 | * * The directive may be called from within interrupt context. |
---|
| 685 | * |
---|
[55c6cb1d] | 686 | * * The directive may unblock a task. This may cause the calling task to be |
---|
| 687 | * preempted. |
---|
[73a0175] | 688 | * |
---|
| 689 | * * When the directive operates on a remote object, the directive sends a |
---|
| 690 | * message to the remote node and waits for a reply. This will preempt the |
---|
| 691 | * calling task. |
---|
| 692 | * @endparblock |
---|
[ac7d5ef0] | 693 | */ |
---|
| 694 | rtems_status_code rtems_message_queue_broadcast( |
---|
[d3b72ca3] | 695 | rtems_id id, |
---|
| 696 | const void *buffer, |
---|
| 697 | size_t size, |
---|
| 698 | uint32_t *count |
---|
[ac7d5ef0] | 699 | ); |
---|
| 700 | |
---|
[73a0175] | 701 | /* Generated from spec:/rtems/message/if/receive */ |
---|
| 702 | |
---|
[067a96a] | 703 | /** |
---|
[73a0175] | 704 | * @ingroup RTEMSAPIClassicMessage |
---|
| 705 | * |
---|
| 706 | * @brief Receives a message from the queue. |
---|
| 707 | * |
---|
| 708 | * @param id is the queue identifier. |
---|
| 709 | * |
---|
| 710 | * @param buffer is the begin address of the buffer to receive the message. |
---|
| 711 | * The buffer shall be large enough to receive a message of the maximum |
---|
| 712 | * length of the queue as defined by rtems_message_queue_create() or |
---|
| 713 | * rtems_message_queue_construct(). The ``size`` parameter cannot be used to |
---|
| 714 | * specify the size of the buffer. |
---|
| 715 | * |
---|
| 716 | * @param size is the pointer to a size_t variable. When the directive call is |
---|
| 717 | * successful, the size in bytes of the received messages will be stored in |
---|
| 718 | * this variable. This parameter cannot be used to specify the size of the |
---|
| 719 | * buffer. |
---|
| 720 | * |
---|
| 721 | * @param option_set is the option set. |
---|
| 722 | * |
---|
| 723 | * @param timeout is the timeout in clock ticks if the #RTEMS_WAIT option is |
---|
| 724 | * set. Use #RTEMS_NO_TIMEOUT to wait potentially forever. |
---|
| 725 | * |
---|
| 726 | * This directive receives a message from the queue specified by ``id``. |
---|
| 727 | * |
---|
| 728 | * The **option set** specified in ``option_set`` is built through a *bitwise |
---|
| 729 | * or* of the option constants described below. Not all combinations of |
---|
| 730 | * options are allowed. Some options are mutually exclusive. If mutually |
---|
| 731 | * exclusive options are combined, the behaviour is undefined. Options not |
---|
| 732 | * mentioned below are not evaluated by this directive and have no effect. |
---|
| 733 | * Default options can be selected by using the #RTEMS_DEFAULT_OPTIONS |
---|
| 734 | * constant. |
---|
| 735 | * |
---|
| 736 | * The calling task can **wait** or **try to receive** a message from the queue |
---|
| 737 | * according to the mutually exclusive #RTEMS_WAIT and #RTEMS_NO_WAIT options. |
---|
| 738 | * |
---|
| 739 | * * **Waiting to receive** a message from the queue is the default and can be |
---|
| 740 | * emphasized through the use of the #RTEMS_WAIT option. The ``timeout`` |
---|
| 741 | * parameter defines how long the calling task is willing to wait. Use |
---|
| 742 | * #RTEMS_NO_TIMEOUT to wait potentially forever, otherwise set a timeout |
---|
| 743 | * interval in clock ticks. |
---|
| 744 | * |
---|
| 745 | * * **Trying to receive** a message from the queue is selected by the |
---|
| 746 | * #RTEMS_NO_WAIT option. If this option is defined, then the ``timeout`` |
---|
| 747 | * parameter is ignored. When a message from the queue cannot be immediately |
---|
| 748 | * received, then the ::RTEMS_UNSATISFIED status is returned. |
---|
| 749 | * |
---|
| 750 | * With either #RTEMS_WAIT or #RTEMS_NO_WAIT if there is at least one message |
---|
| 751 | * in the queue, then it is copied to the buffer, the size is set to return the |
---|
| 752 | * length of the message in bytes, and this directive returns immediately with |
---|
| 753 | * the ::RTEMS_SUCCESSFUL status code. The buffer has to be big enough to |
---|
| 754 | * receive a message of the maximum length with respect to this message queue. |
---|
| 755 | * |
---|
| 756 | * If the calling task chooses to return immediately and the queue is empty, |
---|
| 757 | * then the directive returns immediately with the ::RTEMS_UNSATISFIED status |
---|
[278c7daa] | 758 | * code. If the calling task chooses to wait at the message queue and the |
---|
| 759 | * queue is empty, then the calling task is placed on the message wait queue |
---|
| 760 | * and blocked. If the queue was created with the #RTEMS_PRIORITY option |
---|
[73a0175] | 761 | * specified, then the calling task is inserted into the wait queue according |
---|
| 762 | * to its priority. But, if the queue was created with the #RTEMS_FIFO option |
---|
| 763 | * specified, then the calling task is placed at the rear of the wait queue. |
---|
| 764 | * |
---|
| 765 | * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. |
---|
| 766 | * |
---|
| 767 | * @retval ::RTEMS_INVALID_ID There was no queue associated with the identifier |
---|
| 768 | * specified by ``id``. |
---|
| 769 | * |
---|
| 770 | * @retval ::RTEMS_INVALID_ADDRESS The ``buffer`` parameter was NULL. |
---|
| 771 | * |
---|
| 772 | * @retval ::RTEMS_INVALID_ADDRESS The ``size`` parameter was NULL. |
---|
| 773 | * |
---|
| 774 | * @retval ::RTEMS_UNSATISFIED The queue was empty. |
---|
| 775 | * |
---|
| 776 | * @retval ::RTEMS_UNSATISFIED The queue was flushed while the calling task was |
---|
| 777 | * waiting to receive a message. |
---|
| 778 | * |
---|
| 779 | * @retval ::RTEMS_TIMEOUT The timeout happened while the calling task was |
---|
| 780 | * waiting to receive a message |
---|
| 781 | * |
---|
| 782 | * @retval ::RTEMS_OBJECT_WAS_DELETED The queue was deleted while the calling |
---|
| 783 | * task was waiting to receive a message. |
---|
| 784 | * |
---|
| 785 | * @par Constraints |
---|
| 786 | * @parblock |
---|
| 787 | * The following constraints apply to this directive: |
---|
| 788 | * |
---|
| 789 | * * When a local queue is accessed and the #RTEMS_NO_WAIT option is set, the |
---|
| 790 | * directive may be called from within interrupt context. |
---|
| 791 | * |
---|
| 792 | * * The directive may be called from within task context. |
---|
| 793 | * |
---|
| 794 | * * When the request cannot be immediately satisfied and the #RTEMS_WAIT |
---|
| 795 | * option is set, the calling task blocks at some point during the directive |
---|
| 796 | * call. |
---|
| 797 | * |
---|
| 798 | * * The timeout functionality of the directive requires a clock tick. |
---|
| 799 | * |
---|
| 800 | * * When the directive operates on a remote object, the directive sends a |
---|
| 801 | * message to the remote node and waits for a reply. This will preempt the |
---|
| 802 | * calling task. |
---|
| 803 | * @endparblock |
---|
[ac7d5ef0] | 804 | */ |
---|
| 805 | rtems_status_code rtems_message_queue_receive( |
---|
[73a0175] | 806 | rtems_id id, |
---|
| 807 | void *buffer, |
---|
| 808 | size_t *size, |
---|
| 809 | rtems_option option_set, |
---|
| 810 | rtems_interval timeout |
---|
[ac7d5ef0] | 811 | ); |
---|
| 812 | |
---|
[73a0175] | 813 | /* Generated from spec:/rtems/message/if/get-number-pending */ |
---|
| 814 | |
---|
[067a96a] | 815 | /** |
---|
[73a0175] | 816 | * @ingroup RTEMSAPIClassicMessage |
---|
| 817 | * |
---|
| 818 | * @brief Gets the number of messages pending on the queue. |
---|
[ac7d5ef0] | 819 | * |
---|
[73a0175] | 820 | * @param id is the queue identifier. |
---|
| 821 | * |
---|
| 822 | * @param[out] count is the pointer to an uint32_t variable. When the |
---|
| 823 | * directive call is successful, the number of pending messages will be |
---|
| 824 | * stored in this variable. |
---|
| 825 | * |
---|
| 826 | * This directive returns the number of messages pending on the queue specified |
---|
| 827 | * by ``id`` in ``count``. If no messages are present on the queue, count is |
---|
| 828 | * set to zero. |
---|
| 829 | * |
---|
| 830 | * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. |
---|
[4efe1955] | 831 | * |
---|
[73a0175] | 832 | * @retval ::RTEMS_INVALID_ID There was no queue associated with the identifier |
---|
| 833 | * specified by ``id``. |
---|
| 834 | * |
---|
| 835 | * @retval ::RTEMS_INVALID_ADDRESS The ``count`` parameter was NULL. |
---|
| 836 | * |
---|
| 837 | * @par Constraints |
---|
| 838 | * @parblock |
---|
| 839 | * The following constraints apply to this directive: |
---|
| 840 | * |
---|
| 841 | * * The directive may be called from within task context. |
---|
| 842 | * |
---|
| 843 | * * The directive may be called from within interrupt context. |
---|
| 844 | * |
---|
| 845 | * * When the directive operates on a remote object, the directive sends a |
---|
| 846 | * message to the remote node and waits for a reply. This will preempt the |
---|
| 847 | * calling task. |
---|
| 848 | * @endparblock |
---|
[ac7d5ef0] | 849 | */ |
---|
[73a0175] | 850 | rtems_status_code rtems_message_queue_get_number_pending( |
---|
[d3b72ca3] | 851 | rtems_id id, |
---|
| 852 | uint32_t *count |
---|
[ac7d5ef0] | 853 | ); |
---|
| 854 | |
---|
[73a0175] | 855 | /* Generated from spec:/rtems/message/if/flush */ |
---|
| 856 | |
---|
[067a96a] | 857 | /** |
---|
[73a0175] | 858 | * @ingroup RTEMSAPIClassicMessage |
---|
[4c90eb4] | 859 | * |
---|
[73a0175] | 860 | * @brief Flushes all messages on the queue. |
---|
[e7d8b58] | 861 | * |
---|
[73a0175] | 862 | * @param id is the queue identifier. |
---|
| 863 | * |
---|
| 864 | * @param[out] count is the pointer to an uint32_t variable. When the |
---|
| 865 | * directive call is successful, the number of unblocked tasks will be stored |
---|
| 866 | * in this variable. |
---|
| 867 | * |
---|
| 868 | * This directive removes all pending messages from the queue specified by |
---|
| 869 | * ``id``. The number of messages removed is returned in ``count``. If no |
---|
| 870 | * messages are present on the queue, count is set to zero. |
---|
| 871 | * |
---|
| 872 | * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. |
---|
| 873 | * |
---|
| 874 | * @retval ::RTEMS_INVALID_ID There was no queue associated with the identifier |
---|
| 875 | * specified by ``id``. |
---|
| 876 | * |
---|
| 877 | * @retval ::RTEMS_INVALID_ADDRESS The ``count`` parameter was NULL. |
---|
| 878 | * |
---|
| 879 | * @par Constraints |
---|
| 880 | * @parblock |
---|
| 881 | * The following constraints apply to this directive: |
---|
| 882 | * |
---|
| 883 | * * The directive may be called from within task context. |
---|
| 884 | * |
---|
| 885 | * * The directive may be called from within interrupt context. |
---|
| 886 | * |
---|
| 887 | * * When the directive operates on a remote object, the directive sends a |
---|
| 888 | * message to the remote node and waits for a reply. This will preempt the |
---|
| 889 | * calling task. |
---|
| 890 | * @endparblock |
---|
[e7d8b58] | 891 | */ |
---|
[73a0175] | 892 | rtems_status_code rtems_message_queue_flush( rtems_id id, uint32_t *count ); |
---|
[e7d8b58] | 893 | |
---|
[73a0175] | 894 | /* Generated from spec:/rtems/message/if/buffer */ |
---|
| 895 | |
---|
| 896 | /** |
---|
| 897 | * @ingroup RTEMSAPIClassicMessage |
---|
| 898 | * |
---|
| 899 | * @brief Defines a structure which can be used as a message queue buffer for |
---|
| 900 | * messages of the specified maximum size. |
---|
| 901 | * |
---|
| 902 | * @param _maximum_message_size is the maximum message size in bytes. |
---|
| 903 | * |
---|
| 904 | * @par Notes |
---|
| 905 | * Use this macro to define the message buffer storage area for |
---|
| 906 | * rtems_message_queue_construct(). |
---|
| 907 | */ |
---|
| 908 | #define RTEMS_MESSAGE_QUEUE_BUFFER( _maximum_message_size ) \ |
---|
| 909 | struct { \ |
---|
| 910 | CORE_message_queue_Buffer _buffer; \ |
---|
| 911 | char _message[ _maximum_message_size ]; \ |
---|
| 912 | } |
---|
[ac7d5ef0] | 913 | |
---|
| 914 | #ifdef __cplusplus |
---|
| 915 | } |
---|
| 916 | #endif |
---|
| 917 | |
---|
[73a0175] | 918 | #endif /* _RTEMS_RTEMS_MESSAGE_H */ |
---|