Another work progress

2 files changed, 169 insertions, 0 deletions

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 |