sch-rnd - attribute export naming

Attribute export names

Each attribute in the abstract model has an optional "export name" field. If the export file format supports arbitrary key/value pairs exported (e.g. with nets, components or even ports), those attributes that have an export name set are exported, using the export name instead of the original attribute name. This allows plugins to control which attributes to export for a given workflow, under what output attribute name.

Usually the target plugin sets export name on some of the attributes, typically using the standard attribute export naming mechanism.

Standard attribute export naming mechanism

The target plugin has the following configuration nodes:

end of node path description
flow_prefix workflow prefix (domain prefix)
sw_prefix consumer software prefix
whitelist list of attribute names to export with an option to use a different name in export; this is typically a list type config node of the target plugin, e.g. for target_pcb it is plugins/target_pcb/attr_export/whitelist
blacklist list of attribute names that shall not be exported; this is typically a list type config node of the target plugin, e.g. for target_pcb it is plugins/target_pcb/attr_export/blacklist

end of node path	description
flow_prefix	workflow prefix (domain prefix)
sw_prefix	consumer software prefix
whitelist	list of attribute names to export with an option to use a different name in export; this is typically a list type config node of the target plugin, e.g. for target_pcb it is plugins/target_pcb/attr_export/whitelist
blacklist	list of attribute names that shall not be exported; this is typically a list type config node of the target plugin, e.g. for target_pcb it is plugins/target_pcb/attr_export/blacklist

The mechanism is specified in CoralEDA crl001, with the following sch-rnd specific implementation details:

flow_prefix is the same as "domain scope prefix" in crl001; it's typically the same as the target plugin's basename, e.g. "pcb" for plugin target_pcb, so symbol attribute "pcb:foo" is exported as component attribute "foo" when using target_pcb
whitelist items are either plain attribute names, or "attr_name->export_name" pairs for a rename; e.g. "display/dnp->dnp" means the display/dnp attribute is exported under the name dnp
blacklist is a list of attribute names; a blacklisted attribute's export name is removed even if it was also whitelisted or matched any of the prefixes or another plugin has set it earlier during the compilation process

The order of precedence (later items override earlier items on the list):

whitelist
sw_prefix
flow_prefix
blacklist

Since sch-rnd does not know the exact software the netlist will be used with, the sw_prefix is usually manually configured, e.g. when using target_pcb the config node to set is plugins/target_pcb/attr_export/sw_prefix.

Practical example (pcb workflow)

When exporting a netlist using the pcb view, which in turn uses the target_pcb plugin to mark attributes for export, the following methods can be used to get an attribute exported.

In this example the list type config node plugins/target_pcb/attr_export/whitelist contains the following items:

tolerance
color
display/dnp->dnp

A typical symbol placed on the sheet will have a name, a footprint a value and sometimes a device attribute. The name attribute has a meaning to the sch-rnd compiler as it will determine the unique identifier of the resulting (abstract) component. The footprint, value and device attributes are hardwired in the tEDAx netlist code because these are predefined fields in the file format with fixed name.

Then comes the flexible part: any component attribute key that's on the whitelist is selected for export. For the display/dnp->dnp entry of the above whitelist, the component symbol display/dnp is renamed to dnp on the export. (The input attribute on the symbol is normally dnp, but it gets renamed to display/dnp during compilation while merging attributes of multiple symbols of the same name into a single component).

Then any component attribute whose key is starting with pcb: is marked for export, with the pcb: prefix removed. This is done automatically but the target_pcb plugin (used when the pcb view is active). This means a custom attribute like pcb:height=15mm is marked for export as height=15mm without any extra configuration.

Then comes the sw_prefix mechanism. For example set the config node plugins/target_pcb/attr_export/sw_prefix to "pcb-rnd", either in the config tree or e.g. using the -c command line argument:

pcb-rnd -x tedax -c plugins/target_pcb/attr_export/sw_prefix=pcb-rnd board.rs

and any attribute whose key is prefixed with "pcb-rnd:" will be marked for export, with the prefix removed.

Finally if the blacklist at plugins/target_pcb/attr_export/blacklist is not empty, all attributes are checked against the blacklist. On any match the attribute's export name (set by the above mechanisms) is deleted, so that the attribute is not exported.

Note: the blacklist goes by the original attribute name, including prefixes. So to remove the final height=15mm comptag from the netlist, pcb:height needs to be blacklisted, and to remove the dnp comptag, display/dnp needs to be blacklisted.

Component attribute (original) names can be observed in the abstract model window. When the attribute is selected, the exported as: under the list shows the final export name used in the netlist output. When this is empty, the attribute is not exported.