Document all bitfield functions.

diff --git a/README.mkd b/README.mkd
index b96d587..76feddb 100644 (file)
--- a/README.mkd
+++ b/README.mkd
@@ -1,5 +1,12 @@
 CAN Message Utilities for C
-============
+===========================
+
+This is a C library with functions to help encode and decode Controller Area
+Network (CAN) message payloads. Some of the bitfield functions may be useful for
+other areas, too.
+
+The header files contain complete function documentation, but to get you
+started, here are examples using the API:
 
 ## Bitfield Manipulation
 
@@ -8,11 +15,31 @@ CAN Message Utilities for C
     uint8_t result = getNibble(data, sizeof(data), 0);
     fail_unless(copyBitsRightAligned(data, 4, 4, 12, result, 4));
 
-## 8 Byte Bitfield Manipulation
+## 8 Byte Bitfield Decoding
+
+    uint64_t data = 0x8000000000000000;
+    uint64_t result = get_bit_field(data, 0, 1, false);
+    // result == 0x1
+
+    data = 0x0402574d555a0401;
+    result = get_bit_field(data, 16, 32, false);
+    // result = 0x574d555a;
+
+    data = 0x00000000F34DFCFF;
+    result = nth_byte(data, 0);
+    //result = 0x0
+
+    result = nth_byte(data, 4);
+    //result = 0xF3
+
+## 8 Byte Bitfield 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
-TODO bring back old uint64_t implementation of getBitField if it's faster /
-    simpler
 
 ## CAN Signal Encoding
 

diff --git a/src/bitfield/8byte.c b/src/bitfield/8byte.c
index 3b6b546..845be8c 100644 (file)
--- a/src/bitfield/8byte.c
+++ b/src/bitfield/8byte.c
@@ -18,26 +18,28 @@ static uint16_t bits_to_bytes(uint32_t bits) {
     return byte_count;
 }
 
-uint64_t get_bit_field(uint64_t source, const uint16_t startBit,
+uint64_t get_bit_field(uint64_t source, const uint16_t offset,
         const uint16_t bit_count, bool big_endian) {
-    uint8_t result[8] = {0};
+    int startByte = offset / CHAR_BIT;
+    int endByte = (offset + bit_count - 1) / CHAR_BIT;
+
     if(!big_endian) {
         source = __builtin_bswap64(source);
     }
-    copyBitsRightAligned((const uint8_t*)&source, sizeof(source), startBit,
-            bit_count, result, sizeof(result));
-    uint64_t int_result = 0;
 
-    if(!big_endian) {
-        // we need to swap the byte order of the array to get it into a
-        // uint64_t, but it's been right aligned so we have to be more careful
-        for(int i = 0; i < bits_to_bytes(bit_count); i++) {
-            int_result |= result[bits_to_bytes(bit_count) - i - 1] << (CHAR_BIT * i);
+    uint8_t* bytes = (uint8_t*)&source;
+    uint64_t ret = bytes[startByte];
+    if(startByte != endByte) {
+        // The lowest byte address contains the most significant bit.
+        int i;
+        for(i = startByte + 1; i <= endByte; i++) {
+            ret = ret << 8;
+            ret = ret | bytes[i];
         }
-    } else {
-        int_result = *(uint64_t*)result;
     }
-    return int_result;
+
+    ret >>= 8 - find_end_bit(offset + bit_count);
+    return ret & bitmask(bit_count);
 }
 
 bool set_bit_field(uint64_t* destination, uint64_t value, const uint16_t offset,

diff --git a/src/bitfield/8byte.h b/src/bitfield/8byte.h
index 36b5fe6..1ee9c0e 100644 (file)
--- a/src/bitfield/8byte.h
+++ b/src/bitfield/8byte.h
@@ -18,7 +18,7 @@ extern "C" {
  *
  * 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.
+ * 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
  *      will be flipped before grabbing the bit field.
  *
@@ -44,7 +44,7 @@ extern "C" {
  *
  *  uint64_t value = get_bit_field(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);
@@ -71,6 +71,10 @@ bool set_bit_field(uint64_t* destination, uint64_t value, const uint16_t offset,
  */
 uint8_t nth_byte(const uint64_t source, const uint16_t byte_index);
 
+/* Private: Determine the index of the last bit used.
+ */
+uint8_t find_end_bit(const uint16_t num_bits);
+
 #ifdef __cplusplus
 }
 #endif

diff --git a/src/bitfield/bitarray.c b/src/bitfield/bitarray.c
index 8fbc941..f8c2352 100644 (file)
--- a/src/bitfield/bitarray.c
+++ b/src/bitfield/bitarray.c
@@ -113,7 +113,7 @@ bool copyBits(const uint8_t* source_origin, const uint16_t source_length,
  *
  * Returns: a bit position from 0 to 7.
  */
-static uint8_t findEndBit(const uint16_t startBit, const uint16_t numBits) {
+uint8_t find_end_bit(const uint16_t numBits) {
     int endBit = numBits % CHAR_BIT;
     return endBit == 0 ? CHAR_BIT : endBit;
 }
@@ -125,5 +125,5 @@ bool copyBitsRightAligned(const uint8_t source[], const uint16_t source_length,
             destination_length,
             // provide a proper destination offset so the result is right
             // aligned
-            CHAR_BIT - findEndBit(offset, bit_count));
+            CHAR_BIT - find_end_bit(bit_count));
 }

diff --git a/tests/8byte_tests.c b/tests/8byte_tests.c
index 64c1a39..6166f1d 100644 (file)
--- a/tests/8byte_tests.c
+++ b/tests/8byte_tests.c
@@ -56,10 +56,10 @@ START_TEST (test_one_byte)
     uint64_t data = 0xFA00000000000000;
     uint64_t result = get_bit_field(data, 0, 4, false);
     fail_unless(result == 0xF,
-            "First 4 bits in 0x%llx was 0x%llx instead of 0xF", data, result);
+            "First nibble in 0x%llx was 0x%llx instead of 0xF", data, result);
     result = get_bit_field(data, 4, 4, false);
     fail_unless(result == 0xA,
-            "First 4 bits in 0x%llx was 0x%llx instead of 0xA", data, result);
+            "Second nibble in 0x%llx was 0x%llx instead of 0xA", data, result);
     result = get_bit_field(data, 0, 8, false);
     fail_unless(result == 0xFA,
             "All bits in 0x%llx were 0x%llx instead of 0x%llx", data, result, data);