source: rtems/cpukit/include/rtems/rtems/message.h @ 6abdd89

Last change on this file since 6abdd89 was 6abdd89, checked in by Sebastian Huber <sebastian.huber@…>, on Jun 14, 2021 at 7:57:51 AM

Use a common phrase for pointer parameters

Mention the type of the pointer in the parameter description. Use the
more general term "object" instead of "variable".

Update #3993.

  • Property mode set to 100644
File size: 33.5 KB
Line 
1/* SPDX-License-Identifier: BSD-2-Clause */
2
3/**
4 * @file
5 *
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.
33 */
34
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:
40 *
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
50 */
51
52/* Generated from spec:/rtems/message/if/header */
53
54#ifndef _RTEMS_RTEMS_MESSAGE_H
55#define _RTEMS_RTEMS_MESSAGE_H
56
57#include <stddef.h>
58#include <stdint.h>
59#include <rtems/rtems/attr.h>
60#include <rtems/rtems/options.h>
61#include <rtems/rtems/status.h>
62#include <rtems/rtems/types.h>
63#include <rtems/score/coremsgbuffer.h>
64
65#ifdef __cplusplus
66extern "C" {
67#endif
68
69/* Generated from spec:/rtems/message/if/group */
70
71/**
72 * @defgroup RTEMSAPIClassicMessage Message Manager
73 *
74 * @ingroup RTEMSAPIClassic
75 *
76 * @brief The Message Manager provides communication and synchronization
77 *   capabilities using RTEMS message queues.
78 */
79
80/* Generated from spec:/rtems/message/if/config */
81
82/**
83 * @ingroup RTEMSAPIClassicMessage
84 *
85 * @brief This structure defines the configuration of a message queue
86 *   constructed by rtems_message_queue_construct().
87 */
88typedef 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
137/* Generated from spec:/rtems/message/if/create */
138
139/**
140 * @ingroup RTEMSAPIClassicMessage
141 *
142 * @brief Creates a message queue.
143 *
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 ::rtems_id object.  When the directive
155 *   call is successful, the identifier of the created message queue will be
156 *   stored in this object.
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
272 */
273rtems_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 */
282
283/**
284 * @ingroup RTEMSAPIClassicMessage
285 *
286 * @brief Constructs a message queue from the specified the message queue
287 *   configuration.
288 *
289 * @param config is the message queue configuration.
290 *
291 * @param[out] id is the pointer to an ::rtems_id object.  When the directive
292 *   call is successful, the identifier of the constructed message queue will
293 *   be stored in this object.
294 *
295 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
296 *
297 * @retval ::RTEMS_INVALID_ADDRESS The ``config`` parameter was NULL.
298 *
299 * @retval ::RTEMS_INVALID_NAME The message queue name in the configuration was
300 *   invalid.
301 *
302 * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
303 *
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.
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
374 */
375rtems_status_code rtems_message_queue_construct(
376  const rtems_message_queue_config *config,
377  rtems_id                         *id
378);
379
380/* Generated from spec:/rtems/message/if/ident */
381
382/**
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 ::rtems_id object.  When the directive
392 *   call is successful, the object identifier of an object with the specified
393 *   name will be stored in this object.
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
451 */
452rtems_status_code rtems_message_queue_ident(
453  rtems_name name,
454  uint32_t   node,
455  rtems_id  *id
456);
457
458/* Generated from spec:/rtems/message/if/delete */
459
460/**
461 * @ingroup RTEMSAPIClassicMessage
462 *
463 * @brief Deletes the message queue.
464 *
465 * @param id is the message queue identifier.
466 *
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
520 */
521rtems_status_code rtems_message_queue_delete( rtems_id id );
522
523/* Generated from spec:/rtems/message/if/send */
524
525/**
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 *
566 * * The directive may unblock a task.  This may cause the calling task to be
567 *   preempted.
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
573 */
574rtems_status_code rtems_message_queue_send(
575  rtems_id    id,
576  const void *buffer,
577  size_t      size
578);
579
580/* Generated from spec:/rtems/message/if/urgent */
581
582/**
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:
618 *
619 * * The directive may be called from within task context.
620 *
621 * * The directive may be called from within interrupt context.
622 *
623 * * The directive may unblock a task.  This may cause the calling task to be
624 *   preempted.
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
630 */
631rtems_status_code rtems_message_queue_urgent(
632  rtems_id    id,
633  const void *buffer,
634  size_t      size
635);
636
637/* Generated from spec:/rtems/message/if/broadcast */
638
639/**
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 object.  When the directive
651 *   call is successful, the number of unblocked tasks will be stored in this
652 *   object.
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().
677 *
678 * @par Constraints
679 * @parblock
680 * The following constraints apply to this directive:
681 *
682 * * The directive may be called from within task context.
683 *
684 * * The directive may be called from within interrupt context.
685 *
686 * * The directive may unblock a task.  This may cause the calling task to be
687 *   preempted.
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
693 */
694rtems_status_code rtems_message_queue_broadcast(
695  rtems_id    id,
696  const void *buffer,
697  size_t      size,
698  uint32_t   *count
699);
700
701/* Generated from spec:/rtems/message/if/receive */
702
703/**
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[out] size is the pointer to a size_t object.  When the directive call
717 *   is successful, the size in bytes of the received messages will be stored
718 *   in this object.  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
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
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
804 */
805rtems_status_code rtems_message_queue_receive(
806  rtems_id       id,
807  void          *buffer,
808  size_t        *size,
809  rtems_option   option_set,
810  rtems_interval timeout
811);
812
813/* Generated from spec:/rtems/message/if/get-number-pending */
814
815/**
816 * @ingroup RTEMSAPIClassicMessage
817 *
818 * @brief Gets the number of messages pending on the queue.
819 *
820 * @param id is the queue identifier.
821 *
822 * @param[out] count is the pointer to an uint32_t object.  When the directive
823 *   call is successful, the number of pending messages will be stored in this
824 *   object.
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.
831 *
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
849 */
850rtems_status_code rtems_message_queue_get_number_pending(
851  rtems_id  id,
852  uint32_t *count
853);
854
855/* Generated from spec:/rtems/message/if/flush */
856
857/**
858 * @ingroup RTEMSAPIClassicMessage
859 *
860 * @brief Flushes all messages on the queue.
861 *
862 * @param id is the queue identifier.
863 *
864 * @param[out] count is the pointer to an uint32_t object.  When the directive
865 *   call is successful, the number of unblocked tasks will be stored in this
866 *   object.
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
891 */
892rtems_status_code rtems_message_queue_flush( rtems_id id, uint32_t *count );
893
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  }
913
914#ifdef __cplusplus
915}
916#endif
917
918#endif /* _RTEMS_RTEMS_MESSAGE_H */
Note: See TracBrowser for help on using the repository browser.