Differences

This shows you the differences between two versions of the page.

--- gnucap:user:netlist_import_and_export [2024/07/09 19:01]
aldavis [Adding physical position]
+++ gnucap:user:netlist_import_and_export [2025/06/28 02:01] (current)
felixs fix reference to r2 (was: p2)
@@ Line 138: / Line 138: @@
   module amp (a, c);
-A "module" is the unit of encapsulation.  This one is called "amp", and it has two connections to outside, "a" and "c".
+A //module// is the unit of encapsulation.  This one is called ''amp'', and it has two connections to outside, ''a'' and ''c''.
   resistor #(.r(1k)) r1 (.p(a), .n(b));
-This line instantiates a "resistor".  It could be a symbol, a device, a footprint, depending on the application.
+This line instantiates a ''resistor''.  It could be a symbol, a device, a footprint, depending on the application.
-The "#" introduces a parameter list.  "r" is the name of a parameter.  "1k" is the value (a string).
+The ''#'' introduces a parameter list.  ''r'' is the name of a parameter.  ''1k'' is the value (a string).
-"r1" is the instance name,
+''r1'' is the instance name,
-It has two pins, named "p" and "n'.  Node "b" connects to pin "p" and node "c" connects to pin "n".
+It has two pins, named ''p'' and ''n''.  Node ''a'' connects to pin ''p'' and node ''b'' connects to pin ''n''.
-The type ("resistor") refers to a model in simulation.  In layout or schematic, it would refer to a footprint, indirectly.
+The type (''resistor'') refers to a model in simulation.  In layout or schematic, it would refer to a footprint, indirectly.
 In simulation, the models often come from some place external, or might come with the simulator.  You might substitute different models for the same device, depending what you want to do.
@@ Line 161: / Line 161: @@
   module amp (.a(a0), .c(c0));
+    ground gnd;
     resistor #(.r(1k)) r1 (.p(a1), .n(b1));
     resistor #(.r(1k)) r2 (.p(b2), .n(c2));
-    opamp741 #(.gain(100k)) u1 (.p(c3), .n(0), .ps(0), .pn(b3));
+    opamp741 #(.gain(100k)) u1 (.p(c3), .n(gnd), .ps(gnd), .pn(b3));
-    net a (.1(a0), .2(a1));
+    net a (a0, a1);
-    net b (.1(b1), .2(b2), .3(b3));
+    net b (b1, b2, b3);
-    net c (.1(c0), .2(c2), .3(c3));
+    net c (c0, c2, c3);
   endmodule
-We have replaced the nodes with nets, which are now first class objects.
+We have replaced the nodes with nets, which are now first class objects.   This will give us a way to represent the interconnect in a schematic drawing or a layout.  It also provides essential data to support analysis and simulation of the interconnect.
-Looking at net "b" as an example, it has 3 connections : r1 pin n, p2 pin p, and u1 pin pn.
+Looking at net ''b'' as an example, it has 3 connections : ''r1'' pin ''n'', ''r2'' pin ''p'', and ''u1'' pin ''pn''.
+What is a "net"?  It depends how you look at it.  It could be the lines on a schematic, or the traces on a PC board.  If we are doing a Spice-type simulation, we would want to collapse it into a single node.  So we might define:
+  module net (.a(z), .b(z), .c(z), .d(z), .e(z), .f(z));
+  endmodule
+This definition gives us up to 6 connections (a,b,c,d,e,f) as seen from outside, all connected together internally, which has the effect of collapsing it all down to one.
+==== The "rail" device ====
+We use rail devices with a single port to make connections to designated circuit nodes, possibly across hierarchy. This removes the need for "global" nodes, which are known from Spice and prone to error.
+  module amp(.a(a0), .c(c0), .vdd(vdd));
+    [..]
+    electrical vdd; // rvv connects to here.
+    rail #(.node("vdd")) rvv(vv);
+    op #(.gain(100k)) u1 (.p(c3), .n(nn), .ps(b2), .pn(b3), .vdd(vv), .vss(nn1));
+    rail #(.node("gnd")) rg1(nn);
+    rail #(.node("gnd")) rg2(nn2);
+    net nn(nn1, nn2);
+    [..]
+  endmodule
+  module top();
+    ground gnd; // <= a0.rg1 and a0.rg2 connect to here.
+    amp a0(a, b, v);
+    [..]
+  endmodule
+A possible rail implementation may look like this
+  module rail(n);
+    electrical n;
+    parameter string node = "(nothing)";
+    analog initial begin
+      if(!$analog_node_alias(n, node))
+         $error("dangling rail, cannot find %s\n", node);
+    end
+  endmodule
+The rail connects to the node of the given name found by upwards traversal through the hierarchy. In particular, a rail does not create a node.
 ==== Verilog "system" parameters ====
