summaryrefslogtreecommitdiffstats
path: root/libs/bitfield-c/README.mkd
diff options
context:
space:
mode:
Diffstat (limited to 'libs/bitfield-c/README.mkd')
-rw-r--r--libs/bitfield-c/README.mkd107
1 files changed, 107 insertions, 0 deletions
diff --git a/libs/bitfield-c/README.mkd b/libs/bitfield-c/README.mkd
new file mode 100644
index 00000000..439b3dd0
--- /dev/null
+++ b/libs/bitfield-c/README.mkd
@@ -0,0 +1,107 @@
+Bitfield Utilities in C
+===========================
+
+This is a C library with functions to help encode and decode Controller Area
+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;
+ result = get_nibble(data, sizeof(data), 0);
+ // result = 0x1;
+ bool success = copy_bits_right_aligned(data, 4, 4, 12, result, 4)
+ // success == true
+ // result[0] == 0x2
+ // result[1] == 0x34
+
+## 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 = eightbyte_get_bitfield(data, 0, 1, false);
+ // result == 0x1
+
+ data = 0x0402574d555a0401;
+ result = eightbyte_get_bitfield(data, 16, 32, false);
+ // result = 0x574d555a;
+
+ data = 0x00000000F34DFCFF;
+ result = eightbyte_get_byte(data, 0, false);
+ //result = 0x0
+
+ result = eightbyte_get_byte(data, 4, false);
+ //result = 0xF3
+
+ result = eightbyte_get_nibble(data, 10, false);
+ //result = 0x4;
+
+### 8 Byte Encoding
+
+ uint64_t data = 0;
+ 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);
+
+### CAN Signal Encoding
+
+The library supports encoding floating point CAN signals as well as booleans
+into a uint64_t payload.
+
+ uint64_t payload = eightbyte_encode_float(1, 1, 3, 1, 0)
+ // payload == 0x1000000000000000
+
+ payload = eightbyte_encode_bool(true, 1, 3);
+ // payload == 0x1000000000000000
+
+### CAN Signal Decoding
+
+The library supports parsing floating point CAN signals as well as booleans.
+
+ uint64_t payload = 0xeb00000000000000;
+ 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 = eightbyte_parse_bool(payload,
+ 0, // starting bit
+ 1, // width of the signal's field
+ 1.0, // transformation factor for the signal value
+ 0); // transformation offset for the signal value
+ // bool_result == true
+
+## Testing
+
+The library includes a test suite that uses the `check` C unit test library. It
+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
+
+## License
+
+Copyright (c) 2013 Ford Motor Company
+
+Licensed under the BSD license.