ericherman / libeba Goto Github PK

LibEBA Embedable Bit Array
--------------------------

An implementation suitable for small CPUs.


Usage:
------

	/* create a bit array for our 16 bit flags: */
	struct eba *eba = NULL;
	eba = eba_new(16);

	/* alternatively, choose an endian-ness of the bits */
	eba *eba_new_endian(15, eba_big_endian);

	/* set bits 2 and 5 to 1 */
	eba_set(eba, 2, 1);
	eba_set(eba, 5, 1);

	/* check a value */
	if (eba_get(eba, index)) { printf("index is set\n"); }

	/* swap the values at two index locations */
	eba_swap(eba, index_a, index_b);

	/* change the value at a location */
	eba_toggle(eab, index);

	/* shift all bits down by 3, filling with zero */
	eba_shift_right(eba, 3);

	/* shift all bits up by 5, filling with zero */
	eba_shift_left(eba, 4);

	/* shift all bits down by 8, filling with a specific value */
	unsigned char fill_with = eba_get(15);
	eba_shift_right_fill(eba, 8, fill_with);

	/* rotate the bits, bits shifted off the top will go to bottom */
	eba_rotate_left(eba, 7);

	/* fill the buffer with a string representation of the bits */
	printf("the bits: %s\n", eba_to_string(eba, buf, buf_len));

	/* reset all of the bits to 0 */
	eba_set_all(eba, 0);

	/* free the struct */
	eba_free(eba);


Usage Notes
-----------
There is no magic to the 'eba_new' and 'eba_free', only convience.
The caller can do the initialziation by hand:

	unsigned char flags[4];
	struct eba my_eba;

	eba.bits = flags;
	eba.size_bytes = 4;
	eba.endian = eba_endian_little;

In fact, there is not magic to the 'eba_set' or 'eba_get', rather
they simply make the indexing a bit in a byte array easier, as well
as do the bit-fiddling so the reader doesn't have to look it up or
think hard.

If targeting something like an stm or avr chip, the source should be
easy to drop into a project, possibly modifying to remove functions,
and defineing EEMBED_HOSTED to 0.


Example Usage
-------------
An example can be be found in the demo directory:

demos/sieve-of-eratosthenes.c

The tests/ directory also may shed some light.


Reducing firmware size
----------------------
If EEMBED_HOSTED is defined to be non-zero, the function pointers
eba_malloc, and eba_mfree naturally point to the standard C library
functions, however if EEMBED_HOSTED is 0, alternative
implementations are provided, and these pointers default to simple
versions, or no-op versions. To instead initialize these pointers to
NULL, and avoid building the default versions, define the following:

#define EBA_SKIP_NO_MALLOC 1
#define EBA_SKIP_NO_PRINT 1

Additionally, other functions can be skipped, and the firmware made
marginally smaller, with the following defines:

#define EBA_SKIP_NEW 1
#define EBA_SKIP_SET_ALL 1
#define EBA_SKIP_SHIFTS 1
#define EBA_SKIP_SWAP 1
#define EBA_SKIP_TOGGLE 1


Bugs
----
If a bug is encountered, it may be useful to recompile with
debugging, by defining EBA_DEBUG to 1. When EBA_DEBUG is defined to
non-zero, assertions are added to the code.


CHAR_BIT weird-ness
-------------------
POSIX and Windows define CHAR_BIT to 8. Most people never work on a
system where CHAR_BIT is defined to anything other than 8.  However,
rare DSPs and some emulators of very old hardware define CHAR_BIT to
values like 9, 16, 24, 32, or 36.  Effort has been made to try to
support weird platforms, but this is largely un-tested.  If your
platform is weird or you do not wish to reference limits.h, you can
define "EEMBED_CHAR_BIT" to 8 or a larger number.


Cloning
-------
git clone -o upstream https://github.com/ericherman/libeba.git &&
 cd libeba &&
 git submodule update --init --recursive &&
 autoreconf -iv &&
 ./configure &&
 make -j check


Contributing
------------
This codebase started as a learning exercise, although it proved
itself useful.  No doubt there is much that could still be improved.
Please feel free to give suggestions, in the form of comments, bug
reports, feedback, or code.


Packaging
---------
autoreconf -iv &&
 ./configure &&
 make &&
 make distcheck &&
 echo "Success."


License
-------
GNU Lesser General Public License (LGPL), version 3 or later.
See COPYING and COPYING.LESSER for details.