From 9439c6f1caffd938673018f3af7460b33a12528e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karel=20Ko=C4=8D=C3=AD?= Date: Sun, 20 Mar 2016 16:39:30 +0100 Subject: Another work progress --- docs/parts/utils/buffer.md | 105 +++++++++++++++++++++++++++++++++++++++++++++ docs/parts/utils/narray.md | 64 +++++++++++++++++++++++++++ 2 files changed, 169 insertions(+) create mode 100644 docs/parts/utils/buffer.md create mode 100644 docs/parts/utils/narray.md (limited to 'docs/parts/utils') diff --git a/docs/parts/utils/buffer.md b/docs/parts/utils/buffer.md new file mode 100644 index 0000000..4365c25 --- /dev/null +++ b/docs/parts/utils/buffer.md @@ -0,0 +1,105 @@ +buffer +====== +In whole project are used ring buffers. This is so common that handling them is +exported to separated header file. In fact it contains two implementations of +buffers. One implementation is defined using preprocessor macros. Another one is +plain C code. + +## Preprocessor implementation +Preprocessor implementation is expected to be faster and less memory intense. Also +more suitable for buffers of simple types (such us int). But this buffer has to be +defined with known size at compile time and can't be resized. All this makes it +good implementation for IO devices input and output buffers, but less for more +complicated tasks containing for example sorting. + +### Macros +#### IOEBUFFER +```C +IOEBUFFER(type, name, size) +``` +This macro defines buffer. Use it to define new buffer. +##### Parameters +| type | Specify type of elements in buffer. Can be any valid C type | +| name | Name of buffer. This is C variable name. | +| size | Numerical value of buffer size | + +#### IOEBUFFER_INIT +```C +IOEBUFFER_INIT(name, size) +``` +Use this to initialize buffer. Parameter `size` must be same as for IOEBUFFER +(definition of buffer). You can use this also to reset buffer (remove all data +from buffer). +##### Parameters +| name | Name if buffer. This is C variable name. | +| size | Numerical value of buffer size | + +#### IOEBUFFER_PUT +```C +IOEBUFFER_PUT(name, size, data, mode) +``` +Use this macro to add new data to buffer. +##### Parameters +| name | Name of buffer. This is C variable name. | +| size | Numerical value of buffer size | +| data | Data to be stored to buffer | +| mode | This specifies action if buffer is full. | +##### Modes +| IOEBUFFER_MODE_BLOCK | Block execution until buffer has some free space. | +| IOEBUFFER_MODE_OVERWRITE | Overwrites oldest added (fist to be read) | +| IOEBUFFER_MODE_DROP | New data won't be stored to buffer if full | + +#### IOEBUFFER_GET +```C +IOEBUFFER_GET(name, size, variable) +``` +Get value from buffer. Value is stored in `variable` (it is variable of same type +as buffer data, not pointer to variable of same type). If no data is in buffer, +variable is set to NULL. +##### Parameters +| name | Name of buffer. This is C variable name. | +| size | Numerical value of buffer size. | +| variable | Variable in which data will be stored in. | + +#### IOEBUFFER_CNT +```C +IOEBUFFER_CNT(name, size, variable) +``` +Counts number of data entries in buffer and saves value to variable. +##### Parameters +| name | Name of buffer. This is C variable name. | +| size | Numerical value of buffer size. | +| variable | Int/Unsigned type variable where data count will be stored. | + +## C implementation +C implementation is more general. Size is defined by calling initialization +function. But it is using general pointers, so it is only able store pointers. + +As buffer identification is used defined type `IOEBuffer`. All functions takes +pointer to this type as parameter. Because of this, it won't be described for +every function. + +### Functions +#### ioebuffer_init +```C +int8_t ioebuffer_init(IOEBuffer *buf, uint8_t size, uint8_t flags) +``` +Initialized buffer and allocates required resources. +##### Parameters +| size | Number of elements to be maximally stored in buffer | +| flags | TODO +##### Flags +TODO + +#### ioebuffer_uninit +```C +void ioebuffer_uninit(IOEBuffer *buf) +``` +Frees all resources allocated during initialization of buffer. Use this every time +you are freeing buffer. + +#### ioebuffer_put +```C +int8_t ioebuffer_put(IOEBuffer *buf, void *data) +``` +Add `data` to buffer diff --git a/docs/parts/utils/narray.md b/docs/parts/utils/narray.md new file mode 100644 index 0000000..3e64f67 --- /dev/null +++ b/docs/parts/utils/narray.md @@ -0,0 +1,64 @@ +narray.h +======== +This implements some helping functions for null terminated arrays. Null terminated +arrays are used across whole project because they are simple and don't waste +memory space. Their disadvantage is more complicated implementation of utility +functions and much longer adding time (they are reallocated every time new data +are added). + +This implementation is limited to only contains 255 elements(limited by uint8_t +type). But it should be enough for basic usage. If you need store more than that, +you should use different approach. Also only pointers can be stored. + +To define null terminated array just define pointer to you required pointer and set +it to NULL. Such narray is handled as empty. Example: +```C +int **narray = 0; +``` +After adding some data (in example case data of type `int*`) you can access them +same as if you would working with simple array (`narray[i]`). Last element it such +array is `NULL`. No more valid data are stored after `NULL` (This also means that +`NULL` can't be stored to narray). + +All functions are taking as parameter `void ***array`, which is pointer to null +terminated array. This parameter won't be described in functions. + +## Functions and macros +### narray_add +```C +void narray_add(void ***array, void *data) +``` +Add data to end of the array. This increases size of the array by one (two bytes). +#### Parameters +| data | data to be stored to array | + +### narray_remove +```C +void narray_remove(void ***array, void *data) +``` +Remove specified data from array. This effectively decreases size of the array by +one (two bytes). +#### Parameters +| data | data to be removed from array | + +### narray_size +```C +size_t narray_size(void ***array) +``` +Returns size of array. + +### narray_free +```C +inline void narray_free(void ***array) +``` +Frees whole array if allocated. + +### fornarray +```C +#define fornarray(array, i, data) for (i = 0; (data = array[i]) != 0; i++) +``` +This is macro. It implements simple foreach cycle. +#### Parameters +| array | array it self (void ** not pointer) | +| i | unsigned integer (uint8_t) | +| data | variable which will be used to access data | -- cgit v1.2.3