Netlisting, wrapper script
~~~~~~~~~~~~~~~~~~~~~~~~~~
Devmap is a script that implements transparent manipulation of
component pin data in a gsch2pcb workflow. To access the extra
features, run gsch2pcb_devmap instead of gsch2pcb.

pinmap
~~~~~~
There are two new attributes introduced by this system. The lower layer is
the pinmap attribute attached to a component, which is a list of
name=pinnumber separated by ";". It instructs the scripts to change pin
numbers of the component, for example "B=1;C=2;E=3" change pin numbers
in a way that pin 'B' becomes 1, pin 'C' becomes 2 and pin 'E' becomes 3
in the temp sch. This way a generic transistor symbol can be used
and configured to match an actual product, by setting the pin mapping
and footprint.

When deciding which pin is 'B' or 'C' or 'E', the following logic
is implemented:
 - if pinnumber matches the name, take that pin
 - else if pinlabel matches the name, take that pin
 - if no match found, error
 - if matched, modify pinnumber according pinmap

Furthermore, names and pin numbers must be unique in pinmap (i.e. 'B' can't
be assigned twice, or pin 2 can't be bound to both 'B' and 'C').

Using pinmap is a simple yet powerful tool to assign a generic symbol to a
given package pinout. However, it is not very convinent to have such long
mappings given by hand on the schematics all the time, and is intended for
use with rare components/mappings.

devmap
~~~~~~
The higher layer is devmap; in this attribute the user specifies a device map
identifier from which both the package (footprint) and pin map are derived using
a database. This means instead of looking up which pin connected how,
the user specifies the connection between a generic NPN symbol and a
specific device, i.e. "bc182 in to92 package" or even "myvendor_11-22-33".

Actual mapping is stored in a file system database in plain text files in a
devmap directory. The component attribute "devmap" shall be one of these file
names.

A devmap file contains one command per line (empty lines and lines starting
with # are ignored). Commands are:
 delattr NAME      - delete attribute called NAME
 attr NAME=VAL     - append VAL to attribute NAME

This means a devmap file can modify any attribute of the given symbol,
including deleting existing attributes or introducing new attributes.

Normally a devmap file contains at least one "attr footprint=..." and
one "attr pinmap=..." line, but it is also possible to add attributes
to indicate the model, vendor, ordering infromation, etc.

The user is free to choose the naming convention of devmap files.
The default library of devmap files shipped with the project
follows "device_package" schema (all in lower case), i.e. the NPN transistor
in the above example is called "bc182_to92". A pitfall is that this
assumes there is only one (or at least one default/preferred) pin mapping for
any device-package pair. An alternative naming schema, for example, is
using vendor-partno (assuming partno includes packaging/footprint information).



internals
~~~~~~~~~
The script works in 3 stages pipeline:
 - sch parser to produce a detailed list of all components and their pins
   and attributes in a line based summary;
 - scripts that manipulate the summary: interpret devmap and pinmap
   attributes (and read a database if necessary) and change pin
   numbers, footprint and component/pin attributes in the summary;
 - sch filter that takes the summary and the original schematics and
   renders a new schematics merging the new component/pin attributes
   from the summary.

Main entry point currently is gsch2pcb_devmap, which is a wrapper around
gsch2pcb. It can be used instead of gsch2pcb transparently. The data flow
is:

[sch files] ---(gsch2pcb_devmap)--> [temp sch] ----(gsch2pcb)----> pcb