docs/wiki/geda-ssan.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="geda_gaf_switcap_symbols_and_netlister">gEDA/gaf Switcap Symbols and Netlister</h1>
  14 <div class="level1">
  15
  16 <p>
  17 by: Dan McMahill
  18 </p>
  19
  20 <p>
  21 This document is released under <a href="http://www.gnu.org/copyleft/fdl.html" class="urlextern" title="http://www.gnu.org/copyleft/fdl.html" rel="nofollow">GFDL</a>
  22 </p>
  23
  24 <p>
  25 April 13th, 2003
  26 </p>
  27
  28 </div>
  29 <!-- EDIT1 SECTION "gEDA/gaf Switcap Symbols and Netlister" [1-168] -->
  30 <h2 class="sectionedit2" id="overview">Overview</h2>
  31 <div class="level2">
  32
  33 <p>
  34 This document describes the symbol library and gnetlist backend which supports driving SWITCAP simulations from the gEDA/gaf system. SWITCAP is a switched capacitor circuit simulator available from Columbia University. It is used in many classroom and research environments. One drawback to SWITCAP is the lack of a freely available schematic capture frontend. The gEDA/gaf SWITCAP symbol library and gnetlist backend tries to fill that gap.<br/>
  35
  36 The basic steps involved with using gEDA as the frontend for SWITCAP simulations are:
  37 </p>
  38 <ol>
  39 <li class="level1"><div class="li"> Create schematics of the circuit.</div>
  40 </li>
  41 <li class="level1"><div class="li"> Create an analysis file.</div>
  42 </li>
  43 <li class="level1"><div class="li"> Extract the netlist.</div>
  44 </li>
  45 <li class="level1"><div class="li"> Run the SWITCAP simulation.</div>
  46 </li>
  47 <li class="level1"><div class="li"> Run <strong>sw2asc</strong> to extract the results.</div>
  48 </li>
  49 <li class="level1"><div class="li"> View the results with <strong>gwave</strong>.</div>
  50 </li>
  51 </ol>
  52
  53 </div>
  54 <!-- EDIT2 SECTION "Overview" [169-924] -->
  55 <h2 class="sectionedit3" id="requirements">Requirements</h2>
  56 <div class="level2">
  57
  58 <p>
  59 You will need the following programs to be installed:
  60 </p>
  61 <ol>
  62 <li class="level1"><div class="li"> A recent version of gEDA/gaf. To see if your version is recent enough, see if the directory <strong><code>$prefix/share/gEDA/sym/switcap</code></strong> exists. <strong><code>$prefix</code></strong> is the installation prefix for gEDA on your system.</div>
  63 </li>
  64 <li class="level1"><div class="li"> SWITCAP. The executable is usually called <strong><code>sw</code></strong>. If you do not have SWITCAP available on your system, you will need to contact Columbia University to obtain a copy. The gEDA/gaf SWITCAP support was tested with SWITCAP Version A.5R Release 21-Sep-87.</div>
  65 </li>
  66 <li class="level1 node"><div class="li"> Although it is optional, you may wish to install a tool which can be used for plotting the output data. SWITCAP produces both <abbr title="American Standard Code for Information Interchange">ASCII</abbr> data listings as well as ugly <abbr title="American Standard Code for Information Interchange">ASCII</abbr> plots (note the release date of the version of SWITCAP used). Suitable tools are:</div>
  67 <ol>
  68 <li class="level2"><div class="li"> Gwave. Gwave is an analog waveform viewer. It is fairly basic, but easy to use, includes cursors, and has zoom/pan features. See <strong><a href="http://www.geda-project.org" class="urlextern" title="http://www.geda-project.org" rel="nofollow">http://www.geda-project.org</a></strong></div>
  69 </li>
  70 <li class="level2"><div class="li"> Scilab. Similar to matlab. Powerful, but no cursors or panning. See <strong><a href="http://www-rocq.inria.fr/scilab" class="urlextern" title="http://www-rocq.inria.fr/scilab" rel="nofollow">http://www-rocq.inria.fr/scilab</a></strong></div>
  71 </li>
  72 <li class="level2"><div class="li"> Octave. Similar to matlab. See <strong><a href="http://www.octave.org" class="urlextern" title="http://www.octave.org" rel="nofollow">http://www.octave.org</a></strong></div>
  73 </li>
  74 <li class="level2"><div class="li"> Grace. See <strong><a href="http://plasma-gate.weizmann.ac.il/Grace/" class="urlextern" title="http://plasma-gate.weizmann.ac.il/Grace/" rel="nofollow">http://plasma-gate.weizmann.ac.il/Grace/</a></strong></div>
  75 </li>
  76 </ol>
  77 </li>
  78 </ol>
  79
  80 </div>
  81 <!-- EDIT3 SECTION "Requirements" [925-2130] -->
  82 <h2 class="sectionedit4" id="creating_schematics">Creating Schematics</h2>
  83 <div class="level2">
  84
  85 </div>
  86 <!-- EDIT4 SECTION "Creating Schematics" [2131-2162] -->
  87 <h3 class="sectionedit5" id="required_symbols">Required Symbols</h3>
  88 <div class="level3">
  89
  90 <p>
  91 This section assumes you are familiar with using gschem to create and edit schematics. SWITCAP netlisting is only supported for the components contained in the SWITCAP symbol library as well as the ground symbol found in the &#039;power&#039; library which comes with gEDA. All allowed SWITCAP elements except for subcircuits are supported. You <em>must</em> include the following elements
  92 on your schematic:
  93 </p>
  94 <ol>
  95 <li class="level1"><div class="li"> One instance of the switcap-timing symbol. This symbol will set the master clock period for your simulations.</div>
  96 </li>
  97 <li class="level1"><div class="li"> One or more instances of the switcap-clock symbol. This symbol defines a clock with a particular phase and period. The reference designator of the clock symbol is used by the switches to set what phase they switch on.</div>
  98 </li>
  99 <li class="level1"><div class="li"> One or more instances of the switcap-analysis symbol. This symbol defines an analysis by specifying a file to include in the SWITCAP netlist. By including multiple instances of this symbol, multiple analysis files may be included.</div>
 100 </li>
 101 </ol>
 102
 103 </div>
 104 <!-- EDIT5 SECTION "Required Symbols" [2163-3155] -->
 105 <h3 class="sectionedit6" id="optional_symbols">Optional Symbols</h3>
 106 <div class="level3">
 107
 108 <p>
 109 You can also optionally add the following SWITCAP special symbols to your schematic:
 110 </p>
 111 <ol>
 112 <li class="level1"><div class="li"> Zero or one instance of the switcap-title symbol. This will add a TITLE: line to the SWITCAP netlist and will appear in the output file.</div>
 113 </li>
 114 <li class="level1"><div class="li"> Zero or one instance of the switcap-options symbol. By editing the OPTIONS attribute on this symbol you can set the various options which can be passed to SWITCAP.</div>
 115 </li>
 116 </ol>
 117
 118 </div>
 119 <!-- EDIT6 SECTION "Optional Symbols" [3156-3577] -->
 120 <h3 class="sectionedit7" id="net_names">Net Names</h3>
 121 <div class="level3">
 122
 123 <p>
 124 When creating schematics to drive SWITCAP, you should name all nets that you wish to plot. To avoid possible conflicts with unnamed nets, you should avoid using purely numerical names for nets because all unnamed nets will be assigned (somewhat randomly) numbers without checking for possible conflicts with explicitly named nets. SWITCAP limits the length of node names to 7 characters.
 125 </p>
 126
 127 </div>
 128 <!-- EDIT7 SECTION "Net Names" [3578-3986] -->
 129 <h3 class="sectionedit8" id="switches">Switches</h3>
 130 <div class="level3">
 131
 132 <p>
 133 When placing switches on your schematic, you will need to define which clock they are controlled with. This is done by setting the clock attribute on the switch to the reference designator of the clock which should control it.
 134 </p>
 135
 136 </div>
 137 <!-- EDIT8 SECTION "Switches" [3987-4233] -->
 138 <h2 class="sectionedit9" id="extracting_the_switcap_netlist">Extracting the SWITCAP Netlist</h2>
 139 <div class="level2">
 140
 141 <p>
 142 To extract the SWITCAP netlist, run:
 143 </p>
 144 <pre class="code">gnetlist -g switcap -o test.scn file1.sch [file2.sch ...]</pre>
 145
 146 <p>
 147 For the example file contained in this archive, you can run:
 148 </p>
 149 <pre class="code">gnetlist -g switcap -o example.scn ckt.sch clocks.sch analysis.sch</pre>
 150
 151 <p>
 152 The netlist will be left in <strong>example.scn</strong>.
 153 </p>
 154
 155 </div>
 156 <!-- EDIT9 SECTION "Extracting the SWITCAP Netlist" [4234-4573] -->
 157 <h2 class="sectionedit10" id="running_switcap">Running SWITCAP</h2>
 158 <div class="level2">
 159
 160 <p>
 161 I typically use something like:
 162 </p>
 163 <pre class="code">printf &quot;example.scn\nexample.out\n&quot; | sw</pre>
 164
 165 <p>
 166 so I can use command history to rerun SWITCAP without having to manually type the file names each time.<br/>
 167
 168 Refer to the SWITCAP manual for more details.
 169 </p>
 170
 171 </div>
 172 <!-- EDIT10 SECTION "Running SWITCAP" [4574-4841] -->
 173 <h2 class="sectionedit11" id="appendix_a_--_symbols_in_the_library">Appendix A -- Symbols in the Library</h2>
 174 <div class="level2">
 175
 176 </div>
 177 <!-- EDIT11 SECTION "Appendix A -- Symbols in the Library" [4842-4890] -->
 178 <h3 class="sectionedit12" id="capacitors_switcap-capacitor">Capacitors (switcap-capacitor)</h3>
 179 <div class="level3">
 180
 181 <p>
 182 Ideal capacitor. Attributes:
 183 </p>
 184 <ul>
 185 <li class="level1"><div class="li"> <strong>C</strong>=capacitance. Required. Specifies filename to be included.</div>
 186 </li>
 187 <li class="level1"><div class="li"> <strong>refdes</strong>=reference designator. Required. Must start with “C” and be unique.</div>
 188 </li>
 189 </ul>
 190
 191 </div>
 192 <!-- EDIT12 SECTION "Capacitors (switcap-capacitor)" [4891-5111] -->
 193 <h3 class="sectionedit13" id="switches_switcap-switch">Switches (switcap-switch)</h3>
 194 <div class="level3">
 195
 196 <p>
 197 Ideal switch. Attributes:
 198 </p>
 199 <ul>
 200 <li class="level1"><div class="li"> <strong>clock</strong>=Controlling clock. Required. Specifies which clock controls this switch.</div>
 201 </li>
 202 <li class="level1"><div class="li"> <strong>refdes</strong>=reference designator. Required. Must start with “S” and be unique.</div>
 203 </li>
 204 </ul>
 205
 206 </div>
 207 <!-- EDIT13 SECTION "Switches (switcap-switch)" [5112-5343] -->
 208 <h3 class="sectionedit14" id="independent_voltage_sources_switcap-vsrc">Independent Voltage Sources (switcap-vsrc)</h3>
 209 <div class="level3">
 210
 211 <p>
 212 Attributes:
 213 </p>
 214 <ul>
 215 <li class="level1"><div class="li"> <strong>refdes</strong>=reference designator. Required. Must start with “V” and be unique.</div>
 216 </li>
 217 </ul>
 218
 219 </div>
 220 <!-- EDIT14 SECTION "Independent Voltage Sources (switcap-vsrc)" [5344-5491] -->
 221 <h3 class="sectionedit15" id="dependent_voltage_sources_switcap-vcvs">Dependent Voltage Sources (switcap-vcvs)</h3>
 222 <div class="level3">
 223
 224 <p>
 225 Attributes:
 226 </p>
 227 <ul>
 228 <li class="level1"><div class="li"> <strong>gain</strong>=gain. Required. Specifies the gain of the controlled source.</div>
 229 </li>
 230 <li class="level1"><div class="li"> <strong>refdes</strong>=reference designator. Required. Must start with “E” and be unique.</div>
 231 </li>
 232 </ul>
 233
 234 </div>
 235 <!-- EDIT15 SECTION "Dependent Voltage Sources (switcap-vcvs)" [5492-5711] -->
 236 <h3 class="sectionedit16" id="clock_specification_switcap-clock">Clock Specification (switcap-clock)</h3>
 237 <div class="level3">
 238
 239 <p>
 240 Attributes:
 241 </p>
 242 <ul>
 243 <li class="level1"><div class="li"> <strong>PSTART</strong>=starting clock phase. Required. Specifies on what phase of the master clock this clock turns on.</div>
 244 </li>
 245 <li class="level1"><div class="li"> <strong>PSTOP</strong>=ending clock phase. Required. Specifies on what phase of the master clock this clock turns off.</div>
 246 </li>
 247 <li class="level1"><div class="li"> <strong>PERIOD</strong>=clock period. Required. Specifies the period of the clock in terms of master clock cycles.</div>
 248 </li>
 249 <li class="level1"><div class="li"> <strong>refdes</strong>=reference designator. Required. The switches that are controlled by this clock will refer to it by the reference designator. As such, avoid running any reference designator renumbering tools.</div>
 250 </li>
 251 </ul>
 252
 253 </div>
 254 <!-- EDIT16 SECTION "Clock Specification (switcap-clock)" [5712-6305] -->
 255 <h3 class="sectionedit17" id="master_timing_specification_switcap-timing">Master Timing Specification (switcap-timing)</h3>
 256 <div class="level3">
 257
 258 <p>
 259 Attributes:
 260 </p>
 261 <ul>
 262 <li class="level1"><div class="li"> PERIOD=clock period. Required. Specifies the period of the master clock in seconds.</div>
 263 </li>
 264 </ul>
 265
 266 <p>
 267 Only a single instance of this symbol is allowed.
 268 </p>
 269
 270 </div>
 271 <!-- EDIT17 SECTION "Master Timing Specification (switcap-timing)" [6306-6512] -->
 272 <h3 class="sectionedit18" id="analysis_file_include_switcap-analysis">Analysis File Include (switcap-analysis)</h3>
 273 <div class="level3">
 274
 275 <p>
 276 This symbol will cause a specified file containing SWITCAP analysis commands to be included in the output netlist. Attributes:
 277 </p>
 278 <ul>
 279 <li class="level1"><div class="li"> <strong>file</strong>=filename. Required. Specifies filename to be included.</div>
 280 </li>
 281 </ul>
 282
 283 </div>
 284 <!-- EDIT18 SECTION "Analysis File Include (switcap-analysis)" [6513-6759] -->
 285 <h3 class="sectionedit19" id="simulation_title_specification_switcap-title">Simulation Title Specification (switcap-title)</h3>
 286 <div class="level3">
 287
 288 <p>
 289 Attributes:
 290 </p>
 291 <ul>
 292 <li class="level1"><div class="li"> <strong>TITLE</strong>=switcap title. Required. Specifies the TITLE line for the SWITCAP netlist.</div>
 293 </li>
 294 </ul>
 295
 296 <p>
 297 Only a single instance of this symbol is allowed.
 298 </p>
 299
 300 </div>
 301 <!-- EDIT19 SECTION "Simulation Title Specification (switcap-title)" [6760-6969] -->
 302 <h3 class="sectionedit20" id="simulation_options_specification_switcap-options">Simulation Options Specification (switcap-options)</h3>
 303 <div class="level3">
 304
 305 <p>
 306 Attributes:
 307 </p>
 308 <ul>
 309 <li class="level1"><div class="li"> <strong>OPTIONS</strong>=switcap options. Required. Specifies the OPTIONS line for the SWITCAP netlist. See the SWITCAP manual for allowed values.</div>
 310 </li>
 311 </ul>
 312
 313 <p>
 314 Only a single instance of this symbol is allowed.
 315 </p>
 316
 317 </div>
 318 <!-- EDIT20 SECTION "Simulation Options Specification (switcap-options)" [6970-7232] -->
 319 <h2 class="sectionedit21" id="example">Example</h2>
 320 <div class="level2">
 321
 322 <p>
 323 This appendix provides a simple example of the entire process of generating a schematic, producing a SWITCAP netlist, running a simulation, and plotting the results.
 324 </p>
 325 <div class="table sectionedit22"><table class="inline">
 326         <tr class="row0">
 327                 <td class="col0"> <a href="media/geda/switcap_figure1.jpg" class="media" target="_blank" title="geda:switcap_figure1.jpg"><img src="media/geda/switcap_figure1.jpg" class="media" alt="" /></a> </td>
 328         </tr>
 329         <tr class="row1">
 330                 <td class="col0"> <a href="media/geda/switcap_figure2.jpg" class="media" target="_blank" title="geda:switcap_figure2.jpg"><img src="media/geda/switcap_figure2.jpg" class="media" alt="" /></a> </td>
 331         </tr>
 332         <tr class="row2">
 333                 <td class="col0"> <a href="media/geda/switcap_figure3.jpg" class="media" target="_blank" title="geda:switcap_figure3.jpg"><img src="media/geda/switcap_figure3.jpg" class="media" alt="" /></a> </td>
 334         </tr>
 335         <tr class="row3">
 336                 <td class="col0"> <a href="media/geda/switcap_figure4.jpg" class="media" target="_blank" title="geda:switcap_figure4.jpg"><img src="media/geda/switcap_figure4.jpg" class="media" alt="" /></a> </td>
 337         </tr>
 338 </table></div>
 339 <!-- EDIT22 TABLE [7420-7555] -->
 340 <p>
 341 Figure 5/6: Simulation Results - Transient MISSING
 342 </p>
 343
 344 </div>
 345 <!-- EDIT21 SECTION "Example" [7233-7608] -->
 346 <h3 class="sectionedit23" id="example_schematics">Example Schematics</h3>
 347 <div class="level3">
 348
 349 <p>
 350 <strong>Figure 1</strong> shows the schematic of a simple switched capacitor circuit. Note that some switches, S1 and S3 for example, are controlled by CLK1 while others, S2 and S4 for example, are controlled by the complement of CLK1 (#CLK1).<br/>
 351
 352 <strong>Figure 2</strong> shows the definition of a clock and the master clock. Here we define a master clock period (mcp) of 1.0 μs in the timing block. In the clock definition symbol, we define a clock called CLK1 that has a period equal to 1 master clock period (mcp). The phase of CLK1 turning on switches is 0 and the phase of CLK1 turning off switches is 3/8 mcp. Additional clock phases can be defined by creating more instances of the clock definition symbol.<br/>
 353
 354 <strong>Figure 3</strong> shows an instantiation of the title block symbol which will cause “my title” to be used in the TITLE line in the SWITCAP netlist. Figure 3 also shows an instantiation of an analysis block which directs the netlister to include the contents of the file test.ana in the output netlist. <strong>Figure 4</strong> shows the contents of the test.ana file.
 355 </p>
 356
 357 </div>
 358 <!-- EDIT23 SECTION "Example Schematics" [7609-8680] -->
 359 <h3 class="sectionedit24" id="netlist_the_design">Netlist the Design</h3>
 360 <div class="level3">
 361
 362 <p>
 363 To netlist the design, run:
 364 </p>
 365 <pre class="code">gnetlist -g switcap -o example.scn ckt.sch clocks.sch analysis.sch</pre>
 366
 367 </div>
 368 <!-- EDIT24 SECTION "Netlist the Design" [8681-8818] -->
 369 <h3 class="sectionedit25" id="run_the_simulation">Run the Simulation</h3>
 370 <div class="level3">
 371
 372 <p>
 373 Run the simulation with:
 374 </p>
 375 <pre class="code">printf &quot;example.scn\nexample.out\n&quot; | sw</pre>
 376
 377 </div>
 378 <!-- EDIT25 SECTION "Run the Simulation" [8819-8927] -->
 379 <h3 class="sectionedit26" id="process_the_results">Process the Results</h3>
 380 <div class="level3">
 381
 382 <p>
 383 Convert the SWITCAP output file to something gwave can read by running:
 384 </p>
 385 <pre class="code">sw2asc example.out</pre>
 386
 387 </div>
 388 <!-- EDIT26 SECTION "Process the Results" [8928-9062] -->
 389 <h3 class="sectionedit27" id="plot_the_results">Plot the Results</h3>
 390 <div class="level3">
 391
 392 <p>
 393 Start up the gwave program and load the first sinusoidal steady state result by running:
 394 </p>
 395 <pre class="code">gwave example.out.SSS.1.asc</pre>
 396
 397 <p>
 398 Drag the two waveforms onto the two waveform panels and change the x-axis to a log scale. Figure 5 shows the output. Start up the gwave program and load the transient result by running:
 399 </p>
 400 <pre class="code">gwave example.out.TRAN.1.asc</pre>
 401
 402 </div>
 403 <!-- EDIT27 SECTION "Plot the Results" [9063-9449] -->
 404 <h2 class="sectionedit28" id="document_revision_history">Document Revision History</h2>
 405 <div class="level2">
 406 <div class="table sectionedit29"><table class="inline">
 407         <tr class="row0">
 408                 <td class="col0"> April 13th, 2003 </td><td class="col1"> Created switcap.tex </td>
 409         </tr>
 410 </table></div>
 411 <!-- EDIT29 TABLE [9488-9530] -->
 412 </div>
 413 <!-- EDIT28 SECTION "Document Revision History" [9450-] --></body>
 414 </html>