Finished rough draft of the spec

README.md

@@ -1,3 +1,79 @@
 # yazoalfa
 
-Yet Another Zero Overhead Abstraction Library For AVR.
+Yet Another Zero Overhead Abstraction Library For AVR.
+
+## Specification
+
+This document will outline the capabilities of this library and what features will be implemented.
+The library is grouped into modules that each implement a zero overhead template-based abstraction for the underlying hardware of the AVR chip.
+
+### IO
+
+The IO module provides an abstraction for configuring the mode of a pin, or port, or virtual port. It provides an easy way of writing to, or reading from the underlying hardware.
+
+#### Virtual port
+
+Sometimes it is not possible to use a hardware port, because some pins are needed for their alternative functions. In this case it would be very convenient to group arbitrary pins into a virtual port that can then be used just like a regular port.
+This will obviously incur some overhead compared to a hardware port, but not more than manually setting each pin.
+
+### ADC
+
+The ADC module provides an easy way to configure the mode of operation and will check that only pins with ADC can be used.
+
+### UART
+
+The UART module provides a general interface for serial communication which is decoupled from the actual backend driver. The backend driver might be UART0 (or UART1 if available), or it might be a software UART driver on chips (pins) that don't have hardware UART support.
+
+The backend might also be interrupt driven and use some configurable receive/transmit buffer, or be blocking and not need any buffers. The buffers should only be allocated in interrupt driven mode and also be compile-time allocated.
+
+### SPI
+
+The SPI module, similar to UART, is decoupled from the backend. This allows a software backend to be used where no hardware SPI is supported.
+
+### I2C
+
+The I2C module is basically identical to SPI, just with a different protocol.
+
+### Timers
+
+The timers module allows the configuration of the hardware timers. Compile-time checks make sure that the requested time is actually achievable with the underlying hardware timer. The prescaler will be automatically calculated at compile-time based on the clock frequency, the hardware timer used and the time requested. The prescaler can also be specified directly.
+
+#### PWM
+
+The PWM mode of the hardware timer can also be used. Additionally, if PWM is needed on a pin that does not have hardware PWM support, a hardware timer can be used to implement software PWM.
+
+## Goals
+
+- IO
+  - [ ] Interface for io-pins
+  - [ ] Interface for io-ports
+  - [ ] Interface for mapping io-pins onto virtual io-ports, where the pins do not have to be located on the same hardware port
+- ADC
+  - [ ] Support all hardware provided configuration options
+  - [ ] Compile-time check for correct hardware configuration
+- UART
+  - [ ] Separation of interface and backend-driver
+  - [ ] Support all hardware provided configuration options
+  - [ ] Compile-time check for correct hardware configuration
+  - [ ] Software backend driver
+  - [ ] Blocking hardware backend
+  - [ ] Interrupt driven hardware backend
+  - [ ] Type-safe convenience functions for writing and reading basic data types
+- SPI
+  - [ ] Separation of interface and backend-driver
+  - [ ] Support all hardware provided configuration options
+  - [ ] Compile-time check for correct hardware configuration
+  - [ ] Software backend driver
+- I2C
+  - [ ] Separation of interface and backend-driver
+  - [ ] Support all hardware provided configuration options
+  - [ ] Compile-time check for correct hardware configuration
+  - [ ] Software backend driver
+- Timers
+  - [ ] Support all hardware provided configuration options
+  - PWM
+    - [ ] Compile-time check for correct hardware configuration
+    - [ ] Software PWM on pins that don't have hardware PWM support
+- General
+  - [ ] Support for most common AVR chips (ATmega8, ATmega328, ATtiny85, ...)
+  - [ ] Provide examples for each module showcasing the usage and possibilities