Changeset 0865cd2 in rtems


Ignore:
Timestamp:
Apr 5, 2019, 10:39:51 AM (6 months ago)
Author:
Andreas Dachsberger <andreas.dachsberger@…>
Branches:
master
Children:
d369903
Parents:
accbe67
git-author:
Andreas Dachsberger <andreas.dachsberger@…> (04/05/19 10:39:51)
git-committer:
Sebastian Huber <sebastian.huber@…> (05/13/19 05:42:03)
Message:

doxygen: score: adjust doc in coremsgimpl.h to doxygen guidelines

Update #3706.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • cpukit/include/rtems/score/coremsgimpl.h

    raccbe67 r0865cd2  
    11/**
    22 * @file
     3 *
     4 * @ingroup RTEMSScoreMessageQueue
    35 *
    46 * @brief Inlined Routines in the Core Message Handler
     
    3537/**
    3638 * @addtogroup RTEMSScoreMessageQueue
    37  */
    38 /**@{**/
     39 *
     40 * @{
     41 */
    3942
    4043/**
     
    6770
    6871/**
    69  *  @brief Initialize a message queue.
    70  *
    71  *  This package is the implementation of the CORE Message Queue Handler.
    72  *  This core object provides task synchronization and communication functions
    73  *  via messages passed to queue objects.
    74  *
    75  *  This routine initializes @a the_message_queue
    76  *      based on the parameters passed.
    77  *
    78  *  @param[in] the_message_queue points to the message queue to initialize
    79  *  @param[in] discipline the blocking discipline
    80  *  @param[in] maximum_pending_messages is the maximum number of messages
    81  *         that will be allowed to pend at any given time
    82  *  @param[in] maximum_message_size is the size of largest message that
    83  *         may be sent to this message queue instance
    84  *
    85  *  @retval true if the message queue can be initialized.  In general,
    86  *         false will only be returned if memory for the pending
    87  *         messages cannot be allocated.
     72 * @brief Initializes a message queue.
     73 *
     74 * This package is the implementation of the CORE Message Queue Handler.
     75 * This core object provides task synchronization and communication functions
     76 * via messages passed to queue objects.
     77 *
     78 * This routine initializes @a the_message_queue
     79 *        based on the parameters passed.
     80 *
     81 * @param[out] the_message_queue The message queue to initialize.
     82 * @param discipline The blocking discipline for the message queue.
     83 * @param maximum_pending_messages The maximum number of messages
     84 *        that will be allowed to pend at any given time.
     85 * @param maximum_message_size The size of the largest message that
     86 *        may be sent to this message queue instance.
     87 *
     88 * @retval true The message queue can be initialized.
     89 * @retval false Memory for the pending messages cannot be allocated.
    8890 */
    8991bool _CORE_message_queue_Initialize(
     
    9597
    9698/**
    97  *  @brief Close a message queue.
    98  *
    99  *  This package is the implementation of the CORE Message Queue Handler.
    100  *  This core object provides task synchronization and communication functions
    101  *  via messages passed to queue objects
    102  *
    103  *  This function closes a message by returning all allocated space and
    104  *  flushing @a the_message_queue's task wait queue.
    105  *
    106  *  @param[in] the_message_queue points to the message queue to close
    107  *  @param[in] queue_context The thread queue context used for
    108  *    _CORE_message_queue_Acquire() or _CORE_message_queue_Acquire_critical().
     99 * @brief Closes a message queue.
     100 *
     101 * This package is the implementation of the CORE Message Queue Handler.
     102 * This core object provides task synchronization and communication functions
     103 * via messages passed to queue objects.
     104 *
     105 * This function closes a message by returning all allocated space and
     106 * flushing @a the_message_queue's task wait queue.
     107 *
     108 * @param[in, out] the_message_queue The message queue to close.
     109 * @param[in, out] queue_context The thread queue context used for
     110 *   _CORE_message_queue_Acquire() or _CORE_message_queue_Acquire_critical().
    109111 */
    110112void _CORE_message_queue_Close(
     
    114116
    115117/**
    116  *  @brief Flush pending messages.
    117  *
    118  *  This package is the implementation of the CORE Message Queue Handler.
    119  *  This core object provides task synchronization and communication functions
    120  *  via messages passed to queue objects.
    121  *
    122  *  This function flushes @a the_message_queue's pending message queue.  The
    123  *  number of messages flushed from the queue is returned.
    124  *
    125  *  @param[in] the_message_queue points to the message queue to flush
    126  *  @param[in] queue_context The thread queue context with interrupts disabled.
    127  *
    128  *  @retval This method returns the number of message pending messages flushed.
     118 * @brief Flushes pending messages.
     119 *
     120 * This package is the implementation of the CORE Message Queue Handler.
     121 * This core object provides task synchronization and communication functions
     122 * via messages passed to queue objects.
     123 *
     124 * This function flushes @a the_message_queue's pending message queue.  The
     125 * number of messages flushed from the queue is returned.
     126 *
     127 * @param[in, out] the_message_queue The message queue to flush.
     128 * @param queue_context The thread queue context with interrupts disabled.
     129 *
     130 * @return This method returns the number of message pending messages flushed.
    129131 */
    130132uint32_t   _CORE_message_queue_Flush(
     
    135137#if defined(FUNCTIONALITY_NOT_CURRENTLY_USED_BY_ANY_API)
    136138/**
    137  *  @brief Flush waiting threads.
    138  *
    139  *  This function flushes the threads which are blocked on
    140  *  @a the_message_queue's pending message queue.  They are
    141  *  unblocked whether blocked sending or receiving. It returns
    142  *  the number of messages flushed from the queue.
    143  *
    144  *  @param[in] the_message_queue points to the message queue to flush
    145  *  @retval number of messages flushed from the queue
     139 * @brief Flushes waiting threads.
     140 *
     141 * This function flushes the threads which are blocked on
     142 * @a the_message_queue's pending message queue.  They are
     143 * unblocked whether blocked sending or receiving. It returns
     144 * the number of messages flushed from the queue.
     145 *
     146 * @param[in, out] the_message_queue The message queue to flush.
     147 *
     148 * @return This method returns the number of messages flushed from the queue.
    146149 */
    147150  void _CORE_message_queue_Flush_waiting_threads(
     
    151154
    152155/**
    153  *  @brief Broadcast a message to the message queue.
    154  *
    155  *  This package is the implementation of the CORE Message Queue Handler.
    156  *  This core object provides task synchronization and communication functions
    157  *  via messages passed to queue objects.
    158  *
    159  *  This function sends a message for every thread waiting on the queue and
    160  *  returns the number of threads made ready by the message.
    161  *
    162  *  @param[in] the_message_queue points to the message queue
    163  *  @param[in] buffer is the starting address of the message to broadcast
    164  *  @param[in] size is the size of the message being broadcast
    165  *  @param[out] count points to the variable that will contain the
    166  *         number of tasks that are sent this message
    167  *  @param[in] queue_context The thread queue context used for
    168  *    _CORE_message_queue_Acquire() or _CORE_message_queue_Acquire_critical().
    169  *  @retval @a *count will contain the number of messages sent
    170  *  @retval indication of the successful completion or reason for failure
     156 * @brief Broadcasts a message to the message queue.
     157 *
     158 * This package is the implementation of the CORE Message Queue Handler.
     159 * This core object provides task synchronization and communication functions
     160 * via messages passed to queue objects.
     161 *
     162 * This function sends a message for every thread waiting on the queue and
     163 * returns the number of threads made ready by the message.
     164 *
     165 * @param[in, out] the_message_queue The message queue to operate upon.
     166 * @param buffer The starting address of the message to broadcast.
     167 * @param size The size of the message being broadcast.
     168 * @param[out] count The variable that will contain the
     169 *        number of tasks that are sent this message.
     170 * @param queue_context The thread queue context used for
     171 *   _CORE_message_queue_Acquire() or _CORE_message_queue_Acquire_critical().
     172 *
     173 * @retval STATUS_SUCCESSFUL The message was successfully broadcast.
     174 * @retval STATUS_MESSAGE_INVALID_SIZE The message size was too big.
    171175 */
    172176Status_Control _CORE_message_queue_Broadcast(
     
    179183
    180184/**
    181  *  @brief Submit a message to the message queue.
    182  *
    183  *  This routine implements the send and urgent message functions. It
    184  *  processes a message that is to be submitted to the designated
    185  *  message queue.  The message will either be processed as a
    186  *  send message which it will be inserted at the rear of the queue
    187  *  or it will be processed as an urgent message which will be inserted
    188  *  at the front of the queue.
    189  *
    190  *  @param[in] the_message_queue points to the message queue
    191  *  @param[in] buffer is the starting address of the message to send
    192  *  @param[in] size is the size of the message being send
    193  *  @param[in] submit_type determines whether the message is prepended,
    194  *         appended, or enqueued in priority order.
    195  *  @param[in] wait indicates whether the calling thread is willing to block
    196  *         if the message queue is full.
    197  *  @param[in] queue_context The thread queue context used for
    198  *    _CORE_message_queue_Acquire() or _CORE_message_queue_Acquire_critical().
    199  *  @retval indication of the successful completion or reason for failure
     185 * @brief Submits a message to the message queue.
     186 *
     187 * This routine implements the send and urgent message functions. It
     188 * processes a message that is to be submitted to the designated
     189 * message queue.  The message will either be processed as a
     190 * send message which it will be inserted at the rear of the queue
     191 * or it will be processed as an urgent message which will be inserted
     192 * at the front of the queue.
     193 *
     194 * @param[in, out] the_message_queue The message queue to operate upon.
     195 * @param executing The executing thread.
     196 * @param buffer The starting address of the message to send.
     197 * @param size The size of the message being send.
     198 * @param submit_type Determines whether the message is prepended,
     199 *        appended, or enqueued in priority order.
     200 * @param wait Indicates whether the calling thread is willing to block
     201 *        if the message queue is full.
     202 * @param queue_context The thread queue context used for
     203 *   _CORE_message_queue_Acquire() or _CORE_message_queue_Acquire_critical().
     204 *
     205 * @retval STATUS_SUCCESSFUL The message was successfully submitted to the message queue.
     206 * @retval STATUS_MESSAGE_INVALID_SIZE The message size was too big.
     207 * @retval STATUS_TOO_MANY No message buffers were available.
     208 * @retval STATUS_MESSAGE_QUEUE_WAIT_IN_ISR The caller is in an ISR, do not block!
     209 * @retval STATUS_TIMEOUT A timeout occured.
    200210 */
    201211Status_Control _CORE_message_queue_Submit(
     
    210220
    211221/**
    212  *  @brief Size a message from the message queue.
    213  *
    214  *  This package is the implementation of the CORE Message Queue Handler.
    215  *  This core object provides task synchronization and communication functions
    216  *  via messages passed to queue objects.
    217  *
    218  *  This kernel routine dequeues a message, copies the message buffer to
    219  *  a given destination buffer, and frees the message buffer to the
    220  *  inactive message pool.  The thread will be blocked if wait is true,
    221  *  otherwise an error will be given to the thread if no messages are available.
    222  *
    223  *  @param[in] the_message_queue points to the message queue
    224  *  @param[in] buffer is the starting address of the message buffer to
    225  *         to be filled in with a message
    226  *  @param[in] size_p is a pointer to the size of the @a buffer and
    227  *         indicates the maximum size message that the caller can receive.
    228  *  @param[in] wait indicates whether the calling thread is willing to block
    229  *         if the message queue is empty.
    230  *  @param[in] queue_context The thread queue context used for
    231  *    _CORE_message_queue_Acquire() or _CORE_message_queue_Acquire_critical().
    232  *
    233  *  @retval indication of the successful completion or reason for failure.
    234  *          On success, the location pointed to @a size_p will contain the
    235  *          size of the received message.
    236  *
    237  *  @note Returns message priority via return area in TCB.
    238  *
    239  *  - INTERRUPT LATENCY:
    240  *    + available
    241  *    + wait
     222 * @brief Seizes a message from the message queue.
     223 *
     224 * This package is the implementation of the CORE Message Queue Handler.
     225 * This core object provides task synchronization and communication functions
     226 * via messages passed to queue objects.
     227 *
     228 * This kernel routine dequeues a message, copies the message buffer to
     229 * a given destination buffer, and frees the message buffer to the
     230 * inactive message pool.  The thread will be blocked if wait is true,
     231 * otherwise an error will be given to the thread if no messages are available.
     232 *
     233 * @param[in, out] the_message_queue The message queue to seize a message from.
     234 * @param executing The executing thread.
     235 * @param[out] buffer The starting address of the message buffer to
     236 *        to be filled in with a message.
     237 * @param[out] size_p The size of the @a buffer,
     238 *        indicates the maximum size message that the caller can receive.
     239 * @param wait Indicates whether the calling thread is willing to block
     240 *        if the message queue is empty.
     241 * @param queue_context The thread queue context used for
     242 *   _CORE_message_queue_Acquire() or _CORE_message_queue_Acquire_critical().
     243 *
     244 * @retval STATUS_SUCCESSFUL The message was successfully seized from the message queue.
     245 * @retval STATUS_UNSATISFIED Wait was set to false and there is currently no pending message.
     246 * @retval STATUS_TIMEOUT A timeout occured.
     247 *
     248 * @note Returns message priority via return area in TCB.
     249 *
     250 * - INTERRUPT LATENCY:
     251 *   + available
     252 *   + wait
    242253 */
    243254Status_Control _CORE_message_queue_Seize(
     
    251262
    252263/**
    253  *  @brief Insert a message into the message queue.
    254  *
    255  *  Copies the specified content into the message storage space and then
    256  *  inserts the message into the message queue according to the submit type.
    257  *
    258  *  @param[in] the_message_queue points to the message queue
    259  *  @param[in] the_message is the message to enqueue
    260  *  @param[in] content_source the message content source
    261  *  @param[in] content_size the message content size in bytes
    262  *  @param[in] submit_type determines whether the message is prepended,
    263  *         appended, or enqueued in priority order.
     264 * @brief Inserts a message into the message queue.
     265 *
     266 * Copies the specified content into the message storage space and then
     267 * inserts the message into the message queue according to the submit type.
     268 *
     269 * @param[in, out] the_message_queue The message queue to insert a message in.
     270 * @param[in, out] the_message The message to insert in the message queue.
     271 * @param content_source The message content source.
     272 * @param content_size The message content size in bytes.
     273 * @param submit_type Determines whether the message is prepended,
     274 *        appended, or enqueued in priority order.
    264275 */
    265276void _CORE_message_queue_Insert_message(
     
    271282);
    272283
     284/**
     285 * @brief Sends a message to the message queue.
     286 *
     287 * @param[in, out] the_message_queue The message queue to send a message to.
     288 * @param buffer The starting address of the message to send.
     289 * @param sizeis The size of the message being send.
     290 * @param wait Indicates whether the calling thread is willing to block
     291 *        if the message queue is full.
     292 * @param queue_context The thread queue context used for
     293 *   _CORE_message_queue_Acquire() or _CORE_message_queue_Acquire_critical().
     294 *
     295 * @retval STATUS_SUCCESSFUL The message was successfully submitted to the message queue.
     296 * @retval STATUS_MESSAGE_INVALID_SIZE The message size was too big.
     297 * @retval STATUS_TOO_MANY No message buffers were available.
     298 * @retval STATUS_MESSAGE_QUEUE_WAIT_IN_ISR The caller is in an ISR, do not block!
     299 * @retval STATUS_TIMEOUT A timeout occured.
     300 */
    273301RTEMS_INLINE_ROUTINE Status_Control _CORE_message_queue_Send(
    274302  CORE_message_queue_Control       *the_message_queue,
     
    290318}
    291319
     320/**
     321 * @brief Sends an urgent message to the message queue.
     322 *
     323 * @param[in, out] the_message_queue The message queue to send an urgent message to.
     324 * @param buffer The starting address of the message to send.
     325 * @param sizeis The size of the message being send.
     326 * @param wait Indicates whether the calling thread is willing to block
     327 *        if the message queue is full.
     328 * @param queue_context The thread queue context used for
     329 *   _CORE_message_queue_Acquire() or _CORE_message_queue_Acquire_critical().
     330 *
     331 * @retval STATUS_SUCCESSFUL The message was successfully submitted to the message queue.
     332 * @retval STATUS_MESSAGE_INVALID_SIZE The message size was too big.
     333 * @retval STATUS_TOO_MANY No message buffers were available.
     334 * @retval STATUS_MESSAGE_QUEUE_WAIT_IN_ISR The caller is in an ISR, do not block!
     335 * @retval STATUS_TIMEOUT A timeout occured.
     336 */
    292337RTEMS_INLINE_ROUTINE Status_Control _CORE_message_queue_Urgent(
    293338  CORE_message_queue_Control       *the_message_queue,
     
    309354}
    310355
     356/**
     357 * @brief Acquires the message queue.
     358 *
     359 * @param[in, out] the_message_queue Rhe message queue to acquire.
     360 * @param queue_context The thread queue context.
     361 */
    311362RTEMS_INLINE_ROUTINE void _CORE_message_queue_Acquire(
    312363  CORE_message_queue_Control *the_message_queue,
     
    317368}
    318369
     370/**
     371 * @brief Acquires the message queue critical.
     372 *
     373 * @param[in, out] the_message_queue The message queue to acquire critical.
     374 * @param queue_context The thread queue context.
     375 */
    319376RTEMS_INLINE_ROUTINE void _CORE_message_queue_Acquire_critical(
    320377  CORE_message_queue_Control *the_message_queue,
     
    325382}
    326383
     384/**
     385 * @brief Releases the message queue.
     386 *
     387 * @param[in, out] the_message_queue The message queue to release.
     388 * @param queue_context The thread queue context.
     389 */
    327390RTEMS_INLINE_ROUTINE void _CORE_message_queue_Release(
    328391  CORE_message_queue_Control *the_message_queue,
     
    334397
    335398/**
     399 * @brief Copies the source message buffer to the destination message buffer.
     400 *
    336401 * This routine copies the contents of the source message buffer
    337402 * to the destination message buffer.
     403 *
     404 * @param source The source message buffer to be copied.
     405 * @param[out] destination The destination messag buffer to copy the source to.
     406 * @param size The size of the source buffer.
    338407 */
    339408RTEMS_INLINE_ROUTINE void _CORE_message_queue_Copy_buffer (
     
    347416
    348417/**
     418 * @brief Allocates a message buffer from the inactive message buffer chain.
     419 *
    349420 * This function allocates a message buffer from the inactive
    350421 * message buffer chain.
     422 *
     423 * @param the_message_queue The message queue to operate upon.
     424 *
     425 * @retval pointer The allocated message buffer.
     426 * @retval NULL The inactive message buffer chain is empty.
    351427 */
    352428RTEMS_INLINE_ROUTINE CORE_message_queue_Buffer_control *
     
    360436
    361437/**
     438 * @brief Frees a message buffer to inactive message buffer chain.
     439 *
    362440 * This routine frees a message buffer to the inactive
    363441 * message buffer chain.
     442 *
     443 * @param[in, out] the_message_queue The message queue to free the message buffer to.
     444 * @param[out] the_message The message to be freed.
    364445 */
    365446RTEMS_INLINE_ROUTINE void _CORE_message_queue_Free_message_buffer (
     
    372453
    373454/**
     455 * @brief Gets message priority.
     456 *
    374457 * This function returns the priority of @a the_message.
     458 *
     459 * @param the_message The message to obtain the priority from.
     460 *
     461 * @retval priority The priority of this message.
     462 * @retval 0 Message priority is disabled.
    375463 *
    376464 * @note It encapsulates the optional behavior that message priority is
     
    389477
    390478/**
     479 * @brief Gets first message of message queue and removes it.
     480 *
    391481 * This function removes the first message from the_message_queue
    392482 * and returns a pointer to it.
     483 *
     484 * @param[in, out] the_message_queue The message queue to get the first message from.
     485 *
     486 * @retval pointer The first message if the message queue is not empty.
     487 * @retval NULL The message queue is empty.
    393488 */
    394489RTEMS_INLINE_ROUTINE
     
    403498#if defined(RTEMS_SCORE_COREMSG_ENABLE_NOTIFICATION)
    404499  /**
     500   * @brief Checks if notification is enabled.
     501   *
    405502   * This function returns true if notification is enabled on this message
    406503   * queue and false otherwise.
     504   *
     505   * @param the_message_queue The message queue to check if the notification is enabled.
     506   *
     507   * @retval true Notification is enabled on this message queue.
     508   * @retval false Notification is not enabled on this message queue.
    407509   */
    408510  RTEMS_INLINE_ROUTINE bool _CORE_message_queue_Is_notify_enabled (
     
    415517
    416518/**
     519 * @brief Initializes notification information.
     520 *
    417521 * This routine initializes the notification information for
    418522 * @a the_message_queue.
     523 *
     524 * @param[out] the_message_queue The message queue to initialize the notification information.
     525 * @param[out] the_handler The notification information for the message queue.
    419526 */
    420527#if defined(RTEMS_SCORE_COREMSG_ENABLE_NOTIFICATION)
     
    432539#endif
    433540
     541/**
     542 * @brief Gets the first locked thread waiting to receive and dequeues it.
     543 *
     544 * This method dequeues the first locked thread waiting to receive a message,
     545 *      dequeues it and returns the corresponding Thread_Control.
     546 *
     547 * @param[in, out] the_message_queue The message queue to operate upon.
     548 * @param buffer The buffer that is copied to the threads mutable_object.
     549 * @param size The size of the buffer.
     550 * @param submit_type Indicates whether the thread should be willing to block in the future.
     551 * @param queue_context The thread queue context.
     552 *
     553 * @retval thread The Thread_Control for the first locked thread, if there is a locked thread.
     554 * @retval NULL There are pending messages or no thread waiting to receive.
     555 */
    434556RTEMS_INLINE_ROUTINE Thread_Control *_CORE_message_queue_Dequeue_receiver(
    435557  CORE_message_queue_Control      *the_message_queue,
Note: See TracChangeset for help on using the changeset viewer.