X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=blobdiff_plain;f=src%2Fbitfield%2Fbitfield.h;h=df92639a9587ba281f00c185668a9af24f390f99;hb=7f1d5473842361f97fef886bc4e98949ecf853b6;hp=bf5c9b7d2795f659ab223c15d991c297b53038f4;hpb=6830d35b449141305f137f78f09c2b879bfb9b33;p=apps%2Flow-level-can-service.git diff --git a/src/bitfield/bitfield.h b/src/bitfield/bitfield.h index bf5c9b7..df92639 100644 --- a/src/bitfield/bitfield.h +++ b/src/bitfield/bitfield.h @@ -4,15 +4,64 @@ #include #include +#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. * @@ -23,6 +72,17 @@ uint8_t getByte(const uint8_t byte_index, const uint8_t data[], * 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. @@ -45,73 +105,113 @@ uint8_t getByte(const uint8_t byte_index, const uint8_t data[], * 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 }