-The Verilog standard defines some "system" parameters for all devices to show position.
+The Verilog standard defines some "hierarchical system parameters" (HSP) for all devices to show position.
   * $xposition (x coordinate, in meters)
@@ Line 184: / Line 225: @@
   * $vflip (flag: flip vertically, +1=no flip, -1=flip)
-These "system" parameters are real parameters, so we won't use them here.  We will use them as inspiration for "attributes" instead.
+These HSPs are real parameters, i.e. carry a physical meaning. Hence we will not use them to store schematic markup. We will use them as inspiration for positioning "attributes" instead.
+HSPs will generally be treated as ordinary parameters, but are subject to special semantics that attributes are not meant to carry. For backwards compatibility, all parameters with a name starting with '$' must be passed on like attributes and without interpretation where they have no meaning.
+The current standard misses out on HSPs that correspond to global options in legacy tools. In the future, HSPs such as $temperature, $dtemp, $method or $mode should be supported to localise such global options as required, but without workarounds.
 ==== Verilog "attributes" ====
-The Verilog standard gives a way to add "attributes" to just about anything.
+The Verilog standard gives a way to add "attributes" to just about anything. We are referring to
+//a mechanism [..] included for specifying properties about objects, statements and groups of statements in the HDL
+source that can be used by various tools// in IEEE1364 Section 3.8.
   (* attribute = value *) resistor r1 (.p(2), .n(3));
@@ Line 198: / Line 244: @@
 | PC     | Printed Circuit Layout |
 | L      | IC Layout              |
 We add a third dimension "z", and a third flip "zflip".  We shorten xposition to x, yposition to y, and add a number to have multiple positions.  The "z" may indicate a layer name instead of a dimension, depending on the application.
 ==== Adding physical position ====
-Now we use the attributes to specify the location.  All positions indicate a place where a connection is made, or could be made.  Then the positions of things that connect there can be determined.  I am thinking schematic for now, but the same concept applies to layout.  It is not necessary to place all of the nodes because others can be implied, but you could as a check or to imply flip and rotate.  If they are inconsistent, rubberbanding would preserve connectivity.  Usually, you can place one node per component, and let the nets float, except that you could add extra nodes to nets so you can place junctions.
+Now we use the attributes to specify the location.  We need to locate the various objects in a suitable [[gnucap:user:schematic_geometry|coordinate system]]. In most cases, we need to specify some point of every object that will identify its location.  Some programs use some notion of a "center", which is ambiguous.  We will use the electrical connection points, often called "pins", as the location points for things that have an electrical connection.  For objects that do not have electrical connections, reference points can be used.
-  module amp (.a(a0), .c(c0));
+We will number the pins, by position, 1, 2, ...  Then we use x1,y1, and so on to locate them.  Usually one of them is adequate to locate an object.  The others can "float", allowing the actual location to be determined by the surroundings.  It is permissible to overspecify locations, provided they are self-consistent, and consistent with connections.
-    (* S0_x1=-5m, S0_y1=0m *)  input a0;
-    (* S0_x1=30m, S0_y1=-3m *) output c0;
+Pin numbering starts at 1 (not 0) to be consistent with most IC and connector pin numbering.  Pin names should be used instead of numbers if the pins have names.
+In addition to the positions, hflip, vflip, and angle are supported.  If there is both a flip and an angle, flip will be done first, then angle.  The angle is specified in degrees counterclockwise, but only 0, 90, 180 and 270 are expected to be supported.
+Another attribute named for the specific tool (example: ''S0_geda'') can be used to stash tool specific data that doesn't fit otherwise.  This is intended to assist with a translation from this format back to the tool format.  Normally, this would be a string containing a composite of the info (''S0_geda="5 10 0 0 0 0 1"'')  If more than one string in a scope is needed, suffixes can be used. (''S0_geda_color="blue" S0_geda_symbol="resistor-1.sym"'')  These are stored and passed on without any interpretation.  For a simple symbol substitution, you might just do ''S0_symbol=";input"'' so the schematic shows the "input" symbol, overriding "inout", which is there for the simulator.
+  module amp (
+    (* S0_x1=-5m, S0_y1=0m, S0_symbol="input" *)  inout  electrical .a(a0), // show symbol ";input", but actual port direction is inout
+    (* S0_x1=30m, S0_y1=-3m *)                    output electrical .c(c0)  // port syntax per SystemVerilog 3.1a, 18,9
+    );                     // a and c are pin names, user specified, outside.  a0 and c0 refer to the node the pin connects to, inside
+                               ground g0;
+                               ground g1;
-    (* S0_x1=0m,  S0_y1=0m *)  resistor #(.r(1k))      r1 (.p(a1), .n(b1));
+    (* S0_x_p=0m,  S0_y_p=0m *) resistor #(.r(1k))      r1 (.p(a1), .n(b1)); // by pin name
-    (* S0_x1=24m, S0_y1=7m *)  resistor #(.r(1k))      r2 (.p(b2), .n(c2));
+    (* S0_x_p=24m, S0_y_p=7m *) resistor #(.r(1k))      r2 (.p(b2), .n(c2));
-    (* S0_x1=25m, S0_y1=-3m *) opamp741 #(.gain(100k)) u1 (.p(c3), .n(0), .ps(0), .ns(b3));
+    (* S0_x1=25m,  S0_y1=-3m *) opamp741 #(.gain(100k)) u1 (c3, g1, g0, b3); // by pin number
-    net a (.1(a0), .2(a1));
+    net a (a0, a1);
-    net b (.1(b1), .2(b2), .3(b3));
+    net b (b1, b2, b3);
-    net c (.1(c0), .2(c2), .3(c3));
+    net c (c0, c2, c3);
   endmodule
   * This is a schematic, using a 1 mm grid.
