The old netlist code is written around the GUI, not around a clean data model:
We normally work with a flat netlist. The netlist represents copper connections on the board. In the same time subcircuits are black boxes: we do have some information about them (e.g. internal connections between terminals) but we generally have no idea about what network is in there.
This setup is fine as long as a subcircuit represents an "atomic" component, e.g. an integrated circuit: we know it's really a bunch of transistors and wiring, but we are not interested in modelling it, for the pcb layout it is enough to place the terminals and take it as a black box.
However, the other important application of subcircuits will be reusable PCB layout modules. This requires subc-in-subc support, so such a module can contain further subcircuits (for parts).
A trivial example is a stereo audio amplifier: the user draws one channel as a subcircuit on the schematics and then a higher level schematic page will reference two channels. In pcb-rnd the user will be able to draw one channel as a subcircuit and then place two of them on the board. A channel would include a lot of wiring, vias and of course a few subcircuits for the parts (e.g. transistors) - this is subc-in-subc.
The above stereo amplifier would work like this. pcb-rnd would get a hierarchical netlist:
First let's assume the user already has the amplifier subcircuit drawn and saved as a subcircuit. When laying out the PCB using the amplifier subcircuit, only the top level board netlist is important. It's still flat, and the whole process is pretty much the same as if the amplifier subcircuits were black boxes: they have terminals to connect to and we have a rather simple task to connect a few connector pins to a few amplifier terminals. The user doesn't even need to know there's an ampch netlist associated with the subcircuit.
When the amplifier subcircuit is placed, refdes for the subc parts become the full path: for A1's T2, it's "A1.T2". This syntax is similar to many netlists' syntax.
The hierarchic netlist starts to play a role when we run connection checks (rats optimization): it will look into A1 and A2 and will figure if connections are not as specified. Then if the user starts to edit the amplifier subcircuit, E.g. ext-edits A1, the relevant netlist section (ampch) is applied there.
An important aspect is that subcircuits will need to have their own netlists: that's how the user can do the initial amplifier channel layout. However, when a subc is imported onto a board, it should lose its own netlist and the board's hierarchical netlist should dictate the subcircuit instance's netlist.
This guarantees that the final board reflects the board netlist. In an optimal situation when the subc was initially drawn, it used the same netlist that ended up in the board's hierarchic netlist as ampch, so it won't make a difference. But in other cases the user is placing an outdated subcircuit, or there was some local change for this particular project in the schematic so board's ampch won't match the actual sucbircuit layout and pcb-rnd will throw errors on rats nest optimization.
At the end, the user interface would not change much: at any given time the user is (mostly) editing one level of the hierarchy, seeing (mostly) a flat netlist associated with that level. Hierarchy will start to matter when the user traverses levels, e.g. edits a subcircuit that represents a complex, non-atomic building block of the board. But this case leads back to (mostly) flat editing too.
On the simple end, for a board that doesn't need hierarchy, this setup doesn't introduce any complication or user visible change.
On the complex end, this setup can be nested to arbitrary depth, yet it will keep each level flat and even the netlist file will be sort of a flat list of netlist blocks. It becomes hierarchic only through how subcircuits refer to netlists. This setup is somewhat similar to how SPICE netlists handle hierarchy.
|module||add new||del old||task|
|core||done||done||netlist infra (structs and functions)|
|core||done||done||maintain both the input and patched netlists, netlist patching, back annotation|
|core||done||done||tool_line.c - new rats drawn in non-brave mode will not create nets that are visible in the brave mode until a board reload|
|done||done||(new) netlist dialog; old user lead circle code deleted|
|dialogs||done||done||dlg_pinout.c (pinout dialog)|
|io_dsn||done||done||netlist I/O - read done|
|io_kicad_legacy||done||done||netlist I/O (has write code only)|
|io_kicad||done||done||netlist I/O - read is not implemented at all|
|export_xy||done||done||pad net name (e.g. for ncap)|
|renumber||done||done||netlist related features|
|report||done||done||netlist related features|
|sketch_route||done||done||netlist related features|
|oldactions||done||done||netlist related features|
|autoroute||done||done||netlist related features|
|autoplace||done||done||netlist related features|
|smartdisperse||done||done||netlist related features|
|hid_lesstif||done||done||netlist dialog - temporary loss of some features; will be fixed by using the new, DAD dialog|