diff options
Diffstat (limited to 'cpukit/include/rtems/rtems/message.h')
| -rw-r--r-- | cpukit/include/rtems/rtems/message.h | 97 |
1 files changed, 51 insertions, 46 deletions
diff --git a/cpukit/include/rtems/rtems/message.h b/cpukit/include/rtems/rtems/message.h index 747daf4e1b..0967430934 100644 --- a/cpukit/include/rtems/rtems/message.h +++ b/cpukit/include/rtems/rtems/message.h @@ -3,11 +3,13 @@ /** * @file * + * @ingroup RTEMSImplClassicMessage + * * @brief This header file defines the Message Manager API. */ /* - * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -151,9 +153,9 @@ typedef struct { * * @param attribute_set is the attribute set of the message queue. * - * @param[out] id is the pointer to an object identifier variable. When the - * directive call is successful, the identifier of the created message queue - * will be stored in this variable. + * @param[out] id is the pointer to an ::rtems_id object. When the directive + * call is successful, the identifier of the created message queue will be + * stored in this object. * * This directive creates a message queue which resides on the local node. The * message queue has the user-defined object name specified in ``name``. @@ -210,14 +212,14 @@ typedef struct { * * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a * message queue. The number of message queue available to the application - * is configured through the #CONFIGURE_MAXIMUM_MESSAGE_QUEUES application - * configuration option. + * is configured through the @ref CONFIGURE_MAXIMUM_MESSAGE_QUEUES + * application configuration option. * * @retval ::RTEMS_TOO_MANY In multiprocessing configurations, there was no * inactive global object available to create a global message queue. The * number of global objects available to the application is configured - * through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration - * option. + * through the @ref CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application + * configuration option. * * @retval ::RTEMS_INVALID_NUMBER The product of ``count`` and * ``max_message_size`` is greater than the maximum storage size. @@ -258,16 +260,16 @@ typedef struct { * message to remote nodes. This may preempt the calling task. * * * The number of message queues available to the application is configured - * through the #CONFIGURE_MAXIMUM_MESSAGE_QUEUES application configuration - * option. + * through the @ref CONFIGURE_MAXIMUM_MESSAGE_QUEUES application + * configuration option. * * * Where the object class corresponding to the directive is configured to use * unlimited objects, the directive may allocate memory from the RTEMS * Workspace. * * * The number of global objects available to the application is configured - * through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration - * option. + * through the @ref CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application + * configuration option. * @endparblock */ rtems_status_code rtems_message_queue_create( @@ -286,11 +288,12 @@ rtems_status_code rtems_message_queue_create( * @brief Constructs a message queue from the specified the message queue * configuration. * - * @param config is the message queue configuration. + * @param config is the pointer to an rtems_message_queue_config object. It + * configures the message queue. * - * @param[out] id is the pointer to an object identifier variable. When the - * directive call is successful, the identifier of the constructed message - * queue will be stored in this variable. + * @param[out] id is the pointer to an ::rtems_id object. When the directive + * call is successful, the identifier of the constructed message queue will + * be stored in this object. * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * @@ -340,8 +343,8 @@ rtems_status_code rtems_message_queue_create( * runtime memory allocators. This can simplify the application architecture * as well as any analysis that may be required. * - * The value for #CONFIGURE_MESSAGE_BUFFER_MEMORY should not include memory for - * message queues constructed by rtems_message_queue_construct(). + * The value for @ref CONFIGURE_MESSAGE_BUFFER_MEMORY should not include memory + * for message queues constructed by rtems_message_queue_construct(). * @endparblock * * @par Constraints @@ -360,16 +363,16 @@ rtems_status_code rtems_message_queue_create( * message to remote nodes. This may preempt the calling task. * * * The number of message queues available to the application is configured - * through the #CONFIGURE_MAXIMUM_MESSAGE_QUEUES application configuration - * option. + * through the @ref CONFIGURE_MAXIMUM_MESSAGE_QUEUES application + * configuration option. * * * Where the object class corresponding to the directive is configured to use * unlimited objects, the directive may allocate memory from the RTEMS * Workspace. * * * The number of global objects available to the application is configured - * through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration - * option. + * through the @ref CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application + * configuration option. * @endparblock */ rtems_status_code rtems_message_queue_construct( @@ -388,9 +391,9 @@ rtems_status_code rtems_message_queue_construct( * * @param node is the node or node set to search for a matching object. * - * @param[out] id is the pointer to an object identifier variable. When the - * directive call is successful, the object identifier of an object with the - * specified name will be stored in this variable. + * @param[out] id is the pointer to an ::rtems_id object. When the directive + * call is successful, the object identifier of an object with the specified + * name will be stored in this object. * * This directive obtains a message queue identifier associated with the * message queue name specified in ``name``. @@ -647,13 +650,13 @@ rtems_status_code rtems_message_queue_urgent( * * @param size is the size in bytes of the message buffer to broadcast. * - * @param[out] count is the pointer to an uint32_t variable. When the - * directive call is successful, the number of unblocked tasks will be stored - * in this variable. + * @param[out] count is the pointer to an uint32_t object. When the directive + * call is successful, the number of unblocked tasks will be stored in this + * object. * * This directive causes all tasks that are waiting at the queue specified by * ``id`` to be unblocked and sent the message contained in ``buffer``. Before - * a task is unblocked, the message ``buffer`` of ``size`` byes in length is + * a task is unblocked, the message ``buffer`` of ``size`` bytes in length is * copied to that task's message buffer. The number of tasks that were * unblocked is returned in ``count``. * @@ -713,9 +716,9 @@ rtems_status_code rtems_message_queue_broadcast( * rtems_message_queue_construct(). The ``size`` parameter cannot be used to * specify the size of the buffer. * - * @param size is the pointer to a size_t variable. When the directive call is - * successful, the size in bytes of the received messages will be stored in - * this variable. This parameter cannot be used to specify the size of the + * @param[out] size is the pointer to a size_t object. When the directive call + * is successful, the size in bytes of the received messages will be stored + * in this object. This parameter cannot be used to specify the size of the * buffer. * * @param option_set is the option set. @@ -773,9 +776,6 @@ rtems_status_code rtems_message_queue_broadcast( * * @retval ::RTEMS_UNSATISFIED The queue was empty. * - * @retval ::RTEMS_UNSATISFIED The queue was flushed while the calling task was - * waiting to receive a message. - * * @retval ::RTEMS_TIMEOUT The timeout happened while the calling task was * waiting to receive a message * @@ -819,9 +819,9 @@ rtems_status_code rtems_message_queue_receive( * * @param id is the queue identifier. * - * @param[out] count is the pointer to an uint32_t variable. When the - * directive call is successful, the number of pending messages will be - * stored in this variable. + * @param[out] count is the pointer to an uint32_t object. When the directive + * call is successful, the number of pending messages will be stored in this + * object. * * This directive returns the number of messages pending on the queue specified * by ``id`` in ``count``. If no messages are present on the queue, count is @@ -861,9 +861,9 @@ rtems_status_code rtems_message_queue_get_number_pending( * * @param id is the queue identifier. * - * @param[out] count is the pointer to an uint32_t variable. When the - * directive call is successful, the number of unblocked tasks will be stored - * in this variable. + * @param[out] count is the pointer to an uint32_t object. When the directive + * call is successful, the number of pending messages removed from the queue + * will be stored in this object. * * This directive removes all pending messages from the queue specified by * ``id``. The number of messages removed is returned in ``count``. If no @@ -876,17 +876,22 @@ rtems_status_code rtems_message_queue_get_number_pending( * * @retval ::RTEMS_INVALID_ADDRESS The ``count`` parameter was NULL. * + * @par Notes + * The directive does not flush tasks waiting to receive a message from the + * wait queue of the message queue. + * * @par Constraints * @parblock * The following constraints apply to this directive: * - * * The directive may be called from within task context. - * * * The directive may be called from within interrupt context. * - * * When the directive operates on a remote object, the directive sends a - * message to the remote node and waits for a reply. This will preempt the - * calling task. + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive will not cause the calling task to be preempted. * @endparblock */ rtems_status_code rtems_message_queue_flush( rtems_id id, uint32_t *count ); |