# Data structure design discussion

# Concept diagram

(Inspired by gnetman, by Bill Cox)

## Concepts behind the structures

### Design

This is might not exist as a “file”, as such, but exists as a data structure entity to be the owner of the circuits required in a particular design. The “root circuit” is the uppermost level of hierarchy.

### Circuit

A circuit entity is the key concept in this model. It defines an electrical block by a its external connections (MPorts). A schematic is one way of representing a circuit, hence a circuit object may own or more page of schematics.

We may also define a symbolic (graphic) representation of a circuit - this is like a schematic page, however its representation should fit within a single sheet. The minimum a symbolic representation must contain is the pins which connect it to higher levels of circuit hierarchy.

### MPort

If it is to be useful as a re-usable block, a sub-circuit must expose electrical connectivity for a parent circuit to connect with. Each such connection is represented by an Mport (Master port). This term (re-used from gnetman) represents the fact that once a circuit is instantiated, we need to differentiate between the connections of each specific instance. This is done with instance specific Port structures. The ports point back at the Mports (master ports) of the circuit representation.

### Instance

A circuit represents a re-usable electrical entity which we may replicate at various points in our design hierarchy. This is done by instantiating the sub-circuit in a higher level of hierarchy. Each instance is associated with an Instance structure, which is a placeholder for instance specific attributes such as the sub-circuit's hierarchical refdes.

### Attrib

An Attrib defines meta-data attached which might be attached to a circuit, a circuit's Mport, a specific circuit instance, or a Net.

In a break from gEDA's current attrib model, it makes sense to associate the meta-data directly with the particular entity it pertains to, rather than the graphic representation. This is because some forms of sub-circuit entity may be defined without a schematic, and could still require this meta-data. It will be possible to reference any attrib within the realm of a circuit for display on its schematic page(s) where that is desired.

### Netlist

A Netlist defines the electrical connectivity of a circuit. It owns a number of Nets, which individually represent a single connection between Mports belonging to this circuit, and ports of instantiated sub-circuits.

Initially, it is likely there will only be one netlist for a circuit - the one constructed from processing the electrically relevant objects on page(s) of the circuit's schematic.

Future developments may see multiple netlists for a circuit, possibly some generated / written in an HDL language, and critically, re-exported from a layout package (e.g. PCB). It will be possible to identify and flag up differences in connectivity throughout a design flow, be that from HDL to schematic, or schematic to layout.

This has real applications in back-annotation and in design verification.

### Net

A net associates with structures forming a given electrical connection within this circuit.

As we also have a graphical representation of the wires (ConnSegments) which make up this connection, each Net can be associated with multiple ConnSegments. The association to Pins representing Mports of this circuit and to the Pins of any instantiated sub-circuits is made via a net's association to the appropriate Mport and port structures.

### Page

A page is a canvas for placing graphical objects representing a circuit. A page can be used to draw an electrically meaningful schematic, or it can be used to draw a symbolic representation of the circuit entity.

Whilst most objects on a page are graphic primitives, there are some which have a relation to the circuit's electrical specification.

- ConnSegments (or nets) represent connected electrical signals within the circuit represented.
  - A connectivity representation (netlist) can be built by considering the end-point positioning of these objects.
  - ConnSegment is intended to be a generalisation of nets and buses for the purpose of this diagram.

- Pins represent a connection outside this circuit.
  - When constructing a netlist, coincidence of a ConnSegment end on these implies an electrical connection to that external port.
  - Each pin (or group of pins?) represent an external electrical connection with this circuit.
  - There is a necessary link between a pin and the circuit's Mport which it represents.

- complex objects represent instantiating a sub-circuit, and will be linked to a specific instance structure.
  - Graphically, this means a symbolic representation of the instantiated circuit will be placed on the page.
  - Nets ending co-incident with the pins of that embedded symbol represent electrical connectivity with the instantiated sub-circuit entity.

# Brainstorms

(from conversation on MSN/IRC on 10th April 2007 – Peter Brett / Peter Clifton)

- In order to do back annotation, need to be able to change the board part references for anywhere in the schematic. It then makes sense to dissociate the concepts of InstanceID and Board Reference, and use an override table that can override an attribute at any given path within the current circuit based on a path composed of InstanceIDs. InstanceIDs would be special-cased throughout libgeda as a means for uniquely identifying circuits and instances. An entry in the override table might have the form “/id1/id2/id3:refdes:U3”

- It might be useful to allow nets to have attributes, for instance to specify minimum copper width and spacing for a net, independently from the attributes of net segments.

- The schematic editor needs to have sidebars for browsing hierarchy and inspecting attributes. This needs to include a way of seeing where the attributes have been inherited from.

- We need to do lazy netlisting, on a circuit-by-circuit basis – the netlists should only be combined into a flat netlist when required by a tool (and even then, most tools can potentially make good use of hierarchy information).

- In order to make finding objects by hierarchical path fast (e.g. to implement override tables discussed above) there needs to be a fast way of generating unique identifiers for objects (e.g. 32-bit ints) that can then be used as keys in hashtables.