aboutsummaryrefslogtreecommitdiff
path: root/docs/references/utils
diff options
context:
space:
mode:
authorKarel Kočí <cynerd@email.cz>2016-06-30 17:18:49 +0200
committerKarel Kočí <cynerd@email.cz>2016-06-30 17:18:49 +0200
commit4e1ce86af16307bf7d42657db07600867c7c4bbc (patch)
tree5d0dfddea221c91545a9bd57ac7face5842291d4 /docs/references/utils
parent147cb7f0e67d1f3c3274effa5476607e24664182 (diff)
downloadavr-ioe-4e1ce86af16307bf7d42657db07600867c7c4bbc.tar.gz
avr-ioe-4e1ce86af16307bf7d42657db07600867c7c4bbc.tar.bz2
avr-ioe-4e1ce86af16307bf7d42657db07600867c7c4bbc.zip
Add some more progress and split non-core functionality to separate repo
More progress to implementation and some changes in project it self. This library will implement only drivers for features on chip but nothing else. Everything connected externally is now in separate repository.
Diffstat (limited to 'docs/references/utils')
-rw-r--r--docs/references/utils/buffer.md105
-rw-r--r--docs/references/utils/narray.md64
2 files changed, 169 insertions, 0 deletions
diff --git a/docs/references/utils/buffer.md b/docs/references/utils/buffer.md
new file mode 100644
index 0000000..4365c25
--- /dev/null
+++ b/docs/references/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/references/utils/narray.md b/docs/references/utils/narray.md
new file mode 100644
index 0000000..3e64f67
--- /dev/null
+++ b/docs/references/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 |