pcb-rnd knowledge pool
New import schematics: rationale
| isch_overview by Tibor 'Igor2' Palinkas on 2020-02-01 | Tags: insight, import, sch, schematics |
Abstract: Rationale for the 'import schematics' rewrite. Overview of the new architecture, focusing on how it differs from the old and what problems these difference solve.
The original import schematics got a lot of things wrong but got one thing right: it remembered import settings so once configured, it was possible to repeat the import (the forward annotation) in a few clicks. In this article this "setup-and-repeat" aspect is called import coordination . Reading the actual netlist or running programs to extract netlists/schematics is called the import format part.
(Note: loading a schematics in this context means loading netlist plus footprints.)
Following is a long list of what it did wrong and how each problem got fixed by the new design.
1. Mixed coordination and format
The old import schematics tried to do both: coordinate the import and perform the actual import (using gnetlist or make). The main problem with this mis-scoping the feature is that it makes it very hard to extend the system with new formats.
The solution was to cut the problem in two: the new import schematics is doing the coordination only, and does not know anything about file format parsing or executing external programs. Instead it relies on import plugins; each import plugin is responsible for understanding one input format or input flow.
This design is modular: the import plugins are small and simple and a new import plugin can be very easily added without any modification in the import schematics code.
2. Hardwired gnetlist
There were times when gschem was the primary input for pcb-rnd. By now it is already only one of the possible input netlist flows. The original import schematics setup had gnetlist hardwired, which made it unable to load netlist of any other kind, including tEDAx, or running any other external netlist software directly to generate the netlist to load.
The new import schematics plugin does not know anything about gnetlist. Instead, a separate import_gnetlist plugin is provided that can execute gnetlist and load the result. This plugin can be used with import schematics or without, directly using the LoadFrom(Netlist, ...) action.
3. Hardwired make
The alternative mode to gnetlist was make . When configured with the import::mode attribute, the old code ran a semi-hardwired, make-syntax-specific command line and assumed the output would be a pcb-rnd action script. This design has two major flaws:
- it doesn't easily let the user run a shell script or other external software, but insists on make (while the code is not simpler or more secure because of this); the user had to work this around by wrapping their command line in a dummy Makefile
- it forces the external program to emit an action script - effectively limiting the use of the only non-gnetlist mode to gnetlist, as nothing else would produce a netlist in PCB action script format.
The new design removes both assumptions. It is implemented as an import format plugin, called import_net_cmd. It takes an output file name and a command line; it executes the command line and loads the output file as a netlist/schematics, in whatever format pcb-rnd supports.
Since we still want to be able to load and execute action scripts as netlists, a new plugin, import_net_action. If the external program happens to write an action script, the format is auto-detected and the script is loaded and executed, thus the old Makefile+gnetlist setup would work (with minor tweaks in the Makefile).
4. Removed format limitations
Because of 2. and 3., the old method pretty much limited the user to gnetlist and input flow from gEDA.
The new import schematics code is decoupled from file formats. All previously existing netlist/schematics import plugins are accessible from the new coordinator, plus a few new importer got implemented. At the time of writing, the following import plugins/formats are available:
| plugin | format | type |
|---|---|---|
| io_tedax | tEDAx netlist block | sch |
| import_gnetlist | gEDA schematics | sch (multi) |
| import_net_cmd | execute external netlister | sch (multi) |
| import_net_action | execute action script | sch (multi) |
| import_netlist | old gEDA/PCB netlist | net |
| import_ipcd36 | IPC-D-356 netlist | net |
| import_edif | EDIF netlist | net |
| import_fpcb_nl | FreePCB netlist | sch |
| import_tinycad | TinyCAD netlist | sch |
| import_ltspice | LTSpice netlist | sch |
| import_mentor_sch | Mentor Design Capture | sch |
| import_calay | Calay netlist | sch |
5. one-time imports
Because the old system didn't support any other file format, the code we inherited has custom actions for other netlist formats.
Meanwhile pcb-rnd developed an netlist import framework, with format autodetection and plugin preferences (priorities). The action LoadFrom(Netlist, ...) will do a one-time import of a netlist or schematics, with format detection. One-time import means it will not remember the input file name or file format after the action. But in return it does not require any setup. Ideal for scripts.
Note: ImportSch() uses a preconfigured file format because that is safer for a known input workflow. An exception is import_net_cmd, which has to autodetect the output file format as arbitrary command can be executed which can produce the result in any format. On the other hand, LoadFrom(Netlist, ...) autodetects the file format.
6. Better configuration: CLI
The old code did not have much setup: the user specified a file name and it remembered that and assumed the method was gnetlist. If the user wanted anything else, they had to edit board attributes.
The new action, ImportSch(), has a setup command which allows the user to use the command line to do the basic configuration of the import. For example:
ImportSch(setup, tEDAx, foo.tdx)
configures import schematics to use the tEDAx netlist format and load foo.tdx when ImportSch() is executed without arguments.
7. Better configuration: GUI
ImportSch(dialog) pops up a dialog box that allows the user to configure the import graphically. The dialog has a list of available formats and understands which format requires a single file name and which format accepts multiple file names.