aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/index.md17
-rw-r--r--docs/miscellanoues/jobs_vs_tasks.md17
-rw-r--r--docs/modules/usart.md0
-rw-r--r--docs/parts/ioport.md (renamed from docs/modules/ioport.md)82
-rw-r--r--docs/parts/jobs.md15
-rw-r--r--docs/parts/spi.md (renamed from docs/modules/spi.md)31
-rw-r--r--docs/parts/tasks.md (renamed from docs/modules/tasks.md)3
-rw-r--r--docs/parts/timer.md (renamed from docs/modules/timer.md)0
-rw-r--r--docs/parts/usart.md23
-rw-r--r--docs/parts/utils/buffer.md (renamed from docs/modules/utils/buffer.md)0
-rw-r--r--docs/parts/utils/narray.md (renamed from docs/modules/utils/narray.md)0
-rw-r--r--docs/usage.md1
12 files changed, 137 insertions, 52 deletions
diff --git a/docs/index.md b/docs/index.md
index 4c261ff..c39df46 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,10 +1,13 @@
AVR Input/Output expansion
==========================
-Modules
--------
-| Module | Header | Enable Config | Description |
-|-------------------------------|----------|-------------------------------------------|--------------------------------------------------------|
-| [IO Ports](modules/ioport.md) | ioport.h | CONFIG_IOPORTS and CONFIG_IOE_PCINTERRUPT | Simple input/output port access |
-| [SPI](modules/spi.md) | spi.h | CONFIG_SPI | Serial peripheral interface |
-| [USART](modules/usart.md) | usart.h | CONFIG_USART | Universal synchronous/asynchronous receive/transmitter |
+Parts
+-----
+Whole library consists from set of parts. You can use any part directly or
+only trough other part. Every part can be enabled or disabled.
+
+| Parts | Header | Description |
+|-------------------------------|----------|--------------------------------------------------------|
+| [IO Ports](parts/ioport.md) | ioport.h | Simple input/output port access |
+| [SPI](parts/spi.md) | spi.h | Serial peripheral interface |
+| [USART](parts/usart.md) | usart.h | Universal synchronous/asynchronous receive/transmitter |
diff --git a/docs/miscellanoues/jobs_vs_tasks.md b/docs/miscellanoues/jobs_vs_tasks.md
new file mode 100644
index 0000000..17d7fdd
--- /dev/null
+++ b/docs/miscellanoues/jobs_vs_tasks.md
@@ -0,0 +1,17 @@
+Jobs vs. Tasks
+==============
+This document refers to [Jobs](/parts/jobs.md) and [Tasks](/parts/tasks.md).
+
+You should be familiar with threads from other platforms. Tasks are from usability
+point of view almost same. They are switched according their priority and
+availability. Jobs are different. They are designed to execute single function at
+the time and when this function exits it executes another. It cant interrupt
+execution when more important task come. So why use jobs instead of tasks? Task
+requires for their run stack memory and during whole live of task is this memory
+taken. This limits number of tasks running. Jobs are sharing same stack and only
+one function has data on it at the time. This results in less memory consumption.
+Another huge difference is how planing works. Tasks are planned based on priority.
+Task with higher priority will run unless it isn't suspended. Jobs don't have
+priority, but they have to specify time until they should be finished (deadline)
+and duration of execution. With these two parameters jobs planner can plan their
+execution.
diff --git a/docs/modules/usart.md b/docs/modules/usart.md
deleted file mode 100644
index e69de29..0000000
--- a/docs/modules/usart.md
+++ /dev/null
diff --git a/docs/modules/ioport.md b/docs/parts/ioport.md
index e777e0c..96a4b82 100644
--- a/docs/modules/ioport.md
+++ b/docs/parts/ioport.md
@@ -1,6 +1,5 @@
IO port
=======
-To use include: `ioport.md`
And define: `CONFIG_IOE_IOPORT`
Defines simple access to io ports. This allows runtime access to any pin with just
@@ -16,36 +15,45 @@ command.
WARNING: No check is implemented for right group number. Usage of unsupported
value is undefined (write to other parts of memory can happen).
-## References
+Configuration
+-------------
+To use this part, you must enable `CONFIG_IOPORTS` option.
+This part also handles pin change interrupts. Enable it using
+`CONFIG_IOPORTS_PCINT` option.
+
+References
+----------
### For output
#### Function io_setout
```C
static inline void io_setout(uint8_t group, uint8_t mask)
```
Configures port of `group` with `mask` as output.
-Parameters:
- group - Character specifying exact port group
- mask - Binary shifted 1. Shift is equal to port index in specified group.
+Parameters:
+__group__ - Character specifying exact port group
+__mask__ - Binary shifted 1. Shift is equal to port index in specified group.
#### Function io_hight
```C
static inline void io_hight(uint8_t group, uint8_t mask)
```
Sets output port to hight (also can be called as 1).
-WARNING: Invoke this only if io_setout is called before.
-Parameters:
- group - Character specifying exact port group
- mask - Binary shifted 1. Shift is equal to port index in specified group.
+WARNING: Invoke this only if io_setout is called before.
+
+Parameters:
+__group__ - Character specifying exact port group
+__mask__ - Binary shifted 1. Shift is equal to port index in specified group.
#### Function io_low
```C
static inline void io_low(uint8_t group, uint8_t mask)
```
Sets output port to low (also called as 0).
-WARNING: Invoke this only if io_setout is called before.
-Parameters:
- group - Number specifying exact port group
- mask - Binary shifted 1. Shift is equal to port index in specified group.
+WARNING: Invoke this only if io_setout is called before.
+
+Parameters:
+__group__ - Number specifying exact port group
+__mask__ - Binary shifted 1. Shift is equal to port index in specified group.
#### Function io_set
```C
@@ -53,9 +61,9 @@ static inline void io_set(uint8_t group, uint8_t mask, int8_t val)
```
Sets output port to value passed as argument.
WARNING: Invoke this only if io_setout is called before.
-Parameters:
- group - Number specifying exact port group
- mask - Binary shifted 1. Shift is equal to port index in specified group.
+Parameters:
+__group__ - Number specifying exact port group
+__mask__ - Binary shifted 1. Shift is equal to port index in specified group.
### For input
#### Function io_setin
@@ -64,20 +72,22 @@ static inline void io_setin(uint8_t group, uint8_t mask,
enum ioeIOInResistor resistor)
```
Configures port of `group` with `mask` as input with specified pull-up/down
-resistor.
-Parameters:
- group - Number specifying exact port group
- mask - Binary shifted 1. Shift is equal to port index in specified group.
+resistor.
+
+Parameters:
+__group__ - Number specifying exact port group
+__mask__ - Binary shifted 1. Shift is equal to port index in specified group.
#### Function io_get
```C
static inline int8_t io_get(uint8_t group, uint8_t mask)
```
Returns current value of port. Note that you can use this also if port is
-configured as output.
-Parameters:
- group - Number specifying exact port group
- mask - Binary shifted 1. Shift is equal to port index in specified group.
+configured as output.
+
+Parameters:
+__group__ - Number specifying exact port group
+__mask__ - Binary shifted 1. Shift is equal to port index in specified group.
#### Enum ioeIOInResistor
```C
@@ -100,20 +110,22 @@ specifies port and edge specifies on what edge should hook be called. `edge` can
be IO_RISING or IO_FALLING or their binary combination with operator
`|`.
WARNING: `change` call is call during interrupt handling. You shouldn't be
-blocking execution for long time.
+blocking execution for long time.
+
Parameters:
- group - Number specifying exact port group
- mask - Binary shifted 1. Shift is equal to port index in specified group.
- edge - Signals on what edge should be hook called.
- change - Pointer to function used as interupt hook
+__group__ - Number specifying exact port group.
+__mask__ - Binary shifted 1. Shift is equal to port index in specified group.
+__edge__ - Signals on what edge should be hook called.
+__change__ - Pointer to function used as interupt hook.
#### Function io_change_remhook
```C
int8_t io_change_remhook(void (*change) (uint8_t group, uint8_t mask))
```
-Removes `change` hook.
+Removes `change` hook.
+
Parameters:
- change - Pointer to function used as hook
+__change__ - Pointer to function used as hook
### Others
#### Definitions IO_{GROUP}
@@ -126,12 +138,14 @@ mcu support file should define all ports in form of single line definition in
format `IOE_IO_{GROUP}{INDEX}`. Disadvantage is that with these definitions you
can't use binary conjunction and so only one pin can be controlled with it.
-## Relevant examples
+Relevant examples
+-----------------
* blink
* pcinterrupt
-## Adding support
-For more information on how add support, see `doc/add_support.md`.
+Adding support
+--------------
+For more information on how add support, see [Adding MCU support](/add_support.md).
Main definition is `MCUSUPPORT_IOPORT`. Define it to enable support.
### IO_{GROUP}
diff --git a/docs/parts/jobs.md b/docs/parts/jobs.md
new file mode 100644
index 0000000..878a557
--- /dev/null
+++ b/docs/parts/jobs.md
@@ -0,0 +1,15 @@
+Jobs
+====
+Jobs allows periodic execution of different short functions. It is designed to host
+control loops. So called functions should be short.
+
+Every job must specify deadline and if not set otherwise also its duration.
+
+If tasks support is enabled jobs can be also executed on multiple tasks, which is
+handy if you divide sensor reading and control algorithm, because control
+algorithm can than run when for example mcu waiting for response from sensor.
+Always be sure that jobs are running on tasks with highest priority, otherwise
+deadlines might not be fulfilled every time.
+
+Be aware of taking mutexes and semaphores. It can sometime result in long task
+suspension and that would result to deadline misses.
diff --git a/docs/modules/spi.md b/docs/parts/spi.md
index 3ae730c..f63d304 100644
--- a/docs/modules/spi.md
+++ b/docs/parts/spi.md
@@ -1,9 +1,16 @@
Serial peripheral interface
===========================
-This interface is link to MOSI and MISO pins. Also SS pin is used when slave mode initialized.
+To use include: `spi.h`
+This interface is link to MOSI and MISO pins. Also SS pin is used when slave mode
+initialized.
-## References
-### spi\_init
+Configuration
+-------------
+To use SPI you must enable `CONFIG_SPI` configuration symbol.
+
+References
+----------
+### Function spi\_init
```C
static inline void spi_init(enum spiMode mode)
```
@@ -13,20 +20,20 @@ Parameters:
NOTE: Global interrupts must be enabled for right function of SPI.
-### spi\_busy
+### Function spi\_busy
```C
static inline int8_t spi_busy(void)
```
Returns NULL when device is not busy.
When device is busy return values in non-zero.
-### spi\_join
+### Function spi\_join
```C
static inline void spi_join(void)
```
Blocks processor until device is not busy.
-### spi\_send
+### Function spi\_send
```C
static inline uint8_t spi_send(uint8_t data)
```
@@ -34,7 +41,7 @@ Swap bytes with slave over SPI.
This function blocks execution until device isn't busy (transfer completed).
WARNING: Invoke this only when interface is initialized in MASTER mode.
-### spi\_transfer
+### Function spi\_transfer
```C
static inline void spi_transfer(uint8_t data)
```
@@ -43,7 +50,7 @@ This function isn't blocking execution until transfer is complete.
Always call spi\_join before this function when called outside of spi\_receive().
WARNING: Invoke this only when interface is initialized in MASTER mode.
-### spi\_expose
+### Function spi\_expose
```C
static inline void spi_expose(uint8_t data)
```
@@ -52,14 +59,14 @@ Please don't use this when device is busy.
Best place to call this is spi\_receive().
WARNING: Invoke this only when interface is initialized in SLAVE mode.
-## Function pointer spi\_receive
+### Function pointer spi\_receive
```C
extern void (*spi_receive)(uint8_t data)
```
This function is called every time transfer is finished.
And until return from this function interrupts are disabled.
-## Enum spiMode
+### Enum spiMode
```C
enum spiMode {
SPI_MODE_MASTER,
@@ -67,3 +74,7 @@ enum spiMode {
};
```
This is used as parameter for spi\_init function.
+
+Relevant examples
+-----------------
+* spiblink
diff --git a/docs/modules/tasks.md b/docs/parts/tasks.md
index 0078f00..e4f71df 100644
--- a/docs/modules/tasks.md
+++ b/docs/parts/tasks.md
@@ -1,6 +1,7 @@
Tasks
=====
-Tasks allows separate jobs.
+Tasks can be used for sharing processor for example during period of waiting for
+interrupt. Planing is based on priority.
## Functions
### tasks_run
diff --git a/docs/modules/timer.md b/docs/parts/timer.md
index e69de29..e69de29 100644
--- a/docs/modules/timer.md
+++ b/docs/parts/timer.md
diff --git a/docs/parts/usart.md b/docs/parts/usart.md
new file mode 100644
index 0000000..22e54ab
--- /dev/null
+++ b/docs/parts/usart.md
@@ -0,0 +1,23 @@
+Universal synchronous/asynchronous receive/transmitter
+======================================================
+This part acts as UART intended as text base interface with computer. It is
+using hardware termed as USART by Atmel. This hardware also supports synchronous
+communication and can behave as SPI master, but this is not supported by this
+library (I don't require this feature, but implementation is welcomed).
+
+This part implements, if enabled, whole stack for binding input and output to
+stdin and stdout. This is handy during development. You can use `printf` and
+`scanf` directly.
+
+This part can be enabled by `CONFIG_USART` configuration option. This enables
+more detailed configuration in sub-menu.
+
+## Usage
+
+
+## References
+### usart_init_async
+```C
+void usart_init_async(void)
+```
+
diff --git a/docs/modules/utils/buffer.md b/docs/parts/utils/buffer.md
index 4365c25..4365c25 100644
--- a/docs/modules/utils/buffer.md
+++ b/docs/parts/utils/buffer.md
diff --git a/docs/modules/utils/narray.md b/docs/parts/utils/narray.md
index 3e64f67..3e64f67 100644
--- a/docs/modules/utils/narray.md
+++ b/docs/parts/utils/narray.md
diff --git a/docs/usage.md b/docs/usage.md
index e69de29..b96c601 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -0,0 +1 @@
+Sorry this documentation is not finished yet. To start you can look to examples.