2. Periphery and References
===========================

The pinmuxer contains an "app" and an "board" object.
The app contains an list of references. The Board contains an list of periphery.
Each periphery has an list of consume-references.

A reference has an parent-periphery.

3. Bindings
===========

Bind modes: every reference is added to C++ class by c++
reference/pointer. Exceptions: GPIO, INPUT, OUTPUT, EXTI. These
are instanciated directly in the parent.
Example:
CGDisplay (Cspi &m_spi1, EGpioPeriphery ePeriphery, EgpioPin ePin);


4. Joint-Modes
==============

4.1. Normal

Peripheries are usualy consumed by one reference

4.2. Shared

When both eference and periphery have the mode "shared", the periphery can be used by multiple references.
This is usually the case for buses like SPI or I2C.
An periphery can still insist to have its exclusive bus by not seting the consume-reference to "shared".

4.3. Exclusive

When an periphery has this mode, none of the sub-periphery can be shared.
This mode is only available for root references.

4.4. Placeholder

Placeholders are not instanciated automatically in the platform. They have to be created at runtime.
They can compete with other placeholders, but in that case the attribute "overlap" has to match.
"overlap" is an custom string just to assure that the application is plausible.
CAN and USB share same pins on some MCUs or can not be run at the same time for other hardware reasons.
With this mode the application can decide at runtime which periphery it wants to use.
This mode is only available for root references.

Placeholders can not use any shared sub-periphery.

4.5. Fabricate

When a periphery with mode "fabricate" is used, it will reproduce itself. This is the case for periphery
that only consumes subperiphery by periphery type.
E.g. an LED consumes any GPIO. When an LED is used, it can be consumed again as long as there are GPIOs
available.


8. STM32
========

Sample MCU name: STM32L011F4P6
Encoding: STM32L   031        F          6            P               7
                   Subfamily  Pins 20    Flash-Size   Package TSSOP   Temperature

board file inheritance
    STM32L031F6PX Concrete MCU: Set size, inherit package
    STM32L031FXPX Package: enable pins, inherit family
    STM32L031XXXX Family: All pins and periphery

9. Writers
==========

"Writers" generate files for different purposes.

9.1. Platform
=============

10. Pins, packages, MCU-Families
================================

In order to make it easy to handle MCU variants (families, packages etc.), pins can be overloaded.
The MCU-family-file (see 'stm32') can declare all gpios with their alternate functions. But per default they are disabled:
'''
[...]
{ "type": "GPIO",   "periphery": "PB8", "status": "disabled", "functions": { "SPI2_SCK": "GPIO_AF5_SPI2" } },
[...]
'''
In the MCU-package-file the gpio can be declared again which will enable it. It also can get assigned to concrete pin.
'''
{ "type": "GPIO",   "periphery": "PB8",  "pin": "#30"},
'''

11. Alternate function
======================

In order not to specify every periphjery-pin-combination, periphery can be specified with their consuming gpios by its alternate function.

'''
       {
           "type": "UART", "periphery": "UART2",
           "consumes": [
               { "function": "UART2_RX",  "name": "UART-RX(red)" },
               { "function": "UART2_TX",  "name": "UART-TX(yel)" },
               { "periphery": "UART2_CU" }
           ],
           "attributes": {
               "configBlock": "uartConfig_UART2",
               "implementation": [
                    "const SUartConfig uartConfig_UART2",
                    "{",
                    "   .instance   = USART2,",
                    "   .irq        = USART2_IRQn,",
                    "   .interrupt  = interruptUart2,",
                    "   .altFunc = <function:0>,",
                    "   .eGpioPeripheralRx = eGpioPeripheral<periphery:0>,",
                    "   .eGpioPinRx = eGpioPin<pin:0>,",
                    "   .eGpioPeripheralTx = eGpioPeripheral<periphery:1>,",
                    "   .eGpioPinTx = eGpioPin<pin:1>,",
                    "};",
                    ""
                    ],
                "irqs": "USART2_IRQHandler"
            }
       },
'''

The GPIO has to specify its alternate function:
'''
       { "type": "GPIO",   "periphery": "PB3", "status": "disabled",
               "functions": { "SPI3_SCK": "GPIO_AF6_SPI3" }
       },
'''