Uncrustify

[pes-rpp/rpp-lib.git] / rpp / include / binary.h

diff --git a/rpp/include/binary.h b/rpp/include/binary.h
index ddf05b9afd6d83212d4992c6526b2aa63d6c2a94..a72a8f064ff1453e9f3ed0e9d9ce5688684cd9d6 100644 (file)
--- a/rpp/include/binary.h
+++ b/rpp/include/binary.h
@@ -1,5 +1,6 @@
 /**
  * RPP binary handling header file.
+ * This file contains helpful macros for binary and bit manipulation.
  *
  * @file binary.h
  *
@@ -11,10 +12,141 @@
 #ifndef __RPP_BINARY_H
 #define __RPP_BINARY_H
 
+// Discussion about binary macros here:
+// http://www.avrfreaks.net/index.php?name=PNphpBB2&file=viewtopic&t=60729
+
+/**
+ * Create a bit mask for given bit number.
+ * For example:
+ *  - _BV(7) -> B[1000 0000]
+ *  - _BV(1) -> B[0000 0010]
+ *  - _BV(0) -> B[0000 0001]
+ *
+ * The function name stands for Bit Value, in reference that the mask is created
+ * only with the given bit number set.
+ *
+ * @param[in] bit       Bit number to create the mask, starting at 0 for the
+ *                      least-significant (rightmost) bit.
+ *
+ * @return A mask with all bits clear except the given bit number.
+ */
 #define _BV(bit) (1UL << (bit))
+
+/**
+ * Reads a bit of a number.
+ *
+ * @param[out] value    The number from which to read.
+ * @param[in] bit       Which bit number to read, starting at 0 for the
+ *                      least-significant (rightmost) bit.
+ *
+ * @return The value of the bit (0 or 1).
+ */
 #define bit_read(value, bit) (((value) >> (bit)) & 0x01)
+
+
+/**
+ * Sets (writes a 1 to) a bit of a numeric variable.
+ *
+ * @param[out] value    The numeric variable whose bit to set.
+ * @param[in] bit       Which bit number to set, starting at 0 for the
+ *                      least-significant (rightmost) bit
+ *
+ * @return None.
+ */
 #define bit_set(value, bit) ((value) |= (1UL << (bit)))
+
+
+/**
+ * Clears (writes a 0 to) a bit of a numeric variable.
+ *
+ * @param[out] value    The numeric variable whose bit to clear.
+ * @param[in] bit       Which bit number to clear, starting at 0 for the
+ *                      least-significant (rightmost) bit.
+ *
+ * @return None.
+ */
 #define bit_clear(value, bit) ((value) &= ~(1UL << (bit)))
+
+
+/**
+ * Writes a bit of a numeric variable.
+ *
+ * @param[out] value    The numeric variable to which to write.
+ * @param[in] bit       Which bit number to write, starting at 0 for the
+ *                      least-significant (rightmost) bit.
+ * @param[in] bit_value The value to write to the bit (0 or 1).
+ *
+ * @return None.
+ */
 #define bit_write(value, bit, bit_value) (bit_value ? bit_set(value, bit) : bit_clear(value, bit))
 
+
+/**
+ * Check if given numeric value has it's given bit number set.
+ *
+ * @param[in] value     The numeric variable to which bit check.
+ * @param[in] bit       Which bit number to check, starting at 0 for the
+ *                      least-significant (rightmost) bit.
+ *
+ * @return TRUE if bit is set, FALSE if not.
+ */
+#define is_bit_set(value, bit) (bit_read(value, bit) == 1)
+
+
+/**
+ * Check if given numeric value has it's given bit number clear.
+ *
+ * @param[in] value     The numeric variable to which bit check.
+ * @param[in] bit       Which bit number to check, starting at 0 for the
+ *                      least-significant (rightmost) bit.
+ *
+ * @return TRUE if bit is clear, FALSE if not.
+ */
+#define is_bit_clear(value, bit) (bit_read(value, bit) == 0)
+
+
+/**
+ * @brief Set value at position specified by mask.
+ *
+ * Macro for value setting into mask position.
+ * For example we want to get value 0x0040. We can use
+ * this macro with parameters: __val2mfld(0x00F0, 4)
+ */
+#define __val2mfld(mask,val) (((mask)&~((mask)<<1))*(val)&(mask))
+
+
+/**
+ * @brief Get value from position specified by mask.
+ *
+ * Macro for getting value from mask position.
+ * For example we have a value 0x1234 and we want get
+ * the second number value from the right. This macro
+ * can be used for this with parameters: __mfld2val(0x00F0, 0x1234)
+ * which will return 0x0030.
+ */
+#define __mfld2val(mask,val) (((val)&(mask))/((mask)&~((mask)<<1)))
+
+/**
+ * @brief Clear bits in mask position
+ *
+ * This macro clears all bits specified by the mask.
+ * For example the call __clrvalmsk(0x00F0, 0x1234) will
+ * return 0x1204.
+ */
+#define __clrvalmsk(mask, val) ((val) & ~(mask))
+
+/**
+ * @brief Insert value into mask position
+ *
+ * This macro inserts value into position specified by mask.
+ * All others bits are preserved, only masked bits are changed.
+ * For example:
+ *      int value = 0X1234;
+ *      int mask = 0x00F0;
+ *      value = __insval2mfld(mask, value, 4);
+ *  will change value into 0x1244;
+ */
+#define __insval2mfld(mask, value, val) (__clrvalmsk(mask, value) | \
+                                                                                __val2mfld(mask,val))
+
 #endif /* __RPP_BINARY_H */