gnetlist-legacy/docs/README.switcap

   1 -----------------------------------------------------------------
   2 I.   What is this?
   3 -----------------------------------------------------------------
   4
   5 This archive contains a set of symbols and a netlister backend for the
   6 gEDA to drive SWITCAP simulations.  gEDA is the GNU EDA project and
   7 includes a schematic capture tool and a highly flexible netlister.
   8 The SWITCAP program is a switched capacitor circuit simulator.
   9
  10 -----------------------------------------------------------------
  11 II.  Overview
  12 -----------------------------------------------------------------
  13
  14 The basic steps involved with using gEDA as the frontend for SWITCAP
  15 simulations are:
  16
  17 - configure the gEDA symbol search path
  18 - set the gEDA netlister backend search path
  19 - create schematics of the circuit
  20 - create an analysis file
  21 - extract the netlist
  22 - run the SWITCAP simulation
  23
  24
  25 -----------------------------------------------------------------
  26 III.  Initial Setup
  27 -----------------------------------------------------------------
  28   1)  Set your symbol search path for gschem and gnetlist by adding
  29       the following line to the 'gschemrc' and 'gnetlistrc' files in
  30       your project directory.
  31
  32         (component-library "/path/to/sym/switcap")
  33
  34       If those files do not exist, then create them.  You will need to
  35       replace /path/to/sym/switcap with the directory name where you
  36       have installed the .sym files.
  37
  38   2)  Set the search path for scheme files for gnetlist by adding the
  39       following line to your 'gnetlistrc' file.
  40
  41         (scheme-directory "/path/to/scheme")
  42
  43       You will need to replace /path/to/scheme with the path to where
  44       you have installed the gnet-switcap.scm file.
  45
  46   3)
  47
  48 -----------------------------------------------------------------
  49 IV.  Creating Schematics
  50 -----------------------------------------------------------------
  51
  52 --------------------
  53 A.  Required Symbols
  54 --------------------
  55
  56 This section assumes you are familiar with using gschem to create and
  57 edit schematics.  SWITCAP netlisting is only supported for the
  58 components contained in the SWITCAP symbol library as well as the
  59 ground symbol found in the 'power' library which comes with gEDA.  All
  60 allowed SWITCAP elements except for subcircuits are supported.  You
  61 _must_ include the following elements on your schematic:
  62
  63 - one instance of the switcap-timing symbol.  This symbol will set the
  64   master clock period for your simulations.
  65
  66 - one or more instances of the switcap-clock symbol.  This symbol
  67   defines a clock with a particular phase and period.  The reference
  68   designator of the clock symbol is used by the switches to set what
  69   phase they switch on.
  70
  71 - one or more instances of the switcap-analysis symbol.  This symbol
  72   defines an analysis by specifying a file to include in the SWITCAP
  73   netlist.
  74
  75 --------------------
  76 B.  Optional Symbols
  77 --------------------
  78
  79 You can also optionally add the following SWITCAP special symbols to
  80 your schematic:
  81
  82 - zero or one instance of the switcap-title symbol.  This will add a
  83   TITLE: line to the SWITCAP netlist and will appear in the output
  84   file.
  85
  86 - zero or one instance of the switcap-options symbol.  By editing the
  87   OPTIONS attribute on this symbol you can set the various options
  88   which can be passed to SWITCAP.
  89
  90 --------------------
  91 C.  Net Names
  92 --------------------
  93
  94 When creating schematics to drive SWITCAP, you should name all nets
  95 that you wish to plot.  To avoid possible conflicts with unnamed nets,
  96 you should avoid using purely numerical names for nets because
  97 all unnamed nets will be assigned (somewhat randomly) numbers.
  98 SWITCAP limits the length of node names to 7 characters.
  99
 100 --------------------
 101 D.  Switches
 102 --------------------
 103
 104 When placing switches on your schematic, you will need to define
 105 which clock they are controlled with.  This is done by setting
 106 the clock attribute on the switch to the reference designator
 107 of the clock which should control it.
 108
 109 -----------------------------------------------------------------
 110 V.  Extracting the SWITCAP Netlist
 111 -----------------------------------------------------------------
 112
 113 To extract the SWITCAP netlist, run
 114
 115   gnetlist -g switcap -o test.scn file1.sch [file2.sch ...]
 116
 117 For the example file contained in this archive, you can run:
 118
 119   gnetlist -g switcap -o example.scn ckt.sch clocks.sch analysis.sch
 120
 121 The netlist will be left in example.scn.
 122
 123 -----------------------------------------------------------------
 124 VI.  Running SWITCAP
 125 -----------------------------------------------------------------
 126
 127 I typically use something like:
 128
 129   printf "example.scn\nexample.out" | sw
 130
 131 so I can use command history to rerun SWITCAP without having to
 132 manually type the file names each time.
 133
 134 Refer to the SWITCAP manual for more details.