-  * The location of node "a1" is being used as a reference here, (0,0).  This is the "p" pin of "r1".
+  * The lines "input" and "output" are pins, explicitly located.
-  * The location of node "b2" is (24,7).  This is the "p" pin of "r2".
+  * The lines "resistor" and "opamp741" are components, explicitly located by pin 1 of each, all called "p" here, by coincidence.
-  * The location of node "c3" is (25,-3).  This is the "p" pin of "u1".
+  * The lines "ground" are the ground symbol.  The first is node "g0", which is the "ps" pin ("+" input, pin 2) of "u1", so it is implicitly located there.  The other is node "g1", which is the "n" pin (pin 1) of "u1", so this one is also implicitly located.  An explicit location could have been specified, but is not necessary because it can be determined by the symbol for "u1".
   * The location of other nodes will follow based on the symbol or footprint geometry.
   * It is ok to leave some, or even most, unspecified, so they will be located by context.
   * It is ok to locate a node more than once, provided the locations are the same.
   * If locations of the same node are not the same, the tool shall issue a warning, and make a correction to assure connectivity is correct.
-  * Locating one node of a footprint or symbol determines the location of the symbol or footprint.
+  * Locating one pin (usually pin one) of a footprint or symbol determines the location of the symbol or footprint.
   * In the above example, the I/O pins and components have been explicitly located.
   * The nets have been implicitly located.
@@ Line 233: / Line 290: @@
 The choice of which nodes to locate could have been different.  The following example produces exactly the same result.
+  module amp (.a(a0), .c(c0)); // port syntax per IEEE 1364-2005
+    input  electrical a0;  // a0, not a.  a0 is inside the module.  a is outside.
+    output electrical c0;  // see IEEE 1364-2005 12.3.3
+    ground g0;
+    ground g1;
+    resistor #(.r(1k))      r1 (.p(a1), .n(b1));
+    resistor #(.r(1k))      r2 (.p(b2), .n(c2));
+    opamp741 #(.gain(100k)) u1 (.p(c3), .n(g1), .ps(g0), .ns(b3));
+    (* S0_x1=-5m, S0_y1=0m,  S0_x1=0m,  S0_y1=0m *)  net a (a0, a1);
+    (* S0_x2=24m, S0_y2=7m *)                        net b (b1, b2, b3);
+    (* S0_x1=30m, S0_y1=-3m, S0_x2=25m, S0_y2=-3m *) net c (c0, c2, c3);
+  endmodule
+The following example is over determined, but legal, and produces the same result.
+  module amp (
+    (* S0_x1=-5m, S0_y1=0m *)  inout  electrical .a(a0),
+    (* S0_x1=30m, S0_y1=-3m *) output electrical .c(c0),
+    );
+                               ground g0;
+                               ground g1;
+    (* S0_x1=0m,  S0_y1=0m *)  resistor #(.r(1k))      r1 (.p(a1), .n(b1));
+    (* S0_x1=24m, S0_y1=7m *)  resistor #(.r(1k))      r2 (.p(b2), .n(c2));
+    (* S0_x1=25m, S0_y1=-3m *) opamp741 #(.gain(100k)) u1 (.p(c3), .n(g1), .ps(g0), .ns(b3));
+    (* S0_x1=-5m, S0_y1=0m,  S0_x2=0m,  S0_y2=0m *)  net a (a0, a1);
+    (* S0_x2=24m, S0_y2=7m *)                        net b (b1, b2, b3);
+    (* S0_x1=30m, S0_y1=-3m, S0_x3=25m, S0_y3=-3m *) net c (c0, c2, c3);
+  endmodule
+==== Multiple applications, both layout and schematic ====
+Markups can be combined.  In this example, schematic ''S0_'' and printed circuit ''PC0_'' are combined in a single file.
   module amp (.a(a0), .c(c0));
