#include <stdint.h>
#include <stdbool.h>
+#define NIBBLE_SIZE (CHAR_BIT / 2)
+
#ifdef __cplusplus
extern "C" {
#endif
-uint8_t getNibble(const uint8_t nibble_index, const uint8_t data[],
- const uint8_t length);
+/* Public: Reads a subset of bits into a uint64_t, right aligned so they may be
+ * interpreted as a number.
+ *
+ * source - the bytes in question.
+ * source_size - the number of bytes in the source.
+ * offset - the starting index of the bit field (beginning from 0).
+ * bit_count - the width of the bit field to extract. This must be less than or
+ * equal to 64.
+ *
+ * Bit fields are positioned according to big-endian bit layout and the data is
+ * swapped automatically as necessary depending on the compiled architecture.
+ *
+ * For example, the bit layout of the value "42" (i.e. 00101010 set at position
+ * 14 with length 6 is:
+ *
+ * 000000000000001010100000000000000000000000000000000000000000000
+ *
+ * and the same value and position but with length 8 is:
+ *
+ * 000000000000000010101000000000000000000000000000000000000000000
+ *
+ * Examples
+ *
+ * uint64_t value = get_bitfield(data, data_size, 2, 4);
+ *
+ * Returns the value of the requested bit field, right aligned in a uint64_t.
+ */
+uint64_t get_bitfield(const uint8_t source[], const uint8_t source_length,
+ const uint16_t offset, const uint16_t bit_count);
-uint8_t getByte(const uint8_t byte_index, const uint8_t data[],
- const uint8_t length);
+/* Public: Return a single nibble from the byte array, with range checking.
+ *
+ * source - the source byte array.
+ * source_length - the total length of the source array.
+ * nibble_index - the index of the nibble to retreive. The leftmost nibble is
+ * index 0.
+ *
+ * Returns the retreived nibble, right aligned in a uint8_t.
+ */
+uint8_t get_nibble(const uint8_t source[], const uint8_t source_length,
+ const uint8_t nibble_index);
+
+/* Public: Return a single byte from the byte array, with range checking.
+ *
+ * source - the source byte array.
+ * source_length - the total length of the source array.
+ * byte_index - the index of the byte to retreive. The leftmost byte is index 0.
+ *
+ * Returns the retreived byte.
+ */
+uint8_t get_byte(const uint8_t source[], const uint8_t source_length,
+ const uint8_t byte_index);
/* Public: Copy a range of bits from one bit array to another.
*
* A bit array with regards to this function always has the leftmost bit in byte
* 0, i.e. bit index is the leftmost bit of byte 0. Endianness does not matter.
*
+ * For example:
+ *
+ * uint8_t source[4] = {0x11, 0x22, 0x33, 0x44};
+ * uint8_t destination[4] = {0};
+ * copy_bits(source, sizeof(source), 8, 8, destination,
+ * sizeof(destination), 0);
+ * // destination[0] == 0x22
+ * // destination[1] == 0x0
+ * // destination[2] == 0x0
+ * // destination[3] == 0x0
+ *
* Thanks to
* http://stackoverflow.com/questions/3534535/whats-a-time-efficient-algorithm-to-copy-unaligned-bit-arrays
* for the implementation of the algorithm.
* Returns true if the copy was successful and false if the range exceeded the
* size of the source or destination, or if the range size negative or 0.
*/
-bool copyBits(const uint8_t* source_origin, const uint16_t source_length,
+bool copy_bits(const uint8_t* source_origin, const uint16_t source_length,
const uint16_t source_offset, uint16_t bit_count,
uint8_t* destination_origin, const uint16_t destination_length,
const uint16_t destination_offset);
-bool copyBitsRightAligned(const uint8_t source[], const uint16_t source_length,
- const uint16_t offset, const uint16_t bit_count,
- uint8_t* destination, const uint16_t destination_length);
-
-// TODO using uint64_t everywhere for CAN message payload is kind of cute, but
-// in actuality a CAN message may have a smaller payload, and it makes all of
-// these functions not applicable to other data sizes. It's also fairly
-// inefficient on 32-bit platforms. how much work is it to switch vi-firmware
-// to using uint8_t*?
-
-/* Public: Reads a subset of bits from a byte array.
+/* Public: Copy a range of bits from one array to another, right aligning the
+ * result.
*
- * data - the bytes in question.
- * startPos - the starting index of the bit field (beginning from 0).
- * numBits - the width of the bit field to extract.
- * bigEndian - if the data passed in is little endian, set this to false and it
- * will be flipped before grabbing the bit field.
+ * This is mostly useful if you want to cast the result to an integer type
+ * instead of a byte array.
*
- * Bit fields are positioned according to big-endian bit layout, but inside the
- * bit field, values are represented as little-endian. Therefore, to get the bit
- * field, we swap the overall byte order if bigEndian == false and
- * use the value we find in the field (assuming the embedded platform is little
- * endian).
+ * For example:
*
- * For example, the bit layout of the value "42" (i.e. 00101010 set at position
- * 14 with length 6 is:
+ * uint8_t source[4] = {0x11, 0x22, 0x33, 0x44};
+ * uint8_t destination[4] = {0};
+ * copy_bits_right_aligned(source, sizeof(source), 8, 8, destination,
+ * sizeof(destination));
+ * // destination[0] == 0x0
+ * // destination[1] == 0x0
+ * // destination[2] == 0x0
+ * // destination[3] == 0x22
*
- * 000000000000001010100000000000000000000000000000000000000000000
+ * int value = (int)destination;
+ * // value == 0x22 == 32
*
- * and the same value and position but with length 8 is:
+ * The arguments are the same as copy_bits, but without the destination_offset
+ * option - that's set automatically to right align the result.
*
- * 000000000000000010101000000000000000000000000000000000000000000
+ * Returns true if the copy was successful and false if the range exceeded the
+ * size of the source or destination, or if the range size negative or 0.
+ */
+bool copy_bits_right_aligned(const uint8_t source[], const uint16_t source_length,
+ const uint16_t offset, const uint16_t bit_count,
+ uint8_t* destination, const uint16_t destination_length);
+
+/* Public: Copy a range of bytes from one byte array to another.
*
- * If the architecture where is code is running is little-endian, the input data
- * will be swapped before grabbing the bit field.
+ * The source and destination do not have to be the same size (as long as the
+ * desitnation has enough room to fit the range).
*
- * Examples
+ * source_origin - the source array.
+ * source_length - the total length of the source array in bytes,
+ * for range checking.
+ * source_offset - a byte offset to start the copy from the source array.
+ * Specify 0 to start from source_origin.
+ * byte_count - the number of bytes to copy.
+ * destination_origin - the destination array.
+ * desitnation_length - the total length of the destination array in bytes,
+ * for range checking.
+ * destination_offset - an offset in bytes to start placing the copied range into
+ * the destination array. Specify 0 to start from the beginning of the
+ * destination.
*
- * uint64_t value = getBitField(data, 2, 4);
+ * Returns true if the copy was successful and false if the range exceeded the
+ * size of the source or destination, or if the range size negative or 0.
+ */
+bool copy_bytes_right_aligned(const uint8_t source[], const uint16_t source_length,
+ const uint16_t offset, const uint16_t byte_count,
+ uint8_t* destination, const uint16_t destination_length);
+
+/* Public: Set the a nibble in the given data array to the new value.
+ *
+ * nibble_index - the index of the nibble to retreive. The leftmost nibble is
+ * index 0.
+ * value - the value to set in the bit field.
+ * destination - the destination array.
+ * destination_length - the total length of the destination array in bytes,
+ * for range checking.
*
- * Returns the value of the requested bit field.
+ * Returns true if the bit_count is enough to fully represent the value, and
+ * false if it will not fit.
*/
-uint64_t getBitField(uint64_t data, const uint16_t startPos,
- const uint16_t numBits, bool bigEndian);
+bool set_nibble(const uint16_t nibble_index, const uint8_t value,
+ uint8_t* destination, const uint16_t destination_length);
/* Public: Set the bit field in the given data array to the new value.
*
- * data - a byte array with size at least startPos + numBits.
* value - the value to set in the bit field.
- * startPos - the starting index of the bit field (beginning from 0).
+ * offset - the starting index of the bit field (beginning from 0).
+ * bit_count - the number of bits to set in the data.
+ * destination - the destination array.
+ * destination_length - the total length of the destination array in bytes,
+ * for range checking.
+ *
+ * Returns true if the bit_count is enough to fully represent the value, and
+ * false if it will not fit.
*/
-void setBitField(uint64_t* data, uint64_t value, const uint16_t startPos,
- const uint16_t numBits);
+bool set_bitfield(const uint64_t value, const uint16_t offset,
+ const uint16_t bit_count, uint8_t destination[],
+ uint16_t destination_length);
-/* Public: Retreive the nth byte out of 8 bytes in a uint64_t.
- *
- * source - the source data to retreive the byte from.
- * byteNum - the index of the byte, starting at 0 and assuming big-endian order.
+/* Public: Return a right aligned bitmask for a uint64_t.
*
- * Returns the requested byte from the source bytes.
+ * bit_count - the number of bits to mask, right aligned.
+ */
+uint64_t bitmask(const uint8_t bit_count);
+
+/* Private:
+ */
+uint16_t bits_to_bytes(uint32_t bits);
+
+/* Private: A union to assist swapping between uint64_t and a uint8_t array.
*/
-uint8_t nthByte(const uint64_t source, const uint16_t byteNum);
+typedef union {
+ uint64_t whole;
+ uint8_t bytes[sizeof(uint64_t)];
+} ArrayOrBytes;
#ifdef __cplusplus
}