docs/wiki/geda-data_structure_design_discussion.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   2  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html>
   4 <head>
   5   <link rel="stylesheet" media="screen" type="text/css" href="./style.css" />
   6   <link rel="stylesheet" media="screen" type="text/css" href="./design.css" />
   7   <link rel="stylesheet" media="print" type="text/css" href="./print.css" />
   8
   9   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  10 </head>
  11 <body>
  12
  13 <h1 class="sectionedit1" id="data_structure_design_discussion">Data structure design discussion</h1>
  14 <div class="level1">
  15
  16 </div>
  17 <!-- EDIT1 SECTION "Data structure design discussion" [1-48] -->
  18 <h1 class="sectionedit2" id="concept_diagram">Concept diagram</h1>
  19 <div class="level1">
  20
  21 <p>
  22 (Inspired by gnetman, by Bill Cox)
  23 </p>
  24
  25 <p>
  26 <a href="/./lib/exe/fetch.php?tok=2fc1e8&amp;media=http%3A%2F%2Fwww2.eng.cam.ac.uk%2F~pcjc2%2Fgeda%2Fdatastructures.png" class="media" title="http://www2.eng.cam.ac.uk/~pcjc2/geda/datastructures.png"><img src="media/http///www2.eng.cam.ac.uk/~pcjc2/geda/datastructures.png" class="media" alt="" /></a>
  27 </p>
  28
  29 </div>
  30 <!-- EDIT2 SECTION "Concept diagram" [49-178] -->
  31 <h2 class="sectionedit3" id="concepts_behind_the_structures">Concepts behind the structures</h2>
  32 <div class="level2">
  33
  34 </div>
  35 <!-- EDIT3 SECTION "Concepts behind the structures" [179-222] -->
  36 <h3 class="sectionedit4" id="design">Design</h3>
  37 <div class="level3">
  38
  39 <p>
  40 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.
  41 </p>
  42
  43 </div>
  44 <!-- EDIT4 SECTION "Design" [223-446] -->
  45 <h3 class="sectionedit5" id="circuit">Circuit</h3>
  46 <div class="level3">
  47
  48 <p>
  49 A <strong>circuit</strong> entity is the key concept in this model. It defines an electrical block by a its external connections (<strong>MPort</strong>s). A schematic is one way of representing a circuit, hence a circuit object may own or more <strong>page</strong> of schematics.
  50 </p>
  51
  52 <p>
  53 We may also define a <strong>symbolic</strong> (graphic) representation of a circuit - this is like a schematic <strong>page</strong>, however its representation should fit within a single sheet. The minimum a symbolic representation must contain is the <strong>pins</strong> which connect it to higher levels of circuit hierarchy.
  54 </p>
  55
  56 </div>
  57 <!-- EDIT5 SECTION "Circuit" [447-1004] -->
  58 <h3 class="sectionedit6" id="mport">MPort</h3>
  59 <div class="level3">
  60
  61 <p>
  62 If it is to be useful as a re-usable block, a sub-<strong>circuit</strong> must expose electrical connectivity for a parent <strong>circuit</strong> to connect with. Each such connection is represented by an <strong>Mport</strong> (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 <strong>Port</strong> structures. The <strong>port</strong>s point back at the <strong>Mport</strong>s (master ports) of the circuit representation.
  63 </p>
  64
  65 </div>
  66 <!-- EDIT6 SECTION "MPort" [1005-1541] -->
  67 <h3 class="sectionedit7" id="instance">Instance</h3>
  68 <div class="level3">
  69
  70 <p>
  71 A <strong>circuit</strong> represents a re-usable electrical entity which we may replicate at various points in our design hierarchy. This is done by instantiating the sub-<strong>circuit </strong> in a higher level of hierarchy. Each instance is associated with an <strong>Instance</strong> structure, which is a placeholder for instance specific attributes such as the sub-circuit&#039;s hierarchical refdes.
  72 </p>
  73
  74 </div>
  75 <!-- EDIT7 SECTION "Instance" [1542-1929] -->
  76 <h3 class="sectionedit8" id="attrib">Attrib</h3>
  77 <div class="level3">
  78
  79 <p>
  80 An <strong>Attrib</strong> defines meta-data attached which might be attached to a <strong>circuit</strong>, a <strong>circuit</strong>&#039;s <strong>Mport</strong>, a specific <strong>circuit</strong> <strong>instance</strong>, or a <strong>Net</strong>.
  81 </p>
  82
  83 <p>
  84 In a break from gEDA&#039;s current <strong>attrib</strong> 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-<strong>circuit</strong> entity may be defined without a schematic, and could still require this meta-data. It will be possible to reference any <strong>attrib</strong> within the realm of a <strong>circuit</strong> for display on its schematic <strong>page</strong>(s) where that is desired.
  85 </p>
  86
  87 </div>
  88 <!-- EDIT8 SECTION "Attrib" [1930-2569] -->
  89 <h3 class="sectionedit9" id="netlist">Netlist</h3>
  90 <div class="level3">
  91
  92 <p>
  93 A <strong>Netlist</strong> defines the electrical connectivity of a <strong>circuit</strong>. It owns a number of <strong>Net</strong>s, which individually represent a single connection between <strong>Mport</strong>s belonging to this <strong>circuit</strong>, and <strong>ports</strong> of instantiated sub-<strong>circuits</strong>.
  94 </p>
  95
  96 <p>
  97 Initially, it is likely there will only be one netlist for a <strong>circuit</strong> - the one constructed from processing the electrically relevant objects on <strong>page</strong>(s) of the <strong>circuit</strong>&#039;s schematic.
  98 </p>
  99
 100 <p>
 101 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.
 102 </p>
 103
 104 <p>
 105 This has real applications in back-annotation and in design verification.
 106 </p>
 107
 108 </div>
 109 <!-- EDIT9 SECTION "Netlist" [2570-3435] -->
 110 <h3 class="sectionedit10" id="net">Net</h3>
 111 <div class="level3">
 112
 113 <p>
 114 A <strong>net</strong> associates with structures forming a given electrical connection within this <strong>circuit</strong>.
 115 </p>
 116
 117 <p>
 118 As we also have a graphical representation of the wires (<strong>ConnSegment</strong>s) which make up this connection, each <strong>Net</strong> can be associated with multiple <strong>ConnSegment</strong>s. The association to <strong>Pins</strong> representing <strong>Mport</strong>s of this <strong>circuit</strong> and to the <strong>Pins</strong> of any instantiated sub-<strong>circuits</strong> is made via a <strong>net</strong>&#039;s association to the appropriate <strong>Mport</strong> and <strong>port</strong> structures.
 119 </p>
 120
 121 </div>
 122 <!-- EDIT10 SECTION "Net" [3436-3940] -->
 123 <h3 class="sectionedit11" id="page">Page</h3>
 124 <div class="level3">
 125
 126 <p>
 127 A <strong>page</strong> is a canvas for placing graphical objects representing a circuit. A <strong>page</strong> can be used to draw an electrically meaningful schematic, or it can be used to draw a symbolic representation of the circuit entity.
 128 </p>
 129
 130 <p>
 131 Whilst most objects on a <strong>page</strong> are graphic primitives, there are some which have a relation to the <strong>circuit</strong>&#039;s electrical specification.
 132 </p>
 133 <ul>
 134 <li class="level1 node"><div class="li"> <strong>ConnSegments</strong> (or <strong>net</strong>s) represent connected electrical signals within the circuit represented.</div>
 135 <ul>
 136 <li class="level2"><div class="li"> A connectivity representation (<strong>netlist</strong>) can be built by considering the end-point positioning of these objects.</div>
 137 </li>
 138 <li class="level2"><div class="li"> <strong>ConnSegment</strong> is intended to be a generalisation of <strong>net</strong>s and <strong>bus</strong>es for the purpose of this diagram.</div>
 139 </li>
 140 </ul>
 141 </li>
 142 </ul>
 143 <ul>
 144 <li class="level1 node"><div class="li"> <strong>Pins</strong> represent a connection outside this circuit.</div>
 145 <ul>
 146 <li class="level2"><div class="li"> When constructing a netlist, coincidence of a <strong>ConnSegment</strong> end on these implies an electrical connection to that external port.</div>
 147 </li>
 148 <li class="level2"><div class="li"> Each <strong>pin</strong> (or group of pins?) represent an external electrical connection with this <strong>circuit</strong>.</div>
 149 </li>
 150 <li class="level2"><div class="li"> There is a necessary link between a <strong>pin</strong> and the circuit&#039;s <strong>Mport</strong> which it represents.</div>
 151 </li>
 152 </ul>
 153 </li>
 154 </ul>
 155 <ul>
 156 <li class="level1 node"><div class="li"> <strong>complex</strong> objects represent instantiating a sub-<strong>circuit</strong>, and will be linked to a specific <strong>instance</strong> structure.</div>
 157 <ul>
 158 <li class="level2"><div class="li"> Graphically, this means a <strong>symbolic</strong> representation of the instantiated circuit will be placed on the page.</div>
 159 </li>
 160 <li class="level2"><div class="li"> Nets ending co-incident with the <strong>pins</strong> of that embedded symbol represent electrical connectivity with the instantiated sub-<strong>circuit</strong> entity.</div>
 161 </li>
 162 </ul>
 163 </li>
 164 </ul>
 165
 166 </div>
 167 <!-- EDIT11 SECTION "Page" [3941-5460] -->
 168 <h1 class="sectionedit12" id="brainstorms">Brainstorms</h1>
 169 <div class="level1">
 170
 171 <p>
 172 (from conversation on MSN/<abbr title="Internet Relay Chat">IRC</abbr> on 10th April 2007 – Peter Brett / Peter Clifton)
 173 </p>
 174 <ul>
 175 <li class="level1"><div class="li"> 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 <strong>InstanceID</strong> and <strong>Board Reference</strong>, and use an <strong>override table</strong> that can override an attribute at any given path within the current <strong>circuit</strong> based on a path composed of <strong>InstanceID</strong>s.  <strong>InstanceID</strong>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”</div>
 176 </li>
 177 </ul>
 178 <ul>
 179 <li class="level1"><div class="li"> 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.</div>
 180 </li>
 181 </ul>
 182 <ul>
 183 <li class="level1"><div class="li"> 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.</div>
 184 </li>
 185 </ul>
 186 <ul>
 187 <li class="level1"><div class="li"> 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).</div>
 188 </li>
 189 </ul>
 190 <ul>
 191 <li class="level1"><div class="li"> 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.</div>
 192 </li>
 193 </ul>
 194
 195 </div>
 196 <!-- EDIT12 SECTION "Brainstorms" [5461-] --></body>
 197 </html>