src/bitfield/bitfield.h

   1 #ifndef __BITFIELD_H__
   2 #define __BITFIELD_H__
   3
   4 #include <stdint.h>
   5 #include <stdbool.h>
   6
   7 #ifdef __cplusplus
   8 extern "C" {
   9 #endif
  10
  11 /* Public: Return a single nibble from the byte array, with range checking.
  12  *
  13  * source - the source byte array.
  14  * source_length - the total length of the source array.
  15  * nibble_index - the index of the nibble to retreive. The leftmost nibble is
  16  *      index 0.
  17  *
  18  * Returns the retreived nibble, right aligned in a uint8_t.
  19  */
  20 uint8_t getNibble(const uint8_t source[], const uint8_t source_length,
  21                 const uint8_t nibble_index);
  22
  23 /* Public: Return a single byte from the byte array, with range checking.
  24  *
  25  * source - the source byte array.
  26  * source_length - the total length of the source array.
  27  * byte_index - the index of the byte to retreive. The leftmost byte is index 0.
  28  *
  29  * Returns the retreived byte.
  30  */
  31 uint8_t getByte(const uint8_t source[], const uint8_t source_length,
  32         const uint8_t byte_index);
  33
  34 /* Public: Copy a range of bits from one bit array to another.
  35  *
  36  * The range does not need to be byte aligned, and the source and destination do
  37  * not have to be the same size (as long as the desitnation has enough room to
  38  * fit the range).
  39  *
  40  * A bit array with regards to this function always has the leftmost bit in byte
  41  * 0, i.e. bit index is the leftmost bit of byte 0. Endianness does not matter.
  42  *
  43  * For example:
  44  *
  45  *      uint8_t source[4] = {0x11, 0x22, 0x33, 0x44};
  46  *      uint8_t destination[4] = {0};
  47  *      copyBits(source, sizeof(source), 8, 8, destination,
  48  *              sizeof(destination), 0);
  49  *      // destination[0] == 0x22
  50  *      // destination[1] == 0x0
  51  *      // destination[2] == 0x0
  52  *      // destination[3] == 0x0
  53  *
  54  * Thanks to
  55  * http://stackoverflow.com/questions/3534535/whats-a-time-efficient-algorithm-to-copy-unaligned-bit-arrays
  56  * for the implementation of the algorithm.
  57  *
  58  * source_origin - the source array.
  59  * source_length - the total length of the source array in bytes,
  60  *      for range checking.
  61  * source_offset - an offset in bits to start the copy from the source array.
  62  *      Specify 0 to start from source_origin.
  63  * bit_count - the number of bits to copy.
  64  * destination_origin - the destination array.
  65  * desitnation_length - the total length of the destination array in bytes,
  66  *      for range checking.
  67  * destination_offset - an offset in bits to start placing the copied range into
  68  *      the destination array. Specify 0 to start from the beginning of the
  69  *      destination. If you are copying a range not aligned on a byte, you
  70  *      probably want to set this to a positive offset to right the resulting
  71  *      bits in the destination.
  72  *
  73  * Returns true if the copy was successful and false if the range exceeded the
  74  * size of the source or destination, or if the range size negative or 0.
  75  */
  76 bool copyBits(const uint8_t* source_origin, const uint16_t source_length,
  77         const uint16_t source_offset, uint16_t bit_count,
  78         uint8_t* destination_origin, const uint16_t destination_length,
  79         const uint16_t destination_offset);
  80
  81 /* Public: Copy a range of bits from one array to another, right aligning the
  82  * result.
  83  *
  84  * This is mostly useful if you want to cast the result to an integer type
  85  * instead of a byte array.
  86  *
  87  * For example:
  88  *
  89  *      uint8_t source[4] = {0x11, 0x22, 0x33, 0x44};
  90  *      uint8_t destination[4] = {0};
  91  *      copyBitsRightAligned(source, sizeof(source), 8, 8, destination,
  92  *              sizeof(destination));
  93  *      // destination[0] == 0x0
  94  *      // destination[1] == 0x0
  95  *      // destination[2] == 0x0
  96  *      // destination[3] == 0x22
  97  *
  98  *      int value = (int)destination;
  99  *      // value == 0x22 == 32
 100  *
 101  * The arguments are the same as copyBits, but without the destination_offset
 102  * option - that's set automatically to right align the result.
 103  *
 104  * Returns true if the copy was successful and false if the range exceeded the
 105  * size of the source or destination, or if the range size negative or 0.
 106  */
 107 bool copyBitsRightAligned(const uint8_t source[], const uint16_t source_length,
 108                 const uint16_t offset, const uint16_t bit_count,
 109                 uint8_t* destination, const uint16_t destination_length);
 110
 111 // TODO using uint64_t everywhere for CAN message payload is kind of cute, but
 112 // in actuality a CAN message may have a smaller payload, and it makes all of
 113 // these functions not applicable to other data sizes. It's also fairly
 114 // inefficient on 32-bit platforms. how much work is it to switch vi-firmware
 115 // to using uint8_t*?
 116
 117 /* Public: Reads a subset of bits from a byte array.
 118  *
 119  * data - the bytes in question.
 120  * startPos - the starting index of the bit field (beginning from 0).
 121  * numBits - the width of the bit field to extract.
 122  * bigEndian - if the data passed in is little endian, set this to false and it
 123  *      will be flipped before grabbing the bit field.
 124  *
 125  * Bit fields are positioned according to big-endian bit layout, but inside the
 126  * bit field, values are represented as little-endian. Therefore, to get the bit
 127  * field, we swap the overall byte order if bigEndian == false and
 128  * use the value we find in the field (assuming the embedded platform is little
 129  * endian).
 130  *
 131  * For example, the bit layout of the value "42" (i.e. 00101010 set at position
 132  * 14 with length 6 is:
 133  *
 134  *     000000000000001010100000000000000000000000000000000000000000000
 135  *
 136  * and the same value and position but with length 8 is:
 137  *
 138  *     000000000000000010101000000000000000000000000000000000000000000
 139  *
 140  * If the architecture where is code is running is little-endian, the input data
 141  * will be swapped before grabbing the bit field.
 142  *
 143  * Examples
 144  *
 145  *  uint64_t value = getBitField(data, 2, 4);
 146  *
 147  * Returns the value of the requested bit field.
 148  */
 149 uint64_t getBitField(uint64_t data, const uint16_t startPos,
 150         const uint16_t numBits, bool bigEndian);
 151
 152 /* Public: Set the bit field in the given data array to the new value.
 153  *
 154  * data - a byte array with size at least startPos + numBits.
 155  * value - the value to set in the bit field.
 156  * startPos - the starting index of the bit field (beginning from 0).
 157  */
 158 void setBitField(uint64_t* data, uint64_t value, const uint16_t startPos,
 159         const uint16_t numBits);
 160
 161 /* Public: Retreive the nth byte out of 8 bytes in a uint64_t.
 162  *
 163  * source - the source data to retreive the byte from.
 164  * byteNum - the index of the byte, starting at 0 and assuming big-endian order.
 165  *
 166  * Returns the requested byte from the source bytes.
 167  */
 168 uint8_t nthByte(const uint64_t source, const uint16_t byteNum);
 169
 170 #ifdef __cplusplus
 171 }
 172 #endif
 173
 174 #endif // __BITFIELD_H__