libutils: util.h: add usage description to {get,set}_field_u{32,64}()

Added comments to get_field_u{32,64}() and set_field_u{32,64}() to
improve understanding and reduce errors.

Signed-off-by: Maxime Méré <[email protected]>

lib/libutils/ext/include/util.h

@@ -188,7 +188,34 @@ static inline void reg_pair_from_64(uint64_t val, uint32_t *reg0,
 	*reg1 = low32_from_64(val);
 }
 
-/* Get and set bit fields  */
+/*
+ * Functions to get and set bit fields in a 32/64-bit register.
+ *
+ * These helper functions allow setting and extracting specific bits in
+ * a bitfield @reg according to a given mask @mask. The mask
+ * specifies which bits in the register should be updated or extracted.
+ * These functions exist in both 32-bit and 64-bit versions
+ *
+ * set_field_u32() / set_field_u64() - Modifies specific bits in a
+ * bitfield by clearing the bits specified by the mask and then setting
+ * these bits to the new value @val.
+ * @reg:  The original 32-bit or 64-bit bitfield value.
+ * @mask: A bitmask indicating which bits in the bitfield should be
+ *	  updated or extracted.
+ * @val:  The new value to be inserted into the bitfield at the
+ *	  positions specified by the mask.
+ * Returns the updated bitfield value with the specified bits set to
+ * the new value.
+ *
+ * get_field_u32() / get_field_u64() - Extracts the value of specific
+ * bits in a bitfield by isolating the bits specified by the mask and
+ * then shifting them to the rightmost position.
+ * @reg:  The original 32-bit or 64-bit bitfield value.
+ * @mask: A bitmask indicating which bits in the bitfield should be
+ *	  updated or extracted.
+ * Returns the value of the bits specified by the mask, shifted to the
+ * rightmost position.
+ */
 static inline uint32_t get_field_u32(uint32_t reg, uint32_t mask)
 {
 	return (reg & mask) / (mask & ~(mask - 1));