libs/bitfield-c/README.mkd

   1 Bitfield Utilities in C
   2 ===========================
   3
   4 This is a C library with functions to help encode and decode Controller Area
   5 Network (CAN) message payloads or other bitfields.
   6
   7 The header files contain complete function documentation, but to get you
   8 started, here are examples using the API:
   9
  10 ## Bitfield Manipulation
  11
  12 The bitfields are stored in `uint8_t[]`.
  13
  14     uint8_t data[4] = {0x12, 0x34, 0x56, 0x78};
  15     uint8_t result = get_byte(data, sizeof(data), 0);
  16     // result = 0x12;
  17     result = get_nibble(data, sizeof(data), 0);
  18     // result = 0x1;
  19     bool success = copy_bits_right_aligned(data, 4, 4, 12, result, 4)
  20     // success == true
  21     // result[0] == 0x2
  22     // result[1] == 0x34
  23
  24 ## 8 Byte Helpers
  25
  26 If you are dealing with 8 byte CAN messages as `uint64_t`, there are some
  27 additional functions prefixed with `eightbyte_` that may be faster or more
  28 useful.
  29
  30 ### 8 Byte Decoding
  31
  32     uint64_t data = 0x8000000000000000;
  33     uint64_t result = eightbyte_get_bitfield(data, 0, 1, false);
  34     // result == 0x1
  35
  36     data = 0x0402574d555a0401;
  37     result = eightbyte_get_bitfield(data, 16, 32, false);
  38     // result = 0x574d555a;
  39
  40     data = 0x00000000F34DFCFF;
  41     result = eightbyte_get_byte(data, 0, false);
  42     //result = 0x0
  43
  44     result = eightbyte_get_byte(data, 4, false);
  45     //result = 0xF3
  46
  47     result = eightbyte_get_nibble(data, 10, false);
  48     //result = 0x4;
  49
  50 ### 8 Byte Encoding
  51
  52     uint64_t data = 0;
  53     fail_unless(8byte_set_bitfield(1, 0, 1, &data));
  54     uint64_t result = eightbyte_get_bitfield(data, 0, 1, false);
  55     ck_assert_int_eq(result, 0x1);
  56
  57 ### CAN Signal Encoding
  58
  59 The library supports encoding floating point CAN signals as well as booleans
  60 into a uint64_t payload.
  61
  62     uint64_t payload = eightbyte_encode_float(1, 1, 3, 1, 0)
  63     // payload == 0x1000000000000000
  64
  65     payload = eightbyte_encode_bool(true, 1, 3);
  66     // payload == 0x1000000000000000
  67
  68 ### CAN Signal Decoding
  69
  70 The library supports parsing floating point CAN signals as well as booleans.
  71
  72     uint64_t payload = 0xeb00000000000000;
  73     float float_result = eightbyte_parse_float(payload,
  74             2, // starting bit
  75             4, // width of the signal's field
  76             1001.0, // transformation factor for the signal value
  77             -30000.0); // transformation offset for the signal value
  78     // float_result == -19990.0
  79
  80     bool bool_result = eightbyte_parse_bool(payload,
  81             0, // starting bit
  82             1, // width of the signal's field
  83             1.0, // transformation factor for the signal value
  84             0); // transformation offset for the signal value
  85     // bool_result == true
  86
  87 ## Testing
  88
  89 The library includes a test suite that uses the `check` C unit test library. It
  90 requires the unit testing library `check`.
  91
  92     $ make test
  93
  94 You can also see the test coverage if you have `lcov` installed and the
  95 `BROWSER` environment variable set to your choice of web browsers:
  96
  97     $ BROWSER=google-chrome-stable make coverage
  98
  99 ## Authors
 100
 101 Chris Peplin cpeplin@ford.com
 102
 103 ## License
 104
 105 Copyright (c) 2013 Ford Motor Company
 106
 107 Licensed under the BSD license.