Differences

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

--- geda:gnetlist_ug [2012/02/22 18:42]
kokr [Introduction] gpleda -> geda-project
+++ geda:gnetlist_ug [2012/11/23 04:08] (current)
vzh Added a link to the Russian translation
@@ Line 1: / Line 1: @@
-====== gEDA gnetlist Users Guide ======
+//Translations of this guide are also available in the following languages:// [[gnetlist_ug.ru|Русский]]
-by: Ales Hvezda
+====== gEDA gnetlist User Guide ======
+<note>The text of and illustrations in this document are licensed under a //Creative Commons Attribution–Share Alike 3.0 Unported// license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/ . The original authors of this document designate the gEDA Project as the "Attribution Party" for purposes of CC-BY-SA. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.</note>
+===== Contents =====
-This document is released under [[http://www.gnu.org/copyleft/fdl.html|GFDL]]
+  - [[geda:gnetlist_ug:introduction|Introduction]]
+  - [[geda:gnetlist_ug:running_gnetlist|Running gnetlist]]
+  - [[geda:gnetlist_ug:input_output_files|Input & output files]]
+  - [[geda:gnetlist_ug:netlist_backends|Netlist backends]]
+  - [[geda:gnetlist_ug:basic_netlisting|Basic netlisting]]
+  - [[geda:gnetlist_ug:hierarchy|Hierarchy]]
+  - [[geda:gnetlist_ug:slotting|Slots and slotting]]
+  - [[geda:gnetlist_ug:implicit_pins|Implicit pins]]
+  - [[geda:gnetlist_ug:config|Configuring gnetlist]]
+  - Appendix: [[geda:gnetlist_ug:command_line|Command-line arguments]]
-September 21st, 2003
-===== Introduction =====
-This document describes how to use **gnetlist**. This document and **gnetlist** in general are pretty ALPHA, so keep that in mind as you use it to generate netlists. As all engineers know, it is very important that you do not blindly trust tools, assuming that they will always create correct output. **gnetlist** is certainly no exception to this rule. It is very important that you verify *every* netlists you create. As with most programs (including all the programs in gEDA), **gnetlist** comes with NO WARRANTY. Blah, I hate having to say that, but I'm hoping that this warning will keep the user from assuming that **gnetlist** generates perfect netlists. Though if you find a bug, please let **ahvezda@geda.seul.org** know.\\
-This document is very rough, so please e-mail all corrections to **ahvezda@geda.seul.org** or file a bug report on the gEDA homepage at http://www.geda-project.org. Thanks!
-===== Overview =====
-**gnetlist** is the gEDA netlister. It takes as input schematic files and produces a netlist. A netlist is a textual representation of a schematic. This textual representation has all of the connections between devices completely resolved. This means that all the connections associated with a net are grouped together. The netlister also handles hierarchies of schematics.\\
-**gnetlist** has a very flexible architecture. The main program, which is written in C, reads in a schematic (using routines from libgeda) and creates an internal representation of the schematic data. This internal representation is then manipulated by a backend which is responsible for writing the various netlist formats. The backend for each netlist format is written in scheme (specifically Guile). This architecture not only allows for an infinite number of netlist formats, but also allows the netlister to generate other reports (like bill of material lists).\\
-As of 20001006 **gnetlist** has scheme backends to support the following netlist formats:
-  - PCB & PCBboard - UNIX PCB netlist format.
-  - Allegro netlist format
-  - BAE netlist format
-  - BOM & BOM2 - Bill of Material generators
-  - DRC - Start of a design rule checker
-  - gEDA - the native format of gEDA, mainly used for testing
-  - Gossip netlist format
-  - PADS netlist format
-  - ProtelII netlist format
-  - Spice compatible netlist format
-  - Tango netlist format
-  - Verilog code
-  - VHDL code
-  - VIPEC netlist format
-  - VAMS - VHDL-AMS netlist format
-This list is constantly growing. Several lacking features (as of 20001006) are: no support for buses, error detection and reporting is fairly limited, and ... (many more).
-===== Installation =====
-Hopefully by now you have already installed **gnetlist** on your machine. This document does not cover installation. You can verify the installation by running:
-<code>libgeda-config --version
-gesym-config --version
-which gnetlist
-ldd `which gnetlist`</code>
-The first two should return the version of the installed tools (libgeda and the symbol library) and the next command should return the path to the **gnetlist** binary. The final command (only on Unix-like operating systems which include the ldd utility for listing dynamic dependencies of executable files or shared objects) will return which libraries are linked to **gnetlist**; all of the request libraries must be found for **gnetlist** to run. If these commands do not return the expected results, then most likely the gEDA tools are not installed properly. Please see the appropriate INSTALL docs (which came with the distribution) for more info on installing the gEDA tools.
-===== Running gnetlist =====
-It is very easy to run **gnetlist**. **gnetlist** is a pure command line interface so there is no pesky GUI to get in the way :-) For a list of command line arguments please run ''gnetlist -h''.\\
-You need to specify the following two parameters to run **gnetlist**:
-  * **-g guile_procedure** (this specifies which backend to run against the schematics)
-  * **filename.sch** (this specifies the schematic files)
-You can specify multiple schematics on the command line. The default filename for the generated netlist goes into "**output.net**" You can change this default location by using the **-o filename** option.\\
-A few examples on running **gnetlist**:
-<code>gnetlist -g geda -o stack.net stack_1.sch</code>
-(output netlist (in **stack.net**) for **stack_1.sch** using the gEDA native format)
-There are also a few debugging flags. The first one is the **-v** flag which enables verbose mode. Verbose mode outputs a whole bunch of information on what **gnetlist** is doing as well a dump of the internal representation. The **-i** flag which puts **gnetlist** into a interactive mode is very useful in debugging scheme backends and typically is not used by the end user.\\
-For a detailed list of command line arguments please see the **gnetlist** man page.
-===== Schematic / symbol requirements =====
-This section describes what schematics/symbols need to have to be usable with **gnetlist**. In order for **gnetlist** to work correctly, both the schematics and supporting symbols must be correct. Basically these requirements consist of attribute specification. Attributes are used through out the gEDA system to represent information. Attributes are the only way of adding information to components, nets, pins, etc... For more detailed information about the attributes mentioned in this document, please see the [[gEDA:master_attributes_list|Master Attributes List]] document.
-==== Symbol requirements ====
-  * All symbols must have a ''device='' attribute.
-  * All pins must have the ''pin#=#'' attribute. This attribute will eventually change form, but for now it is required as ''pin#=#''.
-  * All pins should also have a ''pinlabel='' attribute.
-  * For symbols which are slotted you also need the ''slot='' attribute, for each slot a ''slot#=#'' attribute, and the ''numslots=#'' attribute. Slotting will also change in the near future, but for now it should be specified as above.
-  * For any power/gnd/arbitrary you need to put ''net='' attributes inside the symbol. See the netattrib.txt document for more info.
-  * You can supply default values for various parameters (this is dependent on which backend you use) by taking advantage of the attribute "promotion" mechanism. See below for more info as well as the gschem documentation.
-  * For symbols which you want the netlister to completely ignore use the ''graphical=1'' attribute.
-  * For more tips on symbols, please see the [[gEDA:scg|Symbol Creation Guide]].
-==== Schematic requirements ====
-  * Most importantly, every component you want to show up in a netlist must have a ''refdes='' attribute. This is **VERY** important. **gnetlist** should warn you if you have a component which doesn't have a ''refdes='', but there have been bugs which do not cause this warning.
-  * You can label all nets using the ''label='' attribute. You only need to attach this label to one net segment (of an electrically connected net) for all the net segments to inherit the label.
-  * You can have multiple schematics in a design (which is actually a confusing term since it means many different things to people). To use multiple schematics to create a single netlist, just specify them on the **gnetlist** command line.
-  * If you name nets the same, then these nets will be electrically connected. Same net names spawn all the specified schematics.
-  * There are quite a few issues that deal with hierarchy please see the hierarchy section below.
-==== Random notes ====
-  * Attributes which are not attached to anything and are inside a symbol are "promoted" to the outside of the symbol when the symbol is placed inside a schematic (in gschem). These promoted attributes are always looked at/for first before going into the symbol. So, in other words, if there is an attribute with the same name is inside a symbol and attached to the outside of the instantiated component, then the outside attribute takes precedence.
-===== Hierarchy Support =====
-TBA
-===== Specific backend info =====
-TBA
-===== Scheme backend API =====
-Please note that this section is still under construction. The information here should be correct, but it is not complete.
-==== Overview ====
-**gnetlist** operates by loading the schematic database from the .sch files, building an internal representation and then calling a function specific to the desired output netlist type which performs the actual netlisting. Each **gnetlist** backend is contained in a file called gnet-<backend>.scm. Where <backend> is the name of the particular backend. For example, gnet-switcap.scm contains the code used by "gnetlist -g switcap" and gnet-drc.scm contains the code used by "gnetlist -g drc". The backends are written in the Scheme programming language. The particular implementation of scheme is guile which stands for GNU's Ubiquitous Intelligent Language for Extensions. More information about guile may be found at [[http://www.gnu.org/software/guile/guile.html]].
-==== Entry Point ====
-Each netlist backend is required to provide a function whose name matches the netlist type. For example, the switcap backend contained in gnet-switcap.scm must provide a function called "switcap". That is the function which **gnetlist** will call to initiate the netlisting. The entry point function is given a single argument which is the filename for the output netlist. Typically the first thing a netlister does is to open the output file for writing.\\
-The following excerpt from the switcap backend shows the start of the entry point function and shows the output file being opened. At the end of the function, the output file is closed.
-<code>;; ---------------------------------------
-;; Switcap netlist generation -- top level
-;; ---------------------------------------
-(define switcap
-  (lambda (output-filename)
-    (let ((port (open-output-file output-filename)))
-;; rest of netlisting goes here
-;; close the output file and return
-      (close-output-port port))))</code>
-==== Initialization of the Backend ====
-After opening the output netlist, any specific initializations which must be done for the particular netlist are done. In the switcap example, we must initialize a net name and reference designator (refdes) aliasing database. This is because switcap has more restrictive requirements on its net names than gschem does. In addition, the reference designators in a switcap netlist have special requirements. To deal with this situation, **gnetlist** provides some general purpose functions which rename nets and reference designators to comply with the target netlist requirements. More details on this later. For now, just note that the switcap backend uses the following code:
-<code>;; initialize the net-name aliasing
-(gnetlist:build-net-aliases switcap:map-net-names
-    all-unique-nets)
-;; initialize the refdes aliasing
-(gnetlist:build-refdes-aliases switcap:map-refdes
-    packages)</code>
-The other initialization which is typically done, although not required by all netlist types, is to output some sort of header. This header may be explicitly contained in the entry point function or it may be contained in its own function for code clarity. In the switcap backend, the call is:
-<code>(switcap:write-top-header port)</code>
-Note that the convention is for any backend specific functions to have their names prefixed by the backend name. For example all switcap specific functions begin with "switcap:". Functions which are available to all backends and provided by **gnetlist** are prefixed by "gnetlist:".\\
-The definition of "switcap:write-top-header" is
-<code>;;
-;; Switcap netlist header
-;;
-(define switcap:write-top-header
-  (lambda (port)
-    (display
-      "/* Switcap netlist produced by gnetlist (part of gEDA) */\n"
-      port)
-    (display
-      "/* See http://www.geda.seul.org for more information. */\n"
-      port)
-    (display
-      "/* Switcap backend written by Dan McMahill            */\n"
-      port)
-    (display "\n\n" port)
-    )
-  )</code>
-The entry point function continues by calling functions for each section in the output netlist. The variable "packages" is predefined by **gnetlist** to be a list of all components in the design and "all-unique-nets" is a list of all the nets in the design. The various functions used by the backend for each section in the netlist will use these variables. For example, the main part of the switcap netlist which contains the components and their connectivity is written to the output file with
-<code>(switcap:write-netlist port packages)</code>
-==== Net Name and Reference Designator Aliasing ====
-It is common for a target netlist type to have a more restrictive requirement for the net names than gschem does. For example, there may be restrictions on length, allowed characters, or case. To address this issue, **gnetlist** provides a net name aliasing feature. To use this feature, the function "gnetlist:build-netaliases" is called as part of the initialization section of the entry point function.\\
-For example in the switcap backend,
-<code>;; initialize the net-name aliasing
-(gnetlist:build-net-aliases switcap:map-net-names
-    all-unique-nets)</code>
-The function "switcap:map-net-names" is a backend specific (switcap in this case) function which accepts a gschem net name as an argument and returns a modified net name which meets the requirements for the output netlist format. In the case of switcap, the requirement is ground must be called "0", nets may have no more than 7 characters, and the netlist is not case sensitive.
-<code>;; This procedure takes a net name as determined by
-;; gnetlist and modifies it to be a valid SWITCAP net name.
-;;
-(define switcap:map-net-names
-  (lambda (net-name)
-    (let ((rx (make-regexp "^unnamed_net"))
-          (net-alias net-name)
-          )
-      ;; XXX we should use a dynamic regexp based on the
-      ;; current value for the unnamed net base string.
-      (cond
-       ;; Change "GND" to "0"
-       ((string=? net-name "GND") (set! net-alias "0"))
-       ;; remove the 'unnamed_net' part
-       ((regexp-exec rx net-name)
-           (set! net-alias (substring net-name 11)))
-       (else net-name)
-       )
-      ;; Truncate to 7 characters
-      (if (> (string-length net-alias) 7)
-          (set! net-alias (substring net-alias 0 7))
-          )
-  ;; Convert to all upper case
-  (string-upcase net-alias)
-  )
- )
-)</code>
-The function "gnetlist:build-net-aliases" creates a database which later on lets you look up the output net name from the gschem net name or the gschem net name from the output net name. In addition it does the very important task of ensuring that no shorts are created by modifying the net names. As an example suppose you had a net called "MyNet" and another called "mynet" in the schematic. Those are unique but after converting both to upper case they become a single net. "gnetlist:build-net-aliases" will detect this condition and issue an error and stop netlisting.\\
-Now that the database has been initialized, the netlister simply uses
-<code>(gnetlist:alias-net somenet)</code>
-to retrive the netlist net name from the gschem net name.\\
-A similar set of functions are provided for reference designator aliasing.
-==== Debugging Hints ====
-A useful debugging tool is to run **gnetlist** in interactive mode. This is done by using the "-i" option to **gnetlist**. This will give you a shell where you may enter scheme commands. This provides a simple way to examine various variables and try out various functions.\\
-An example of running **gnetlist** in interactive mode is shown below.
-<code>% gnetlist -i ../../gnetlist/examples/switcap/*.sch
-gEDA/gnetlist version 20041228
-gEDA/gnetlist comes with ABSOLUTELY NO WARRANTY; see COPYING for more details.
-This is free software, and you are welcome to redistribute it under certain
-conditions; please see the COPYING file for more details.
-Loading schematic [../../gnetlist/examples/switcap/analysis.sch]
-Loading schematic [../../gnetlist/examples/switcap/ckt.sch]
-Loading schematic [../../gnetlist/examples/switcap/clocks.sch]
-gnetlist> all-unique-nets
-  ("unnamed_net6" "unnamed_net5" "unnamed_net4" "OUT" "unnamed_net3"
-   "unnamed_net2" "unnamed_net1" "GND")
-  gnetlist> packages
-  ("TIMING" "CLK1" "S7" "S8" "S6" "S5" "C3" "S4" "C2" "C1" "E1" "S3"
-   "S1" "V1" "S2" "OPTIONS" "TITLE" "ANA1")
-  gnetlist> (quit)
-  %</code>

gEDA Project Wiki

User Tools

Site Tools

Differences

Page Tools