From acdb99ebaea6a35966a35dbf429d4585ade19030 Mon Sep 17 00:00:00 2001 From: Andreas Dachsberger Date: Thu, 11 Apr 2019 08:57:09 +0200 Subject: doxygen: score: adjust doc in processormask.h to doxygen guidelines Update #3706. --- 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, -- cgit v1.2.3