7. Device mapping

{des7:0} Device mapping is a generic mechanism for detaching schematics symbols from footprints and simulation models. It allows:

• interchangeable symbols and interchangeable footprints/models for the same generic device (e.g. transistor) by decoupling their pin numbers from pin names (problem known as the "transistor problem")
• multiple symbols to represent different parts of one physical footprint or simulation model (problem known as "slotting")

{des7:1} These goals are achieved by using symbolic terminal names (instead of "pin numbers") in the schematic symbols and using auxiliary data to translate the terminal names into port numbers. The following diagram demonstrates the process:

{des7:2} The default implementation of the device mapper is a plugin called std_devmap. std_devmap has three major features: slotting name translation (red), device mapping (green) and port mapping (blue). The slotting translation makes sure the resulting abstract component has the right amount of ports; the device mapper loads the device-specific port mapping and other attributes from a database; the port mapper applies pin numbers from a table (the table typically set up by the device mapper).

{des7:3} The standard device mapper is an optional mechanism implemented in a plugin. The user may choose to use it or to:

• not include the device mapper in the view at all
• not using the slotting mechanism described here, on per symbol basis, by not having a slot attribute
• not using the device mapping mechanism described here, on per symbol basis, by not having a devmap attribute
• not using the port mapping mechanism described here, on per symbol basis, by not having a portmap attribute and not using a device map that would introduce a portmap attribute

{des7:4} It is possible to use features of this plugin selectively and/or replace some or all features using another plugin.

{des7:5} std_devmap registers for:

• the symbol_joined_component hook (for updating attribute from the devmap if the devmap attribute is present)
• the terminal_name_to_port_name translation hook (for setting port names according to devmap)

7.1. Slot prefixing

{des7:6} If the "slot" attribute presents in a symbol, and the terminal does not have the "noslot" attribute, the translation is activated. The slot name is taken directly from the concrete symbol's "slot" attribute. All ports are then named as "slot/terminal-name" and the slot attribute is then removed from the abstract component to avoid collisions.

{des7:7} Typical example: common opamp symbol:

{des7:9} example opamp terminal attributes
name	noslot	terminal description
in_plus	(not present)	positive input pin
in_minus	(not present)	negative input pin
out	(not present)	output pin
v_plus	"yes"	positive power rail
v_minus	"yes"	negative power rail

{des7:10} In the above example "v_plus" and "v_minus" are never prefixed with "slot/" because of their "noslot" attribute. In case the symbol is used with the "slot" attribute set, this means:

• "in_plus", "in_minus" and "out" will be copied/duplicated for each slot (e.g. as "A/in_plus" for slot "A") for the abstract component
• "v_plus" and "v_minus" are kept common and only one copy of them will exist in the abstract component

{des7:12} Port mapping takes a map between the symbolic description and the physical description (port numbers for a footprint or sim model) and changes port attributes accordingly. There shall be one such mapping per abstract component. If multiple symbols contribute a mapping, the attribute priority mechanism will keep only one of the arrays.

{des7:13} The input array is an unordered list of (terminal name + slot name) -> (attribute_name + value) pairs, each specified in the following syntax:

slot/termname -> attribkey=value
or
termname -> attribkey=value

{des7:14} E.g. "A/out -> pcb/pinnum=1" means "terminal with name=out in symbol tagged as slot=A shall get attribute pcb/pinnum set to 1". Equivalent non-slotted example is "out -> pcb/pinnum=1"

{des7:15} If a slot/terminal pair referenced in the map is not found in the concrete symbol, no error message is emitted. A typical example when this happens is when a logic circuit has 4 identical slots but the schematics uses only 3. If this is considered an error, a DRC plugin shall check for it.

{des7:16} If an existing port of the abstract component is not listed in the mapping, that is the mapping doesn't reference the port in any way, a warning is generated. (This happens e.g. on the PCB flow when the schematics symbol uses a terminal that has no physical pin with the given device.).

{des7:18} port mapping related symbol attributes
attribute	value	description
portmap	array of map entries	the actual map, as described above
slot	slot name	textual name of the slot the symbol provides

7.3. Device mapping

{des7:19} The device mapper takes the "devmap" attribute of a symbol and looks it up in a database for finding a device map file. If the "devmap" attribute is an array, each devmap file is looked up and applied, in order of appearance.

{des7:20} A device map file is a simple list of cschem attributes. The device mapper takes each attribute from the device map file and apply it on the symbol that had the "devmap" attribute.

{des7:21} A common device map file will usually have a "portmap" attribute that will set at least one attributes on each terminal.

{des7:22} device mapping related symbol attributes
attribute	value	description
devmap	name	name of the devmap file to use