Standardize order of arguments - destination is always last.

[apps/agl-service-can-low-level.git] / src / bitfield / 8byte.h

diff --git a/src/bitfield/8byte.h b/src/bitfield/8byte.h
index 36b5fe6..0451269 100644 (file)
--- a/src/bitfield/8byte.h
+++ b/src/bitfield/8byte.h
@@ -8,25 +8,15 @@
 extern "C" {
 #endif
 
-// TODO using uint64_t everywhere for CAN message payload is kind of cute, but
-// in actuality a CAN message may have a smaller payload, and it makes all of
-// these functions not applicable to other data sizes. It's also fairly
-// inefficient on 32-bit platforms. how much work is it to switch vi-firmware
-// to using uint8_t*?
-
 /* Public: Reads a subset of bits into a uint64_t.
  *
  * source - the bytes in question.
  * offset - the starting index of the bit field (beginning from 0).
- * numBits - the width of the bit field to extract.
- * big_endian - if the data passed in is little endian, set this to false and it
+ * bit_count - the width of the bit field to extract.
+ * data_is_big_endian - if the data passed in is little endian, set this to false and it
  *      will be flipped before grabbing the bit field.
  *
- * Bit fields are positioned according to big-endian bit layout, but inside the
- * bit field, values are represented as little-endian. Therefore, to get the bit
- * field, we swap the overall byte order if big_endian == false and
- * use the value we find in the field (assuming the embedded platform is little
- * endian).
+ * Bit fields are positioned according to big-endian bit layout.
  *
  * For example, the bit layout of the value "42" (i.e. 00101010 set at position
  * 14 with length 6 is:
@@ -42,12 +32,37 @@ extern "C" {
  *
  * Examples
  *
- *  uint64_t value = get_bit_field(data, 2, 4);
+ *  uint64_t value = get_bitfield(data, 2, 4);
  *
- * Returns the value of the requested bit field.
+ * Returns the value of the requested bit field, right aligned in a uint64_t.
  */
-uint64_t get_bit_field(uint64_t source, const uint16_t offset,
-        const uint16_t bit_count, bool big_endian);
+uint64_t eightbyte_get_bitfield(uint64_t source, const uint16_t offset,
+        const uint16_t bit_count, const bool data_is_big_endian);
+
+/* Public: Return a single nibble from the payload, with range checking.
+ *
+ * source - the source payload.
+ * nibble_index - the index of the nibble to retreive. The leftmost nibble is
+ *      index 0.
+ * data_is_big_endian - if the data passed in is little endian, set this to false and it
+ *      will be flipped before grabbing the bit field.
+ *
+ * Returns the retreived nibble, right aligned in a uint8_t.
+ */
+uint8_t eightbyte_get_nibble(const uint64_t source, const uint8_t nibble_index,
+        const bool data_is_big_endian);
+
+/* Public: Return a single byte from the payload, with range checking.
+ *
+ * source - the source byte array.
+ * byte_index - the index of the byte to retreive. The leftmost byte is index 0.
+ * data_is_big_endian - if the data passed in is little endian, set this to false and it
+ *      will be flipped before grabbing the bit field.
+ *
+ * Returns the retreived byte.
+ */
+uint8_t eightbyte_get_byte(const uint64_t source, const uint8_t byte_index,
+        const bool data_is_big_endian);
 
 /* Public: Set the bit field in the given data array to the new value.
  *
@@ -59,17 +74,12 @@ uint64_t get_bit_field(uint64_t source, const uint16_t offset,
  * Returns true if the bit_count is enough to fully represent the value, and
  *      false if it will not fit.
  */
-bool set_bit_field(uint64_t* destination, uint64_t value, const uint16_t offset,
-        const uint16_t bit_count);
+bool eightbyte_set_bitfield(uint64_t value,
+        const uint16_t offset, const uint16_t bit_count, uint64_t* destination);
 
-/* Public: Retreive the nth byte out of 8 bytes in a uint64_t.
- *
- * source - the source data to retreive the byte from.
- * byte_index - the index of the byte, starting at 0 and assuming big-endian order.
- *
- * Returns the requested byte from the source bytes.
+/* Private: Determine the index of the last bit used.
  */
-uint8_t nth_byte(const uint64_t source, const uint16_t byte_index);
+uint8_t find_end_bit(const uint16_t num_bits);
 
 #ifdef __cplusplus
 }