From 32e25cbca210a359b09768537b6f443fe90a3070 Mon Sep 17 00:00:00 2001 From: Romain Forlot Date: Tue, 20 Jun 2017 10:24:05 +0000 Subject: Separation Generator to a dedicated repo Change-Id: Id94831651c3266861435272a6e36c7884bef2c45 Signed-off-by: Romain Forlot --- libs/bitfield-c/README.mkd | 107 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 libs/bitfield-c/README.mkd (limited to 'libs/bitfield-c/README.mkd') 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. -- cgit 1.2.3-korg