====== File format translation ======

We need a universal translator system that can translate in all directions between Free EDA tools, possible future free EDA tools, and outside tools that are likely to be used with free EDA tools.
===== Scope =====

Of course, everything to everything is not reasonable.  So, set a limit of circuit oriented free EDA tools, possible future tools, and outside tools that are likely to be used them.  Of course, tool formats where translation doesn't make sense don't need to be supported.

Most tools use a format much like a netlist, often with some special information.  So, use a netlist based intermediate format.  First translate to the intermediate format, then translate out.  The intermediate format should be sufficiently expressive that there can be a lossless round trip from the tool format to the intermediate format and back.

Lossless means that the resultant file is equivalent in how it works.  It is not necessary to preserve formatting and other things that don't matter.

All of the formats needing translation presently consist of lists of objects, with some kind of encapsulation.  Each object has connections and attributes.

This suggests the possible of a standard netlist format as the intermediate format.

Further discussion related only to formats that fit this model.

If possible, the format chosen should have a history of use for at least part of this, and have a published specification that is externally controlled and freely available.

There needs to be a way to merge changes from any target/source without messing up other parts.

==== Tool types needing support ====
  * schematic
  * layout
  * simulation

==== Free tools ====
Lossless round trip is required, so archival storage can use the intermediate format.
  * gschem
  * pcb
  * gnucap
  * Icarus Verilog
  * NGspice
  * Qucs
  * Kicad
  * Magic
  * Electric
  * Xcircuit
  * Fritzing

==== Non-free import and export ====
Support for these will allow gEDA tools to play nice with the commercial world.  Basic functionality is needed, but it doesn't need to be lossless.  Lossless should be possible, but it is not a high priority to actually implement it.
  * Eagle
  * Orcad
  * LTspice
  * Pads

==== gEDA missing functionality ====
Hopefully having a translator system will provide a seed so these can be done.
  * Back annotation from layout or simulation to schematic
  * Static timing analysis
  * Post-layout signal integrity simulation.
  * Layout - schematic comparison
  * Use of the same schematic for the whole project.
==== Explicitly not supported ====
  * Plotting
  * Commands
  * Behavioral modeling
  * Translating the symbols or footprints themselves.
===== Concepts =====

All of these consist of lists of objects, with connections and attributes.

It is tradition that a netlist is used for interchange, but the traditional approach only goes one way, because information is lost in the translation.

The format must convey the meaning, not necessarily in the same way as the tool's native format or internal storage.

It is not necessary to translate parts that are usually in libraries, and are tool specific, such as models, symbols, or footprints.

All contenders for possible formats must support a lossless round-trip to any other.

==== Some possible formats ====

=== Spice ===

A popular netlist format.  It has a history of use for interchange, but not yet for physical placement.  Problems: irregular syntax, not sufficiently expressive.  These problems have been a major hassle for years for developers.  It is well accepted, but not by people who know it well.

=== Verilog ===

The structural subset is a good netlist format.  It is regular, sufficiently expressive, and has a published standard.  It has a history of use for interchange, but not yet for physical placement.

=== VHDL ===

The structural subset is a good netlist format.  It is regular, sufficiently expressive, and has a published standard.  It has a history of use for interchange, but not yet for physical placement.

=== Spectre ===

The structural subset is a good netlist format.  It is regular, sufficiently expressive, but belongs to one company (Cadence), so rule it out.  It has a history of use for simulation only.

=== XML ===

XML is not really a format but a syntax.  A good format can easily be made based on XML, but has no history of use in a similar context.  The syntax is well documented but there is no outside documentation of application in any related use.

==== Representation of physical placement ====

This part is the only part where there is not a strong history of use for VHDL and Verilog.

