diff options
Diffstat (limited to 'cpukit/include/rtems/rtems/message.h')
| -rw-r--r-- | cpukit/include/rtems/rtems/message.h | 59 |
1 files changed, 32 insertions, 27 deletions
diff --git a/cpukit/include/rtems/rtems/message.h b/cpukit/include/rtems/rtems/message.h index 01173d4029..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 @@ -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,7 +288,8 @@ 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 ::rtems_id object. When the directive * call is successful, the identifier of the constructed message queue will @@ -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( @@ -653,7 +656,7 @@ rtems_status_code rtems_message_queue_urgent( * * 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``. * @@ -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 * @@ -862,8 +862,8 @@ 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 object. When the directive - * call is successful, the number of unblocked tasks will be stored in this - * object. + * 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 ); |