# 5. Netlist

{des5:0} In cschem terminology a netlist is a custom, 3rd-party application specific file format that is derived (typically by a plugin) from the abstract model.

{des5:1} The type of information that ends up in a netlist depends on the application. The export plugin will

- filter the abstract model and include only the relevant subset of the model
- process the objects of the abstract model to generate summaries, indices, metadata for the netlist

{des5:2} Thus the term netlist used in cschem doesn't necessarily mean an actual list of networks, but a more generic package of information intended for annotation (data exchange between different software), that may or may not include a list of networks, or a list of components or ports.

{des5:3} Independently of the details of the netlist file format, it mainly consists of netlist objects, each derived from the objects of the abstract model. In a netlist file format specific way, each netlist object can be uniquely identified (netlist ID) and referred to:

- some formats support a netlist-unique name or ID
- structured formats often support a path within the document tree of the netlist
- as an ultimate fallback the generator can refer to the line.column location of the object within the generated text file or the binary byte offset within the generated binary file

# 5.1. Netlist map: format

{des5:4} It is strongly recommended that any netlist export plugin should generate a netlist map as a side effect. The map can be part of the netlist emitted (in case the netlist file format supports arbitrary attachments, comments, text blocks, etc.) or a separate file.

{des5:5} The map file is a flat list of netlist ID, netlist object type, concrete model references tuples.

{des5:6} A netlist ID is netlist file format specific, the concrete model references is a list of concrete model references. The netlist object type is a netlist format specific string that refers to the type of the ID, e.g. "component" or "pin" or "net".

{des5:7} A concrete model reference (CMR) is either an UID of a concrete object (when the whole object is referenced) or the UID:key pair when an attribute of the object is referenced.

{des5:8} In practice this means if a cschem network ends up as network identified as "pgnd" on the netlist, the map file will have an entry identified as "pgnd" of type "net" containing a list of CMRs to every concrete object that contributed to the network. This typically includes a few network UIDs and a few by-attribute-connections, e.g. a connect attribute of a symbol (in the form of UID:connect where UID is the UID of the symbol).

{des5:9} Similar to that, if the netlist has a component called "C2", the map will have a UID list pointing to concrete symbols that built up C2 in the netlist. Again similar, if the netlist refers to pin C2-1, the map for pin "C2-1" will contain the UID of the concrete terminal that got derived into C2-1 in the export.

{des5:10} (Note: it is possible to build the CMR list because each abstract model object contains a list of the concrete model objects that created the given abstract object)

# 5.2. Netlist map: purpose

{des5:11} The purpose of the netlist map is to provide a mechanism through which an object identified in a 3rd party software can be tracked back to concrete objects on the corresponding schematics sheets.

{des5:12} A cschem GUI is required to implement an UI that displays a list of netlist map items: the netlist ID and type as a header and the list of CMRs. The UI shall assist the user to navigate to the concrete objects listed as a CMR; e.g. if the user clicks a CMR, the relevant schematic page is displayed with the referred object centered and/or highlighted. In case of an attribute reference optionally the attribute edition prepared/presented.

{des5:13} This should create a tool-agnostic bridge between arbitrary 3rd-party software and cschem:

- the user selects an item in the 3rd party software (e.g. clicks on a pin in a PCB editor or names a pin in a spice simulation)
- the information of the selection is transferred to a map-lookup-tool, an external program or a plugin/addon running within the 3rd party software
- the map-lookup-tool looks up the map item in the netlist or map file and sends it back to a running instance of cschem (e.g. through a project manager)
- cschem presents the map item helping, effectively displaying the concrete objects of the schematics that eventually created the object which the user selected in the 3rd party software