====== Data structure design discussion ======

====== Concept diagram ======

(Inspired by gnetman, by Bill Cox)

{{http://www2.eng.cam.ac.uk/~pcjc2/geda/datastructures.png}}


===== 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 (**MPort**s). 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 **port**s point back at the **Mport**s (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 **Net**s, which individually represent a single connection between **Mport**s 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 (**ConnSegment**s) which make up this connection, each **Net** can be associated with multiple **ConnSegment**s. The association to **Pins** representing **Mport**s 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 **net**s) 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 **net**s and **bus**es 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 **InstanceID**s.  **InstanceID**s 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.