src/bitfield/8byte.h

   1 #ifndef __8BYTE_H__
   2 #define __8BYTE_H__
   3
   4 #include <stdint.h>
   5 #include <stdbool.h>
   6
   7 #ifdef __cplusplus
   8 extern "C" {
   9 #endif
  10
  11 // TODO using uint64_t everywhere for CAN message payload is kind of cute, but
  12 // in actuality a CAN message may have a smaller payload, and it makes all of
  13 // these functions not applicable to other data sizes. It's also fairly
  14 // inefficient on 32-bit platforms. how much work is it to switch vi-firmware
  15 // to using uint8_t*?
  16
  17 /* Public: Reads a subset of bits into a uint64_t.
  18  *
  19  * source - the bytes in question.
  20  * offset - the starting index of the bit field (beginning from 0).
  21  * bit_count - the width of the bit field to extract.
  22  * big_endian - if the data passed in is little endian, set this to false and it
  23  *      will be flipped before grabbing the bit field.
  24  *
  25  * Bit fields are positioned according to big-endian bit layout, but inside the
  26  * bit field, values are represented as little-endian. Therefore, to get the bit
  27  * field, we swap the overall byte order if big_endian == false and
  28  * use the value we find in the field (assuming the embedded platform is little
  29  * endian).
  30  *
  31  * For example, the bit layout of the value "42" (i.e. 00101010 set at position
  32  * 14 with length 6 is:
  33  *
  34  *     000000000000001010100000000000000000000000000000000000000000000
  35  *
  36  * and the same value and position but with length 8 is:
  37  *
  38  *     000000000000000010101000000000000000000000000000000000000000000
  39  *
  40  * If the architecture where is code is running is little-endian, the input data
  41  * will be swapped before grabbing the bit field.
  42  *
  43  * Examples
  44  *
  45  *  uint64_t value = get_bit_field(data, 2, 4);
  46  *
  47  * Returns the value of the requested bit field, right aligned in a uint64_t.
  48  */
  49 uint64_t get_bit_field(uint64_t source, const uint16_t offset,
  50         const uint16_t bit_count, const bool big_endian);
  51
  52 /* Public: Return a single nibble from the payload, with range checking.
  53  *
  54  * source - the source payload.
  55  * nibble_index - the index of the nibble to retreive. The leftmost nibble is
  56  *      index 0.
  57  * big_endian - if the data passed in is little endian, set this to false and it
  58  *      will be flipped before grabbing the bit field.
  59  *
  60  * Returns the retreived nibble, right aligned in a uint8_t.
  61  */
  62 uint8_t eightbyte_get_nibble(const uint64_t source, const uint8_t nibble_index,
  63                 const bool big_endian);
  64
  65 /* Public: Return a single byte from the payload, with range checking.
  66  *
  67  * source - the source byte array.
  68  * byte_index - the index of the byte to retreive. The leftmost byte is index 0.
  69  * big_endian - if the data passed in is little endian, set this to false and it
  70  *      will be flipped before grabbing the bit field.
  71  *
  72  * Returns the retreived byte.
  73  */
  74 uint8_t eightbyte_get_byte(const uint64_t source, const uint8_t byte_index,
  75                 const bool big_endian);
  76
  77 /* Public: Set the bit field in the given data array to the new value.
  78  *
  79  * destination - a byte array with size at least offset + bit_count.
  80  * value - the value to set in the bit field.
  81  * offset - the starting index of the bit field (beginning from 0).
  82  * bit_count - the number of bits to set in the data.
  83  *
  84  * Returns true if the bit_count is enough to fully represent the value, and
  85  *      false if it will not fit.
  86  */
  87 bool set_bit_field(uint64_t* destination, uint64_t value, const uint16_t offset,
  88         const uint16_t bit_count);
  89
  90 /* Public: Retreive the nth byte out of 8 bytes in a uint64_t.
  91  *
  92  * source - the source data to retreive the byte from.
  93  * byte_index - the index of the byte, starting at 0 and assuming big-endian order.
  94  *
  95  * Returns the requested byte from the source bytes.
  96  */
  97 uint8_t nth_byte(const uint64_t source, const uint16_t byte_index);
  98
  99 /* Private: Determine the index of the last bit used.
 100  */
 101 uint8_t find_end_bit(const uint16_t num_bits);
 102
 103 #ifdef __cplusplus
 104 }
 105 #endif
 106
 107 #endif // __8BYTE_H__