Clarify when you need to specify endianness.

3 files changed, 28 insertions, 31 deletions

diff --git a/README.mkd b/README.mkd
index 749b7995..59d5ae5d 100644
--- a/README.mkd
+++ b/README.mkd
@@ -9,6 +9,8 @@ started, here are examples using the API:
 
 ## Bitfield Manipulation
 
+The bitfields are stored in `uint8_t[]`.
+
     uint8_t data[4] = {0x12, 0x34, 0x56, 0x78};
     uint8_t result = get_byte(data, sizeof(data), 0);
     // result = 0x12;
@@ -19,7 +21,13 @@ started, here are examples using the API:
     // result[0] == 0x2
     // result[1] == 0x34
 
-## 8 Byte Bitfield Decoding
+## 8 Byte Helpers
+
+If you are dealing with 8 byte CAN messages as `uint64_t`, there are some
+additional functions prefixed with `eightbyte_` that may be faster or more
+useful.
+
+### 8 Byte Decoding
 
     uint64_t data = 0x8000000000000000;
     uint64_t result = get_bit_field(data, 0, 1, false);
@@ -39,16 +47,14 @@ started, here are examples using the API:
     result = eightbyte_get_nibble(data, 10, false);
     //result = 0x4;
 
-## 8 Byte Bitfield Encoding
+### 8 Byte Encoding
 
     uint64_t data = 0;
     fail_unless(set_bit_field(&data, 1, 0, 1));
     uint64_t result = get_bit_field(data, 0, 1, false);
     ck_assert_int_eq(result, 0x1);
 
-TODO setting bit fields is just copying
-
-## CAN Signal Encoding
+### CAN Signal Encoding
 
 The library supports encoding floating point CAN signals as well as booleans
 into a uint64_t payload.
@@ -59,7 +65,7 @@ into a uint64_t payload.
     payload = bitfield_encode_bool(true, 1, 3);
     // payload == 0x1000000000000000
 
-## CAN Signal Decoding
+### CAN Signal Decoding
 
 The library supports parsing floating point CAN signals as well as booleans.
 
diff --git a/src/bitfield/8byte.c b/src/bitfield/8byte.c
index e3eddf20..d3160934 100644
--- a/src/bitfield/8byte.c
+++ b/src/bitfield/8byte.c
@@ -11,24 +11,25 @@ uint64_t bitmask(const uint8_t bit_count) {
 }
 
 uint8_t eightbyte_get_nibble(const uint64_t source, const uint8_t nibble_index,
-        const bool big_endian) {
+        const bool data_is_big_endian) {
     return get_bit_field(source, NIBBLE_SIZE * nibble_index, NIBBLE_SIZE,
-            big_endian);
+            data_is_big_endian);
 }
 
-uint8_t eightbyte_get_byte(const uint64_t source, const uint8_t byte_index,
-        const bool big_endian) {
-    // TODO we're not handling swapped endianness - we could use get_bit_field
-    // but this might be more efficient
+uint8_t eightbyte_get_byte(uint64_t source, const uint8_t byte_index,
+        const bool data_is_big_endian) {
+    if(data_is_big_endian) {
+        source = __builtin_bswap64(source);
+    }
     return (source >> (EIGHTBYTE_BIT - ((byte_index + 1) * CHAR_BIT))) & 0xFF;
 }
 
 uint64_t get_bit_field(uint64_t source, const uint16_t offset,
-        const uint16_t bit_count, const bool big_endian) {
+        const uint16_t bit_count, const bool data_is_big_endian) {
     int startByte = offset / CHAR_BIT;
     int endByte = (offset + bit_count - 1) / CHAR_BIT;
 
-    if(!big_endian) {
+    if(!data_is_big_endian) {
         source = __builtin_bswap64(source);
     }
 
diff --git a/src/bitfield/8byte.h b/src/bitfield/8byte.h
index e4773a51..0abc1f07 100644
--- 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).
  * bit_count - the width of the bit field to extract.
- * big_endian - if the data passed in is little endian, set this to false and it
+ * 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:
@@ -47,32 +37,32 @@ extern "C" {
  * 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, const bool big_endian);
+        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.
- * big_endian - if the data passed in is little endian, set this to false and it
+ * 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 big_endian);
+                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.
- * big_endian - if the data passed in is little endian, set this to false and it
+ * 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 big_endian);
+                const bool data_is_big_endian);
 
 /* Public: Set the bit field in the given data array to the new value.
  *