Ideas:

  * Nets are also objects with connections and attributes.  Nets have meaning in all contexts.
  * A place on a schematic can be considered to be an object, with connections and attributes.
  * Pads, connectors, thermals, vias .. are also objects, with connections and attributes.
  * Use `define (assuming Verilog format) to set aside sections that have meaning in one context but not another.
  * This is a high level description.  Take a high level view across all.  It's not lines, boxes, and circles.
  * If you must, lines, boxes, and circles can be objects too, but not translatable because they have no meaning in other contexts.
  * Attributes that have no meaning are silently ignored.  Attributes that have meaning in one context but not in another context are ignored where they have no meaning.

===== Example =====

Choosing the Verilog format as one possibility.

==== Basic Verilog syntax ====

**The unit of encapsulation is the "module":**

  module my-module(connections);
  // contents
  endmodule

**Each object in the list has a consistent syntax:**

  type #(attributes) name (connections);

**Example:**

Here is a simple circuit, plain Verilog, no placement yet.

  module amp (a, c);
    resistor #(.r(1k)) r1 (.p(a), .n(b));
    resistor #(.r(1k)) r2 (.p(b), .n(c));
    opamp741 #(.gain(100k)) u1 (.p(c), .n(0), .ps(0), .pn(b));
  endmodule

Looking at it one line at a time:

  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".

  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.

The "#" introduces a parameter or attribute list.  "r" is the name of an attribute.  "1k" is the value (a string).

"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".

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.

In layout or schematic, the footprints and symbols are not conveyed by this file, and might be changed in a transfer, like you would change a font in a text document.  This provides a mechanism for making changes like from through-hole to surface mount parts.

==== A "net" is also an object. ====

In the above example, both connect to node b directly.  In a schematic or layout representation the connection would not be direct, but through a "net".

  module amp (.a(a0), .c(c0));
    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));
  
    net a (.1(a0), .2(a1));
    net b (.1(b1), .2(b2), .3(b3));
    net c (.1(c0), .2(c2), .3(c3));
  endmodule

We have replaced the nodes with nets, which are now first class objects.

Looking at net "b" as an example, it has 3 connections : r1 pin n, p2 pin p, and u1 pin pn.

==== Verilog "system" parameters ====

The Verilog standard defines some "system" parameters for all devices to show position.

  * $xposition (x coordinate, in meters)
  * $yposition (y coordinate, in meters)
  * $angle (rotation, in degrees)
  * $hflip (flag: flip horizontally, +1=no flip, -1=flip)
  * $vflip (flag: flip vertically, +1=no flip, -1=flip)

==== Adding physical position ====

We could use those parameters to locate the instances explicitly, but that makes it difficult to simultaneously support layout and schematic, and even harder to support different kinds of layout and schematic.

Instead, we create a new "place" object and use it to position the nodes.  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.

  module amp (.a(a0), .c(c0));
    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));
  
    net a (.1(a0), .2(a1));
    net b (.1(b1), .2(b2), .3(b3));
    net c (.1(c0), .2(c2), .3(c3));
  
    place #(.$xposition(24m), .$yposition(7m))  place_b2 (b2);
    place #(.$xposition(0m),  .$yposition(0m))  place_a1 (a1);
    place #(.$xposition(25m), .$yposition(-3m)) place_c3 (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 location of node "b2" is (24,7).  This is the "p" pin of "r2".

The location of node "c3" is (25,-3).  This is the "p" pin of "u1".

Other nodes will follow based on the symbol or footprint geometry.

==== Multiple applications, both layout and schematic ====

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));
    resistor #(.r(1k)) r2 (.p(b2), .n(c2));
    opamp741 #(.gain(100k)) u1 (.p(c3), .n(0), .ps(0), .pn(b3));
  
    net a (.1(a0), .2(a1));
    net b (.1(b1), .2(b2), .3(b3));
    net c (.1(c0), .2(c2), .3(c3));
  
  `ifdef SCHEMATIC
    place #(.$xposition(24m), .$yposition(7m))  place_b2 (b2);
    place #(.$xposition(0m),  .$yposition(0m))  place_a1 (a1);
    place #(.$xposition(25m), .$yposition(-3m)) place_c3 (c3);
  `endif
  `ifdef LAYOUT
    place #(.$xposition(1000u), .$yposition(0u)) place_b2 (b2);
    place #(.$xposition(0m),    .$yposition(0u)) place_a1 (a1);
    place #(.$xposition(2000u), .$yposition(0u)) place_c3 (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.

  `ifdef GSCHEM
    paramset opamp741 symbol
      .file(opamp4.sym);
    paramset resistor symbol
      .file(resistor2.sym);
  `endif
  `ifdef SIMULATION
    module opamp741 ( .....
      .....
    endmodule
  `endif

==== Complex nets can be encapsulated ====

  module net23842 (1,2,3);
    net n23482 (1,2);
    net n84333 (2,3);
    `ifdef SCHEMATIC
      place ...
      place ...
      place ...
    `endif
  endmodule

  module net9393 (1,2);
    net #(.color(blue), .thickness(thin)) n38423 (1,2);
  endmodule

==== Hierarchy ====

The system supports hierarchy.

  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