From bc1baf25a0844861713829c0e9e69e4a2d447cc6 Mon Sep 17 00:00:00 2001 From: Christopher Peplin Date: Tue, 24 Dec 2013 10:56:35 -0500 Subject: [PATCH] Initial commit, pulled from openxc/vi-firmware. --- CHANGELOG.mkd | 5 ++ LICENSE | 24 ++++++ Makefile | 35 ++++++++ README.mkd | 18 ++++ runtests.sh | 17 ++++ src/bitfield/bitfield.c | 60 +++++++++++++ src/bitfield/bitfield.h | 58 +++++++++++++ src/canutil/read.c | 14 +++ src/canutil/read.h | 13 +++ src/canutil/write.c | 18 ++++ src/canutil/write.h | 13 +++ tests/bitfield_tests.c | 225 ++++++++++++++++++++++++++++++++++++++++++++++++ tests/tests.bin | Bin 0 -> 24728 bytes 13 files changed, 500 insertions(+) create mode 100644 CHANGELOG.mkd create mode 100644 LICENSE create mode 100644 Makefile create mode 100644 README.mkd create mode 100644 runtests.sh create mode 100644 src/bitfield/bitfield.c create mode 100644 src/bitfield/bitfield.h create mode 100644 src/canutil/read.c create mode 100644 src/canutil/read.h create mode 100644 src/canutil/write.c create mode 100644 src/canutil/write.h create mode 100644 tests/bitfield_tests.c create mode 100755 tests/tests.bin diff --git a/CHANGELOG.mkd b/CHANGELOG.mkd new file mode 100644 index 0000000..e710764 --- /dev/null +++ b/CHANGELOG.mkd @@ -0,0 +1,5 @@ +# CAN Message Utilities for C + +## v0.1 + +* Initial release diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..330d61f --- /dev/null +++ b/LICENSE @@ -0,0 +1,24 @@ +Copyright (c) 2013 Ford Motor Company +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + * Neither the name of the nor the + names of its contributors may be used to endorse or promote products + derived from this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL BE LIABLE FOR ANY +DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..8385c3a --- /dev/null +++ b/Makefile @@ -0,0 +1,35 @@ +CC = gcc +INCLUDES = -Isrc +CFLAGS = $(INCLUDES) -c -w -Wall -Werror -g -ggdb +LDFLAGS = +LDLIBS = -lcheck + +TEST_DIR = tests + +# Guard against \r\n line endings only in Cygwin +OSTYPE := $(shell uname) +ifneq ($(OSTYPE),Darwin) + OSTYPE := $(shell uname -o) + ifeq ($(OSTYPE),Cygwin) + TEST_SET_OPTS = igncr + endif +endif + +SRC = $(wildcard src/**/*.c) +OBJS = $(SRC:.c=.o) +TEST_SRC = $(wildcard $(TEST_DIR)/*.c) +TEST_OBJS = $(TEST_SRC:.c=.o) + +all: $(OBJS) + +test: $(TEST_DIR)/tests.bin + @set -o $(TEST_SET_OPTS) >/dev/null 2>&1 + @export SHELLOPTS + @sh runtests.sh $(TEST_DIR) + +$(TEST_DIR)/tests.bin: $(TEST_OBJS) $(OBJS) + @mkdir -p $(dir $@) + $(CC) $(LDFLAGS) $(CC_SYMBOLS) $(INCLUDES) -o $@ $^ $(LDLIBS) + +clean: + rm -rf **/*.o $(TEST_DIR)/*.bin diff --git a/README.mkd b/README.mkd new file mode 100644 index 0000000..0d8efb7 --- /dev/null +++ b/README.mkd @@ -0,0 +1,18 @@ +CAN Message Utilities for C +============ + +## Testing + +The library includes a test suite that uses the `check` C unit test library. + + $ make test + +## Authors + +Chris Peplin cpeplin@ford.com + +## License + +Copyright (c) 2013 Ford Motor Company + +Licensed under the BSD license. diff --git a/runtests.sh b/runtests.sh new file mode 100644 index 0000000..4781636 --- /dev/null +++ b/runtests.sh @@ -0,0 +1,17 @@ +echo "Running unit tests:" + +for i in $1/*.bin +do + if test -f $i + then + if ./$i + then + echo $i PASS + else + echo "ERROR in test $i:" + exit 1 + fi + fi +done + +echo "${txtbld}$(tput setaf 2)All unit tests passed.$(tput sgr0)" diff --git a/src/bitfield/bitfield.c b/src/bitfield/bitfield.c new file mode 100644 index 0000000..d383db0 --- /dev/null +++ b/src/bitfield/bitfield.c @@ -0,0 +1,60 @@ +#include + +/** + * Find the ending bit of a bitfield within the final byte. + * + * Returns: a bit position from 0 to 7. + */ +int findEndBit(int startBit, int numBits) { + int endBit = (startBit + numBits) % 8; + return endBit == 0 ? 8 : endBit; +} + +uint64_t bitmask(int numBits) { + return (((uint64_t)0x1) << numBits) - 1; +} + +int startingByte(int startBit) { + return startBit / 8; +} + +int endingByte(int startBit, int numBits) { + return (startBit + numBits - 1) / 8; +} + +uint64_t getBitField(uint64_t data, int startBit, int numBits, bool bigEndian) { + int startByte = startingByte(startBit); + int endByte = endingByte(startBit, numBits); + + if(!bigEndian) { + data = __builtin_bswap64(data); + } + uint8_t* bytes = (uint8_t*)&data; + uint64_t ret = bytes[startByte]; + if(startByte != endByte) { + // The lowest byte address contains the most significant bit. + int i; + for(i = startByte + 1; i <= endByte; i++) { + ret = ret << 8; + ret = ret | bytes[i]; + } + } + + ret >>= 8 - findEndBit(startBit, numBits); + return ret & bitmask(numBits); +} + +/** + * TODO it would be nice to have a warning if you call with this a value that + * won't fit in the number of bits you've specified it should use. + */ +void setBitField(uint64_t* data, uint64_t value, int startBit, int numBits) { + int shiftDistance = 64 - startBit - numBits; + value <<= shiftDistance; + *data &= ~(bitmask(numBits) << shiftDistance); + *data |= value; +} + +uint8_t nthByte(uint64_t source, int byteNum) { + return (source >> (64 - ((byteNum + 1) * 8))) & 0xFF; +} diff --git a/src/bitfield/bitfield.h b/src/bitfield/bitfield.h new file mode 100644 index 0000000..2776673 --- /dev/null +++ b/src/bitfield/bitfield.h @@ -0,0 +1,58 @@ +#ifndef __BITFIELD_H__ +#define __BITFIELD_H__ + +#include +#include + +/* Public: Reads a subset of bits from a byte array. + * + * 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. + * + * 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, 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 + * + * If the architecture where is code is running is little-endian, the input data + * will be swapped before grabbing the bit field. + * + * Examples + * + * uint64_t value = getBitField(data, 2, 4); + * + * Returns the value of the requested bit field. + */ +uint64_t getBitField(uint64_t data, int startPos, int numBits, bool bigEndian); + +/* 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). + */ +void setBitField(uint64_t* data, uint64_t value, int startPos, int numBits); + +/* 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. + * + * Returns the requested byte from the source bytes. + */ +uint8_t nthByte(uint64_t source, int byteNum); + +#endif // __BITFIELD_H__ diff --git a/src/canutil/read.c b/src/canutil/read.c new file mode 100644 index 0000000..6b4e40a --- /dev/null +++ b/src/canutil/read.c @@ -0,0 +1,14 @@ +#include + +float parseFloat(uint64_t data, uint8_t bitPosition, uint8_t bitSize, + float factor, float offset) { + uint64_t rawValue = getBitField(data, bitPosition, + bitSize, true); + return rawValue * factor + offset; +} + +bool parseBoolean(uint64_t data, uint8_t bitPosition, uint8_t bitSize, + float factor, float offset) { + float value = parseFloat(data, bitPosition, bitSize, factor, offset); + return value == 0.0 ? false : true; +} diff --git a/src/canutil/read.h b/src/canutil/read.h new file mode 100644 index 0000000..815f26b --- /dev/null +++ b/src/canutil/read.h @@ -0,0 +1,13 @@ +#ifndef __READ_H__ +#define __READ_H__ + +#include +#include + +float parseFloat(uint64_t data, uint8_t bitPosition, uint8_t bitSize, + float factor, float offset); + +bool parseBoolean(uint64_t data, uint8_t bitPosition, uint8_t bitSize, + float factor, float offset); + +#endif // __READ_H__ diff --git a/src/canutil/write.c b/src/canutil/write.c new file mode 100644 index 0000000..fdcba1f --- /dev/null +++ b/src/canutil/write.c @@ -0,0 +1,18 @@ +#include "write.h" + +uint64_t encodeFloat(float value, float offset, float factor, uint8_t bitPosition, + uint8_t bitSize) { + float rawValue = (value - offset) / factor; + if(rawValue > 0) { + // round up to avoid losing precision when we cast to an int + rawValue += 0.5; + } + uint64_t result = 0; + setBitField(&result, rawValue, bitPosition, bitSize); + return result; +} + +uint64_t encodeBoolean(bool value, float offset, float factor, + uint8_t bitPosition, uint8_t bitSize) { + return encodeFloat(value, offset, factor, bitPosition, bitSize); +} diff --git a/src/canutil/write.h b/src/canutil/write.h new file mode 100644 index 0000000..85a5c1a --- /dev/null +++ b/src/canutil/write.h @@ -0,0 +1,13 @@ +#ifndef __WRITE_H__ +#define __WRITE_H__ + +#include +#include + +uint64_t encodeFloat(float value, float offset, float factor, uint8_t bitPosition, + uint8_t bitSize); + +uint64_t encodeBoolean(bool value, float offset, float factor, + uint8_t bitPosition, uint8_t bitSize); + +#endif // __WRITE_H__ diff --git a/tests/bitfield_tests.c b/tests/bitfield_tests.c new file mode 100644 index 0000000..d248989 --- /dev/null +++ b/tests/bitfield_tests.c @@ -0,0 +1,225 @@ +#include +#include +#include + +START_TEST (test_large_bitmask) +{ + // yeah, this isn't a public method but I wanted to unit test it to track + // down a bug + extern uint64_t bitmask(int numBits); + uint64_t result = bitmask(32); + fail_if(result != 0xffffffff); +} +END_TEST + +START_TEST (test_one_bit_not_swapped) +{ + uint64_t data = 0x80; + uint64_t result = getBitField(data, 0, 1, false); + fail_if(result == 1); +} +END_TEST + +START_TEST (test_one_bit) +{ + uint64_t data = 0x8000000000000000; + uint64_t result = getBitField(data, 0, 1, false); + fail_unless(result == 0x1, + "First bits in 0x%X was 0x%X instead of 0x1", data, result); +} +END_TEST + +START_TEST (test_32_bit_parse) +{ + uint64_t data = 0x0402574d555a0401; + uint64_t result = getBitField(data, 16, 32, false); + uint64_t expectedValue = 0x574d555a; + fail_unless(result == expectedValue, + "Field retrieved in 0x%X was 0x%X instead of %d", data, + result, expectedValue); +} +END_TEST + +START_TEST (test_16_bit_parse) +{ + uint64_t data = 0xF34DFCFF00000000; + uint64_t result = getBitField(data, 16, 16, false); + uint64_t expectedValue = 0xFCFF; + fail_unless(result == expectedValue, + "Field retrieved in 0x%X was 0x%X instead of %d", data, + result, expectedValue); +} +END_TEST + +START_TEST (test_one_byte) +{ + uint64_t data = 0xFA00000000000000; + uint64_t result = getBitField(data, 0, 4, false); + fail_unless(result == 0xF, + "First 4 bits in 0x%X was 0x%X instead of 0xF", data, result); + result = getBitField(data, 4, 4, false); + fail_unless(result == 0xA, + "First 4 bits in 0x%X was 0x%X instead of 0xA", data, result); + result = getBitField(data, 0, 8, false); + fail_unless(result == 0xFA, + "All bits in 0x%X were 0x%X instead of 0x%X", data, result, data); +} +END_TEST + +START_TEST (test_multi_byte) +{ + uint64_t data = 0x12FA000000000000; + uint64_t result = getBitField(data, 0, 4, false); + fail_unless(result == 0x1, + "First 4 bits in 0x%X was 0x%X instead of 0xF", (data >> 60) & 0xF, + result); + result = getBitField(data, 4, 4, false); + fail_unless(result == 0x2, + "Second 4 bits in 0x%X was %d instead of 0xA", (data >> 56) & 0xF, + result); + result = getBitField(data, 8, 4, false); + fail_unless(result == 0xF, + "First 4 bits in 0x%X was %d instead of 0x1", (data >> 52) & 0xF, + result); + result = getBitField(data, 12, 4, false); + fail_unless(result == 0xA, + "Second 4 bits in 0x%X was %d instead of 0x2", (data >> 48) % 0xF, + result); +} +END_TEST + +START_TEST (test_get_multi_byte) +{ + uint64_t data = 0x12FA000000000000; + uint64_t result = getBitField(data, 0, 9, false); + ck_assert_int_eq(result, 0x25); +} +END_TEST + +START_TEST (test_get_off_byte_boundary) +{ + uint64_t data = 0x000012FA00000000; + uint64_t result = getBitField(data, 12, 8, false); + ck_assert_int_eq(result, 0x01); +} END_TEST + +START_TEST (test_set_field) +{ + uint64_t data = 0; + setBitField(&data, 1, 0, 1); + uint64_t result = getBitField(data, 0, 1, false); + ck_assert_int_eq(result, 0x1); + data = 0; + setBitField(&data, 1, 1, 1); + result = getBitField(data, 1, 1, false); + ck_assert_int_eq(result, 0x1); + + data = 0; + setBitField(&data, 0xf, 3, 4); + result = getBitField(data, 3, 4, false); + ck_assert_int_eq(result, 0xf); +} +END_TEST + +START_TEST (test_set_doesnt_clobber_existing_data) +{ + uint64_t data = 0xFFFC4DF300000000; + setBitField(&data, 0x4fc8, 16, 16); + uint64_t result = getBitField(data, 16, 16, false); + fail_unless(result == 0x4fc8, + "Field retrieved in 0x%X was 0x%X instead of 0x%X", data, result, + 0xc84f); + + data = 0x8000000000000000; + setBitField(&data, 1, 21, 1); + fail_unless(data == 0x8000040000000000LLU, + "Expected combined value 0x8000040000000000 but got 0x%X%X", + data >> 32, data); +} +END_TEST + +START_TEST (test_set_off_byte_boundary) +{ + uint64_t data = 0xFFFC4DF300000000; + setBitField(&data, 0x12, 12, 8); + uint64_t result = getBitField(data, 12, 12, false); + ck_assert_int_eq(result,0x12d); +} +END_TEST + +START_TEST (test_set_odd_number_of_bits) +{ + uint64_t data = 0xFFFC4DF300000000LLU; + setBitField(&data, 0x12, 11, 5); + uint64_t result = getBitField(data, 11, 5, false); + fail_unless(result == 0x12, + "Field set in 0x%X%X%X%X was %d instead of %d", data, result, + 0x12); + + data = 0xFFFC4DF300000000LLU; + setBitField(&data, 0x2, 11, 5); + result = getBitField(data, 11, 5, false); + fail_unless(result == 0x2, + "Field set in 0x%X%X%X%X was %d instead of %d", data, result, + 0x2); +} +END_TEST + +START_TEST(test_nth_byte) +{ + uint64_t data = 0x00000000F34DFCFF; + uint8_t result = nthByte(data, 0); + uint8_t expected = 0x0; + ck_assert_int_eq(result, expected); + + result = nthByte(data, 4); + expected = 0xF3; + ck_assert_int_eq(result, expected); + + result = nthByte(data, 5); + expected = 0x4D; + ck_assert_int_eq(result, expected); + + result = nthByte(data, 6); + expected = 0xFC; + ck_assert_int_eq(result, expected); + + result = nthByte(data, 7); + expected = 0xFF; + ck_assert_int_eq(result, expected); +} +END_TEST + +Suite* bitfieldSuite(void) { + Suite* s = suite_create("bitfield"); + TCase *tc_core = tcase_create("core"); + tcase_add_test(tc_core, test_large_bitmask); + tcase_add_test(tc_core, test_one_bit); + tcase_add_test(tc_core, test_one_bit_not_swapped); + tcase_add_test(tc_core, test_one_byte); + tcase_add_test(tc_core, test_16_bit_parse); + tcase_add_test(tc_core, test_32_bit_parse); + tcase_add_test(tc_core, test_multi_byte); + tcase_add_test(tc_core, test_get_multi_byte); + tcase_add_test(tc_core, test_get_off_byte_boundary); + tcase_add_test(tc_core, test_set_field); + tcase_add_test(tc_core, test_set_doesnt_clobber_existing_data); + tcase_add_test(tc_core, test_set_off_byte_boundary); + tcase_add_test(tc_core, test_set_odd_number_of_bits); + tcase_add_test(tc_core, test_nth_byte); + suite_add_tcase(s, tc_core); + + return s; +} + +int main(void) { + int numberFailed; + Suite* s = bitfieldSuite(); + SRunner *sr = srunner_create(s); + // Don't fork so we can actually use gdb + srunner_set_fork_status(sr, CK_NOFORK); + srunner_run_all(sr, CK_NORMAL); + numberFailed = srunner_ntests_failed(sr); + srunner_free(sr); + return (numberFailed == 0) ? 0 : 1; +} diff --git a/tests/tests.bin b/tests/tests.bin new file mode 100755 index 0000000000000000000000000000000000000000..5fd0916e8c57bdc25dd7bcbd2ea25ce90be0e75f GIT binary patch literal 24728 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