-TODO +A funcmap operates on the abstract model. It lists alternate functions +of each port and optiopnally groups those functions in weak and strong +function groups. +
+A typical example is a microcontroller (MCU) that can have the same port +act as a GPIO, as an analog input, a PWM output or part of a sync serial +device. The function is selected runtime by software. +
+As an example for such a situation consider 3 ports of the attiny24 +(full example for all pins is also available). Below +is the stripped down funcmap file from the external library: +
+ha:funcmap.v1 {
+ ha:comp_attribs {
+ li:funcmap/ports {
+ { PB6/PB6 -> sigtype=digital; }
+ { PB6/PCINT6 -> sigtype=digital; dir=input }
+ { PB6/MOSI -> sigtype=digital; }
+ { PB6/DI -> sigtype=digital; dir=input }
+ { PB6/SDA -> sigtype=digital; }
+ { PB6/OC1A -> sigtype=digital; dir=output }
+ { PB6/ADC6 -> sigtype=analog; dir=input }
+ { PA4/PA4 -> sigtype=digital; }
+ { PA4/PCINT4 -> sigtype=digital; dir=input }
+ { PA4/SCK -> sigtype=digital; }
+ { PA4/SCL -> sigtype=digital; }
+ { PA4/ADC4 -> sigtype=analog; dir=input }
+
+ { PA5/PA5 -> sigtype=digital; }
+ { PA5/PCINT5 -> sigtype=digital; dir=input }
+ { PA5/MISO -> sigtype=digital; }
+ { PA5/DO -> sigtype=digital; dir=output }
+ { PA5/OC1B -> sigtype=digital; dir=output }
+ { PA5/ADC5 -> sigtype=analog; dir=input }
+ }
+
+ li:funcmap/weak_groups {
+ { gpio -> PB6, PA4, PA5 }
+ { pcint -> PCINT4, PCINT5, PCINT6 }
+ { PWM -> OC1A, OC1B }
+ { adc -> ADC4, ADC5, ADC6 }
+ }
+
+ li:funcmap/strong_groups {
+ { SPI -> SCK, MISO, MOSI }
+ { I2C -> SDA, SCL }
+ { USI -> SCK, DI, DO }
+ }
+ }
+}
+
++The file is a lihata document with the root node ha:funcmap.v1. It hosts +a single ha:comp_attribs subtree (similar to devmap), to indicate that +the subsequent attributes are component-level (even tho the funcmap plugin +will not actually create these attributes in the components). +
+The li:funcmap/ports attribute is a list of port functions. Each line +is a port/function -> port attributes pair. Function names +are arbitrary. Once the given function is activated for a port, the funcmap +plugin will set all port attributes listed on the right side of the arrow. +As a convention the first function shall match the port name; this is going +to be the primary function of the port which is also used as a fallback +when the user does not activate any function for a port. The typical +port attributes to set are sigtype and dir (see coraleda +std 002), but any port attribute may be set. +
+The li:funcmap/weak_groups attribute is a list of groups for displaying +purposes. Each line is function group in the form of group_name -> +function_list. Group names are arbitrary but must be unique within +a funcmap file. A function_list is a comma separated list of function names. +(Function names must be defined in the li:funcmap/ports section.) +
+In a tabular display each group is a column (while ports are +rows): +
+<port> gpio pcint PWM adc SPI I2C USI <no-group> +PB6 [[PB6]] PCINT6 OC1A ADC6 MOSI SDA DI - +PA4 [[PA4]] PCINT4 - ADC4 SCK SCL SCK - +PA5 PA5 PCINT5 [[OC1B]] ADC5 MISO - DO - ++
+The function wrapped in [[]] is the one activated for the given port. +
+li:funcmap/strong_groups has the same format and display properties as +weak_groups. The difference is that a strong group is also +checked in the DRC for consistency. +
+In the above table the <port> column holds raw port names; functions +start from the second column. The last column is always called +<no-group> and holds any function that is not referenced by any of the +function groups. Note: the same function may be referenced from multiple +groups (like SCK in this case), but it's generally best practice to +avoid that. +
Component attribute: funcmap. Specifies the name of the