@@ Line 242: / Line 336: @@
     opamp741 #(.gain(100k)) u1 (.p(c3), .n(0), .ps(0), .ns(b3));
-    (* S0_x1=-5m, S0_y1=0m,  S0_x2=0m,  S0_y2=0m *)  net a (.1(a0), .2(a1));
+    (* S0_x1=-5m, S0_y1=0m,  S0_x2=0m,  S0_y2=0m,  PC0_x1=-5m, PC0_y1=0m,  PC0_x2=0m,  PC0_y2=0m *)  net a (a0, a1);
-    (* S0_x2=24m, S0_y2=7m *)                        net b (.1(b1), .2(b2), .3(b3));
+    (* S0_x2=24m, S0_y2=7m *)                   (* PC0_x2=24m, PC0_y2=7m *)                          net b (b1, b2, b3);
-    (* S0_x1=30m, S0_y1=-3m, S0_x1=25m, S0_y1=-3m *) net c (.1(c0), .2(c2), .3(c3));
+    (* S0_x1=30m, S0_y1=-3m, S0_x3=25m, S0_y3=-3m, PC0_x1=30m, PC0_y1=-3m, PC0_x3=25m, PC0_y3=-3m *) net c (c0, c2, c3);
   endmodule
-==== Multiple applications, both layout and schematic ====
+Portions that apply in only certain contexts can be selectively included with '''ifdef''.  This may be useful when the component list needs to be different for the different applications, such as when the nets have different forms for a different route or parameters.  Macros like ''%%__S0__%%'' and ''%%__S0__geda__%%'' are automatically predefined if appropriate.  These macros should not be defined in the file, except temporarily for debugging.
-Portions that apply in only certain contexts can be selectively included with 'ifdef:
   module amp (.a(a0), .c(c0));
-    resistor #(.r(1k)) r1 (.p(a1), .n(b1));
+    input a0;
-    resistor #(.r(1k)) r2 (.p(b2), .n(c2));
+    output c0;
-    opamp741 #(.gain(100k)) u1 (.p(c3), .n(0), .ps(0), .pn(b3));
-    net a (.1(a0), .2(a1));
+    resistor #(.r(1k))      r1 (.p(a1), .n(b1));
-    net b (.1(b1), .2(b2), .3(b3));
+    resistor #(.r(1k))      r2 (.p(b2), .n(c2));
-    net c (.1(c0), .2(c2), .3(c3));
+    opamp741 #(.gain(100k)) u1 (.p(c3), .n(0), .ps(0), .ns(b3));
-  `ifdef SCHEMATIC
+  `ifdef __S0__
-    place #(.$xposition(24m), .$yposition(7m))  place_b2 (b2);
+    (* S0_x1=-5m, S0_y1=0m,  S0_x2=0m,  S0_y2=0m *)  net a (a0, a1);
-    place #(.$xposition(0m),  .$yposition(0m))  place_a1 (a1);
+    (* S0_x2=24m, S0_y2=7m *)                        net b (b1, b2, b3);
-    place #(.$xposition(25m), .$yposition(-3m)) place_c3 (c3);
+    (* S0_x1=30m, S0_y1=-3m, S0_x3=25m, S0_y3=-3m *) net c (c0, c2, c3);
-  `endif
+  `elsif __PC0__
-  `ifdef LAYOUT
+    (* PC0_x1=-5m, PC0_y1=0m,  PC0_x2=0m,  PC0_y2=0m *)  net a (a0, a1);
-    place #(.$xposition(1000u), .$yposition(0u)) place_b2 (b2);
+    (* PC0_x2=24m, PC0_y2=7m *)                          net b (b1, b2, b3);
-    place #(.$xposition(0m),    .$yposition(0u)) place_a1 (a1);
+    (* PC0_x1=30m, PC0_y1=-3m, PC0_x3=25m, PC0_y3=-3m *) net c (c0, c2, c3);
-    place #(.$xposition(2000u), .$yposition(0u)) place_c3 (c3);
+  `else
+    net a (a0, a1);
+    net b (b1, b2, b3);
+    net c (c0, c2, c3);
   `endif
   endmodule
 ==== Mapping to the application ====
-Paramset and module can be used, with ifdef, to add info that may be needed for particular applications.
+It is intended that the verilog type (resistor, opamp741, net in this example) and the parameter lists (''#(...)'') could be used directly by a simulator or other tool, but also allowing substitution using whatever mechanism the tool provides, which could be __module__ or __paramset__ in Verilog.
-  `ifdef GSCHEM
+For symbols (in schematics) or footprints (layout), ideally this mapping would be resolved automatically globally.  Alternatively, in could be resolved locally using an attribute.
-    paramset opamp741 symbol
-      .file(opamp4.sym);
-    paramset resistor symbol
-      .file(resistor2.sym);
-  `endif
-  `ifdef SIMULATION
-    module opamp741 ( .....
-      .....
-    endmodule
-  `endif
-==== Complex nets can be encapsulated ====
+  (* S0_geda_symbol="resistor2.sym" *) resistor #(10k) r4 (a,b);
+==== Non-circuit items ====
-  module net23842 (1,2,3);
+In addition to this, nearly all schematics have text or drawings that are not part of the circuit.  In this case we use dummy devices, with type name beginning with an ''S''''_''''_'' prefix. For text, the position is the point where the base line begins.
-    net n23482 (1,2);
-    net n84333 (2,3);
-    `ifdef SCHEMATIC
-      place ...
-      place ...
-      place ...
-    `endif
-  endmodule
-  module net9393 (1,2);
+  (* S0_x=1.5u, S0_y=1.5u, S0_text="This is some text" *) S__text text42();
-    net #(.color(blue), .thickness(thin)) n38423 (1,2);
-  endmodule
+Generic application dependent graphics objects should be represented by objects of type ''S_''''_graphics'', with attributes as required by a specific application, and optionally, ''S0_x/y'' attributes to indicate a ballpark position.
+  (* S0_x=4.5u, S0_y=5.5u, mytool_shape="triangle", more_attributes=[..] *) S__graphics t1();
+In order to ignore such objects in a simulator or similar context, declarations such as
-==== Hierarchy ====
+  module S__text();
+  endmodule;
+  module S__graphics();
+  endmodule;
+are required within the corresponding device library.
-The system supports hierarchy.
+==== PC boards ====
+PC boards are similar to schematics, with some additional features, and possibly different interpretation.
+On a schematic, a "net" is just connections, and objects in the schematic directly map to devices.  On a PC board, it can start at that, which enables basic simulation and bi-directional conversion between board and schematic.  When simulating a PC board, there are many ways to do that, and other types of models are often substituted.
+The meaning of a "net" could be:
+  * A connection, like a schematic.  Its connections are collapsed.
+  * A transmission line.  It then could have parameters, usually that would be a trace width and layer identifier.  It could easily map to a transmission line model, with attributes that could be used to extract data for signal integrity modeling.
+  * A delay.  Delays can be calculated from length.
+The symbols on a schematic map to footprints on a layout.  They could be the same, or could substitute alternate models for signal integrity, such as IBIS models.  This is one reason that it is best that the Verilog type should not be exactly a simulation model, but rather something that can be mapped by a paramset, with different models for different uses.
+A layout needs to add **stackup** information, which would be attributes of the enclosing **module**.
+==== Chip layout ====
+This method could apply to chip layout too, but requires more study, because the symbol/footprint concept is not used in chip layout, and what you can do is more tied to process specifics.
+==== Examples ====
+ - [[gnucap:user:netlist_import_and_export:geda|gEDA/Lepton schematics]]
+ - [[gnucap:user:netlist_import_and_export:qucs|Qucs (reworked) schematics]]
-  module twoamps (in, out);
-    amp a1 (in, mid1);
-    amp a2 (mid2, out);
-    net mid (mid1, mid2);
-  'ifdef SCHEMATIC
-    place #(.$xposition(0),   .$yposition(0)) place_in  (in);
-    place #(.$xposition(30m), .$yposition(0)) place_mid (mid2);
-  'endif
-  endmodule