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

Update #3706.

1 files changed, 169 insertions, 6 deletions

diff --git a/cpukit/include/rtems/score/processormask.h b/cpukit/include/rtems/score/processormask.h
index ce87e9926b..19ad5143da 100644
--- a/cpukit/include/rtems/score/processormask.h
+++ b/cpukit/include/rtems/score/processormask.h
@@ -38,6 +38,8 @@ extern "C" {
  *
  * @ingroup RTEMSScore
  *
+ * @brief Processor Mask
+ *
  * The processor mask provides a bit map large enough to provide one bit for
  * each processor in the system.  It is a fixed size internal data type
  * provided for efficiency in addition to the API level cpu_set_t.
@@ -51,21 +53,45 @@ extern "C" {
  */
 typedef BITSET_DEFINE( Processor_mask, CPU_MAXIMUM_PROCESSORS ) Processor_mask;
 
+/**
+ * @brief Sets the bits of the mask to zero, also considers CPU_MAXIMUM_PROCESSORS.
+ *
+ * @param[out] mask The mask to set to zero.
+ */
 RTEMS_INLINE_ROUTINE void _Processor_mask_Zero( Processor_mask *mask )
 {
   BIT_ZERO( CPU_MAXIMUM_PROCESSORS, mask );
 }
 
+/**
+ * @brief Checks if the mask is zero, also considers CPU_MAXIMUM_PROCESSORS.
+ *
+ * @param mask The mask to check whether is is zero
+ *
+ * @retval true The mask is zero.
+ * @retval false The mask is not zero.
+ */
 RTEMS_INLINE_ROUTINE bool _Processor_mask_Is_zero( const Processor_mask *mask )
 {
   return BIT_EMPTY( CPU_MAXIMUM_PROCESSORS, mask );
 }
 
+/**
+ * @brief Fills the mask, also considers CPU_MAXIMUM_PROCESSORS.
+ *
+ * @param[out] mask The mask to fill
+ */
 RTEMS_INLINE_ROUTINE void _Processor_mask_Fill( Processor_mask *mask )
 {
   BIT_FILL( CPU_MAXIMUM_PROCESSORS, mask );
 }
 
+/**
+ * @brief Copies the mask to another mask, also considers CPU_MAXIMUM_PROCESSORS.
+ *
+ * @param[out] dst The mask to copy @a src to.
+ * @param src The mask to copy to @a dst.
+ */
 RTEMS_INLINE_ROUTINE void _Processor_mask_Assign(
   Processor_mask *dst, const Processor_mask *src
 )
@@ -73,6 +99,12 @@ RTEMS_INLINE_ROUTINE void _Processor_mask_Assign(
   BIT_COPY( CPU_MAXIMUM_PROCESSORS, src, dst );
 }
 
+/**
+ * @brief Sets the specified index bit of the mask.
+ *
+ * @param[out] mask The mask to set the bit of.
+ * @param index The index of the bit that shall be set.
+ */
 RTEMS_INLINE_ROUTINE void _Processor_mask_Set(
   Processor_mask *mask,
   uint32_t        index
@@ -81,6 +113,12 @@ RTEMS_INLINE_ROUTINE void _Processor_mask_Set(
   BIT_SET( CPU_MAXIMUM_PROCESSORS, index, mask );
 }
 
+/**
+ * @brief Clears the specified index bit of the mask.
+ *
+ * @param[out] mask The mask to clear the bit of.
+ * @param index The index of the bit that shall be cleared.
+ */
 RTEMS_INLINE_ROUTINE void _Processor_mask_Clear(
   Processor_mask *mask,
   uint32_t        index
@@ -89,6 +127,15 @@ RTEMS_INLINE_ROUTINE void _Processor_mask_Clear(
   BIT_CLR( CPU_MAXIMUM_PROCESSORS, index, mask );
 }
 
+/**
+ * @brief Checks if the specified index bit of the mask is set.
+ *
+ * @param mask The mask to check if the specified bit is set.
+ * @param index The index of the bit that is checked.
+ *
+ * @retval true The specified index bit is set.
+ * @retval false The specified index bit is not set.
+ */
 RTEMS_INLINE_ROUTINE bool _Processor_mask_Is_set(
   const Processor_mask *mask,
   uint32_t              index
@@ -98,8 +145,13 @@ RTEMS_INLINE_ROUTINE bool _Processor_mask_Is_set(
 }
 
 /**
- * @brief Returns true if the processor sets a and b are equal, and false
- * otherwise.
+ * @brief Checks if the processor sets a and b are equal.
+ *
+ * @param a The first processor set.
+ * @param b The seconde processor set.
+ *
+ * @retval true The processor sets a and b are equal.
+ * @retval false The processor sets a and b are not equal.
  */
 RTEMS_INLINE_ROUTINE bool _Processor_mask_Is_equal(
   const Processor_mask *a,
@@ -110,8 +162,14 @@ RTEMS_INLINE_ROUTINE bool _Processor_mask_Is_equal(
 }
 
 /**
- * @brief Returns true if the intersection of the processor sets a and b is
- * non-empty, and false otherwise.
+ * @brief Checks if the intersection of the processor sets a and b is
+ * non-empty.
+ *
+ * @param a The first processor set.
+ * @param b The second processor set.
+ *
+ * @retval true The intersection of the processor sets a and b is non-empty.
+ * @retval false The intersection of the processor sets a and b is empty.
  */
 RTEMS_INLINE_ROUTINE bool _Processor_mask_Has_overlap(
   const Processor_mask *a,
@@ -122,8 +180,14 @@ RTEMS_INLINE_ROUTINE bool _Processor_mask_Has_overlap(
 }
 
 /**
- * @brief Returns true if the processor set small is a subset of processor set
- * big, and false otherwise.
+ * @brief Checks if the processor set small is a subset of processor set
+ * big.
+ *
+ * @param big The bigger processor set.
+ * @param small The smaller processor set.
+ *
+ * @retval true @a small is a subset of @a big.
+ * @retval false @a small is not a subset of @a big.
  */
 RTEMS_INLINE_ROUTINE bool _Processor_mask_Is_subset(
   const Processor_mask *big,
@@ -135,6 +199,10 @@ RTEMS_INLINE_ROUTINE bool _Processor_mask_Is_subset(
 
 /**
  * @brief Performs a bitwise a = b & c.
+ *
+ * @param[out] a The processor mask that is set by this operation.
+ * @param b The first parameter of the AND-operation.
+ * @param c The second parameter of the AND-operation.
  */
 RTEMS_INLINE_ROUTINE void _Processor_mask_And(
   Processor_mask       *a,
@@ -147,6 +215,10 @@ RTEMS_INLINE_ROUTINE void _Processor_mask_And(
 
 /**
  * @brief Performs a bitwise a = b & ~c.
+ *
+ * @param[out] a The processor mask that is set by this operation.
+ * @param b The first parameter of the operation.
+ * @param c The second parameter of the operation.
  */
 RTEMS_INLINE_ROUTINE void _Processor_mask_Nand(
   Processor_mask       *a,
@@ -159,6 +231,10 @@ RTEMS_INLINE_ROUTINE void _Processor_mask_Nand(
 
 /**
  * @brief Performs a bitwise a = b | c.
+ *
+ * @param[out] a The processor mask that is set by this operation.
+ * @param b The first parameter of the OR-operation.
+ * @param c The second parameter of the OR-operation.
  */
 RTEMS_INLINE_ROUTINE void _Processor_mask_Or(
   Processor_mask       *a,
@@ -171,6 +247,10 @@ RTEMS_INLINE_ROUTINE void _Processor_mask_Or(
 
 /**
  * @brief Performs a bitwise a = b ^ c.
+ *
+ * @param[out] a The processor mask that is set by this operation.
+ * @param b The first parameter of the XOR-operation.
+ * @param c The second parameter of the XOR-operation.
  */
 RTEMS_INLINE_ROUTINE void _Processor_mask_Xor(
   Processor_mask       *a,
@@ -181,11 +261,25 @@ RTEMS_INLINE_ROUTINE void _Processor_mask_Xor(
   BIT_XOR2( CPU_MAXIMUM_PROCESSORS, a, b, c );
 }
 
+/**
+ * @brief Gets the number of set bits in the processor mask.
+ *
+ * @param a The processor mask of which the set bits are counted.
+ *
+ * @return The number of set bits in @a a.
+ */
 RTEMS_INLINE_ROUTINE uint32_t _Processor_mask_Count( const Processor_mask *a )
 {
   return (uint32_t) BIT_COUNT( CPU_MAXIMUM_PROCESSORS, a );
 }
 
+/**
+ * @brief Finds the last set of the processor mask.
+ *
+ * @param a The processor mask wo find the last set of.
+ *
+ * @return The last set of @a a.
+ */
 RTEMS_INLINE_ROUTINE uint32_t _Processor_mask_Find_last_set( const Processor_mask *a )
 {
   return (uint32_t) BIT_FLS( CPU_MAXIMUM_PROCESSORS, a );
@@ -194,6 +288,11 @@ RTEMS_INLINE_ROUTINE uint32_t _Processor_mask_Find_last_set( const Processor_mas
 /**
  * @brief Returns the subset of 32 processors containing the specified index as
  * an unsigned 32-bit integer.
+ *
+ * @param mask The processor mask.
+ * @param index The specified index.
+ *
+ * @return The subset containing the specified index as an unsigned 32-bit integer.
  */
 RTEMS_INLINE_ROUTINE uint32_t _Processor_mask_To_uint32_t(
   const Processor_mask *mask,
@@ -208,6 +307,10 @@ RTEMS_INLINE_ROUTINE uint32_t _Processor_mask_To_uint32_t(
 /**
  * @brief Creates a processor set from an unsigned 32-bit integer relative to
  * the specified index.
+ *
+ * @param[out] mask The mask that is created.
+ * @param bits The bits for creating the mask.
+ * @param index The index to which the mask is relative.
  */
 RTEMS_INLINE_ROUTINE void _Processor_mask_From_uint32_t(
   Processor_mask *mask,
@@ -221,6 +324,9 @@ RTEMS_INLINE_ROUTINE void _Processor_mask_From_uint32_t(
 
 /**
  * @brief Creates a processor set from the specified index.
+ *
+ * @param[out] The mask that is created.
+ * @param index The specified index.
  */
 RTEMS_INLINE_ROUTINE void _Processor_mask_From_index(
   Processor_mask *mask,
@@ -237,6 +343,14 @@ typedef enum {
   PROCESSOR_MASK_COPY_INVALID_SIZE
 } Processor_mask_Copy_status;
 
+/**
+ * @brief Checks if the copy status guarantees at most partial loss.
+ *
+ * @param status The copy status to check.
+ *
+ * @retval true At most partial loss can be guaranteed.
+ * @retval false The status indicates more than partial loss.
+ */
 RTEMS_INLINE_ROUTINE bool _Processor_mask_Is_at_most_partial_loss(
   Processor_mask_Copy_status status
 )
@@ -244,6 +358,23 @@ RTEMS_INLINE_ROUTINE bool _Processor_mask_Is_at_most_partial_loss(
   return (unsigned int) status <= PROCESSOR_MASK_COPY_PARTIAL_LOSS;
 }
 
+/**
+ * @brief Copies one mask to another.
+ *
+ * @param[out] dst The destination of the copy operation.
+ * @param dst_size The size of @a dst.
+ * @param src The source of the copy operation.
+ * @param src_size The size of @a src.
+ *
+ * @retval PROCESSOR_MASK_COPY_LOSSLESS It is guaranteed that the copy
+ *      operation is lossless.
+ * @retval PROCESSOR_MASK_COPY_PARTIAL_LOSS Partial loss happened due
+ *      to the sizes of @a src and @a dst.
+ * @retval PROCESSOR_MASK_COPY_COMPLETE_LOSS Complete loss happened due
+ *      to the sizes of @a src and @a dst.
+ * @retval PROCESSOR_MASK_COPY_INVALID_SIZE One of the arguments sizes
+ *      is invalid (bigger than the size of a long).
+ */
 Processor_mask_Copy_status _Processor_mask_Copy(
   long       *dst,
   size_t      dst_size,
@@ -251,6 +382,22 @@ Processor_mask_Copy_status _Processor_mask_Copy(
   size_t      src_size
 );
 
+/**
+ * @brief Copies one mask to another.
+ *
+ * @param src The source for the copy operation.
+ * @param dst_size The size of @a dst.
+ * @param[out] dst The destination for the copy operation.
+ *
+ * @retval PROCESSOR_MASK_COPY_LOSSLESS It is guaranteed that the copy
+ *      operation is lossless.
+ * @retval PROCESSOR_MASK_COPY_PARTIAL_LOSS Partial loss happened due
+ *      to the sizes of @a src and @a dst.
+ * @retval PROCESSOR_MASK_COPY_COMPLETE_LOSS Complete loss happened due
+ *      to the sizes of @a src and @a dst.
+ * @retval PROCESSOR_MASK_COPY_INVALID_SIZE One of the arguments sizes
+ *      is invalid (bigger than the size of a long).
+ */
 RTEMS_INLINE_ROUTINE Processor_mask_Copy_status _Processor_mask_To_cpu_set_t(
   const Processor_mask *src,
   size_t                dst_size,
@@ -265,6 +412,22 @@ RTEMS_INLINE_ROUTINE Processor_mask_Copy_status _Processor_mask_To_cpu_set_t(
   );
 }
 
+/**
+ * @brief Copies one mask to another.
+ *
+ * @param src The source for the copy operation.
+ * @param src_size The size of @a src.
+ * @param[out] dst The destination for the copy operation.
+ *
+ * @retval PROCESSOR_MASK_COPY_LOSSLESS It is guaranteed that the copy
+ *      operation is lossless.
+ * @retval PROCESSOR_MASK_COPY_PARTIAL_LOSS Partial loss happened due
+ *      to the sizes of @a src and @a dst.
+ * @retval PROCESSOR_MASK_COPY_COMPLETE_LOSS Complete loss happened due
+ *      to the sizes of @a src and @a dst.
+ * @retval PROCESSOR_MASK_COPY_INVALID_SIZE One of the arguments sizes
+ *      is invalid (bigger than the size of a long).
+ */
 RTEMS_INLINE_ROUTINE Processor_mask_Copy_status _Processor_mask_From_cpu_set_t(
   Processor_mask  *dst,
   size_t           src_size,