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     uint8_t data[4] = {0x12, 0x34, 0x56, 0x78};
  13     uint8_t result = get_byte(data, sizeof(data), 0);
  14     // result = 0x12;
  15     result = get_nibble(data, sizeof(data), 0);
  16     // result = 0x1;
  17     bool success = copy_bits_right_aligned(data, 4, 4, 12, result, 4)
  18     // success == true
  19     // result[0] == 0x2
  20     // result[1] == 0x34
  21
  22 ## 8 Byte Bitfield Decoding
  23
  24     uint64_t data = 0x8000000000000000;
  25     uint64_t result = get_bit_field(data, 0, 1, false);
  26     // result == 0x1
  27
  28     data = 0x0402574d555a0401;
  29     result = get_bit_field(data, 16, 32, false);
  30     // result = 0x574d555a;
  31
  32     data = 0x00000000F34DFCFF;
  33     result = eightbyte_get_byte(data, 0, false);
  34     //result = 0x0
  35
  36     result = eightbyte_get_byte(data, 4, false);
  37     //result = 0xF3
  38
  39     result = eightbyte_get_nibble(data, 10, false);
  40     //result = 0x4;
  41
  42 ## 8 Byte Bitfield Encoding
  43
  44     uint64_t data = 0;
  45     fail_unless(set_bit_field(&data, 1, 0, 1));
  46     uint64_t result = get_bit_field(data, 0, 1, false);
  47     ck_assert_int_eq(result, 0x1);
  48
  49 TODO setting bit fields is just copying
  50
  51 ## CAN Signal Encoding
  52
  53 The library supports encoding floating point CAN signals as well as booleans
  54 into a uint64_t payload.
  55
  56     uint64_t payload = bitfield_encode_float(1, 1, 3, 1, 0)
  57     // payload == 0x1000000000000000
  58
  59     payload = bitfield_encode_bool(true, 1, 3);
  60     // payload == 0x1000000000000000
  61
  62 ## CAN Signal Decoding
  63
  64 The library supports parsing floating point CAN signals as well as booleans.
  65
  66     uint64_t payload = 0xeb00000000000000;
  67     float float_result = bitfield_parse_float(payload,
  68             2, // starting bit
  69             4, // width of the signal's field
  70             1001.0, // transformation factor for the signal value
  71             -30000.0); // transformation offset for the signal value
  72     // float_result == -19990.0
  73
  74     bool bool_result = bitfield_parse_bool(payload,
  75             0, // starting bit
  76             1, // width of the signal's field
  77             1.0, // transformation factor for the signal value
  78             0); // transformation offset for the signal value
  79     // bool_result == true
  80
  81 ## Testing
  82
  83 The library includes a test suite that uses the `check` C unit test library. It
  84 requires the unit testing library `check`.
  85
  86     $ make test
  87
  88 ## Authors
  89
  90 Chris Peplin cpeplin@ford.com
  91
  92 ## License
  93
  94 Copyright (c) 2013 Ford Motor Company
  95
  96 Licensed under the BSD license.