Standardize order of arguments - destination is always last.

[apps/agl-service-can-low-level.git] / README.mkd

diff --git a/README.mkd b/README.mkd
index c6dfb43..439b3dd 100644 (file)
--- a/README.mkd
+++ b/README.mkd
@@ -1,15 +1,16 @@
-CAN Message Utilities for C
+Bitfield Utilities in 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.
+Network (CAN) message payloads or other bitfields.
 
 The header files contain complete function documentation, but to get you
 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;
@@ -20,14 +21,20 @@ 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);
+    uint64_t result = eightbyte_get_bitfield(data, 0, 1, false);
     // result == 0x1
 
     data = 0x0402574d555a0401;
-    result = get_bit_field(data, 16, 32, false);
+    result = eightbyte_get_bitfield(data, 16, 32, false);
     // result = 0x574d555a;
 
     data = 0x00000000F34DFCFF;
@@ -40,39 +47,37 @@ 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);
+    fail_unless(8byte_set_bitfield(1, 0, 1, &data));
+    uint64_t result = eightbyte_get_bitfield(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.
 
-    uint64_t payload = bitfield_encode_float(1, 1, 3, 1, 0)
+    uint64_t payload = eightbyte_encode_float(1, 1, 3, 1, 0)
     // payload == 0x1000000000000000
 
-    payload = bitfield_encode_bool(true, 1, 3);
+    payload = eightbyte_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.
 
     uint64_t payload = 0xeb00000000000000;
-    float float_result = bitfield_parse_float(payload,
+    float float_result = eightbyte_parse_float(payload,
             2, // starting bit
             4, // width of the signal's field
             1001.0, // transformation factor for the signal value
             -30000.0); // transformation offset for the signal value
     // float_result == -19990.0
 
-    bool bool_result = bitfield_parse_bool(payload,
+    bool bool_result = eightbyte_parse_bool(payload,
             0, // starting bit
             1, // width of the signal's field
             1.0, // transformation factor for the signal value
@@ -86,6 +91,11 @@ requires the unit testing library `check`.
 
     $ make test
 
+You can also see the test coverage if you have `lcov` installed and the
+`BROWSER` environment variable set to your choice of web browsers:
+
+    $ BROWSER=google-chrome-stable make coverage
+
 ## Authors
 
 Chris Peplin cpeplin@ford.com