[PATCH 40/98] doxygen: score: adjust doc in processormask.h to doxygen guidelines
Sebastian Huber
sebastian.huber at embedded-brains.de
Tue May 7 05:39:45 UTC 2019
From: Andreas Dachsberger <andreas.dachsberger at embedded-brains.de>
---
cpukit/include/rtems/score/processormask.h | 175 ++++++++++++++++++++++++++++-
1 file 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,
--
2.16.4
More information about the devel
mailing list