Changeset fbe8a7a in rtems

Timestamp:

04/03/19 10:44:42 (4 years ago)

Author:

Sebastian Huber <sebastian.huber@…>

Branches:

5, master

Children:

6644867

Parents:

a2aec0b7

git-author:

Sebastian Huber <sebastian.huber@…> (04/03/19 10:44:42)

git-committer:

Sebastian Huber <sebastian.huber@…> (04/04/19 05:22:08)

Message:

doxygen: Rework some Doxygen comments

They are intended as examples in the RTEMS Software Engineering manual.

Update #3704.

Location:

cpukit/include/rtems

Files:

• rtems/message.h (modified) (2 diffs)
• score/rbtree.h (modified) (1 diff)
• score/wkspace.h (modified) (1 diff)

cpukit/include/rtems/rtems/message.h

@@ -105 +105 @@
 
 /**
- *  @brief rtems_message_queue_send
- *
- *  Message Queue Manager - rtems_message_queue_send
- *
- *  This routine implements the rtems_message_queue_send directive.
- *  This directive sends the message buffer to the message queue
- *  indicated by ID.  If one or more tasks is blocked waiting
- *  to receive a message from this message queue, then one will
- *  receive the message.  The task selected to receive the
- *  message is based on the task queue discipline algorithm in
- *  use by this particular message queue.  If no tasks are waiting,
- *  then the message buffer will be placed at the REAR of the
- *  chain of pending messages for this message queue.
+ * @brief Sends a message to the message queue.
+ *
+ * This directive sends the message buffer to the message queue indicated by
+ * ID.  If one or more tasks is blocked waiting to receive a message from this
+ * message queue, then one will receive the message.  The task selected to
+ * receive the message is based on the task queue discipline algorithm in use
+ * by this particular message queue.  If no tasks are waiting, then the message
+ * buffer will be placed at the rear of the chain of pending messages for this
+ * message queue.
+ *
+ * @param id The message queue ID.
+ * @param buffer The message content buffer.
+ * @param size The size of the message.
+ *
+ * @retval RTEMS_SUCCESSFUL Successful operation.
+ * @retval RTEMS_INVALID_ID Invalid message queue ID.
+ * @retval RTEMS_INVALID_ADDRESS The message buffer pointer is @c NULL.
+ * @retval RTEMS_INVALID_SIZE The message size is larger than the maximum
+ *   message size of the message queue.
+ * @retval RTEMS_TOO_MANY The new message would exceed the message queue limit
+ *   for pending messages.
  */
 rtems_status_code rtems_message_queue_send(
@@ -170 +178 @@
 
 /**
- * @brief RTEMS Message Queue Receive
- *
- * This routine implements the rtems_message_queue_receive directive.
- * This directive is invoked when the calling task wishes to receive
- * a message from the message queue indicated by ID. The received
- * message is to be placed in buffer. If no messages are outstanding
- * and the option_set indicates that the task is willing to block,
- * then the task will be blocked until a message arrives or until,
- * optionally, timeout clock ticks have passed.
- *
- * @param[in] id is the queue id
- * @param[in] buffer is the pointer to message buffer
- * @param[in] size is the size of message receive
- * @param[in] option_set is the options on receive
- * @param[in] timeout is the number of ticks to wait
- *
- * @retval This method returns RTEMS_SUCCESSFUL if there was not an
- *         error. Otherwise, a status code is returned indicating the
- *         source of the error.
+ * @brief Receives a message from the message queue
+ *
+ * This directive is invoked when the calling task wishes to receive a message
+ * from the message queue indicated by ID. The received message is to be placed
+ * in the buffer. If no messages are outstanding and the option set indicates
+ * that the task is willing to block, then the task will be blocked until a
+ * message arrives or until, optionally, timeout clock ticks have passed.
+ *
+ * @param id The message queue ID.
+ * @param[out] buffer The buffer for the message content.  The buffer must be
+ *   large enough to store maximum size messages of this message queue.
+ * @param[out] size The size of the message.
+ * @param option_set The option set, e.g. RTEMS_NO_WAIT or RTEMS_WAIT.
+ * @param timeout The number of ticks to wait if the RTEMS_WAIT is set.  Use
+ *   RTEMS_NO_TIMEOUT to wait indefinitely.
+ *
+ * @retval RTEMS_SUCCESSFUL Successful operation.
+ * @retval RTEMS_INVALID_ID Invalid message queue ID.
+ * @retval RTEMS_INVALID_ADDRESS The message buffer pointer or the message size
+ *   pointer is @c NULL.
+ * @retval RTEMS_TIMEOUT A timeout occurred and no message was received.
  */
 rtems_status_code rtems_message_queue_receive(

cpukit/include/rtems/score/rbtree.h

@@ -107 +107 @@
  * @brief Rebalances the red-black tree after insertion of the node.
  *
- * @param[in] the_rbtree The red-black tree control.
- * @param[in] the_node The most recently inserted node.
+ * @param[in, out] the_rbtree The red-black tree control.
+ * @param[in, out] the_node The most recently inserted node.
  */
 void _RBTree_Insert_color(

cpukit/include/rtems/score/wkspace.h

@@ -58 +58 @@
 
 /**
- * @brief Allocate memory from workspace.
+ * @brief Allocates a memory block of the specified size from the workspace.
  *
- *  This routine returns the address of a block of memory of size
- *  bytes.  If a block of the appropriate size cannot be allocated
- *  from the workspace, then NULL is returned.
+ * @param size The size of the memory block.
  *
- *  @param size is the requested size
- *
- *  @retval a pointer to the requested memory or NULL.
+ * @retval pointer The pointer to the memory block.  The pointer is at least
+ *   aligned by CPU_HEAP_ALIGNMENT.
+ * @retval NULL No memory block with the requested size is available in the
+ *   workspace.
  */
-void *_Workspace_Allocate(
-  size_t   size
-);
+void *_Workspace_Allocate( size_t size );
 
 /**