diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/index.md | 17 | ||||
| -rw-r--r-- | docs/miscellanoues/jobs_vs_tasks.md | 17 | ||||
| -rw-r--r-- | docs/modules/usart.md | 0 | ||||
| -rw-r--r-- | docs/parts/ioport.md (renamed from docs/modules/ioport.md) | 82 | ||||
| -rw-r--r-- | docs/parts/jobs.md | 15 | ||||
| -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.md | 23 | ||||
| -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.md | 1 |
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. |