Index: 06_features/funcmap/index.html =================================================================== --- 06_features/funcmap/index.html (revision 9387) +++ 06_features/funcmap/index.html (revision 9388) @@ -59,8 +59,102 @@
-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