Overview
========

For more info on this example usage of the switcap backend, please
see the section "Switcap backend" in the Lepton EDA reference
manual.

The basic steps involved with using Lepton as the frontend for
SWITCAP simulations are:

- configure the symbol search path
- create schematics of the circuit
- create an analysis file
- extract the netlist
- run the SWITCAP simulation


Initial Setup
=============

Set your symbol search path for Lepton tools by adding the
following line to the 'gafrc' file in your project directory.

  (component-library "/path/to/sym/switcap")

If those files do not exist, then create them.  You will need to
replace /path/to/sym/switcap with the directory name where your
switcap .sym files are installed.

In this example, the 'gafrc' file contains the path to the local
symbol cache directory.


Creating Schematics
===================

Required Symbols
----------------

This section assumes you are familiar with using lepton-schematic
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 'power' library
which comes with Lepton.  All allowed SWITCAP elements except for
subcircuits are supported.  You _must_ include the following
elements on your schematic:

- one instance of the switcap-timing symbol.  This symbol will set
  the master clock period for your simulations.

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

- one or more instances of the switcap-analysis symbol.  This
  symbol defines an analysis by specifying a file to include in
  the SWITCAP netlist.

Optional Symbols
----------------

You can also optionally add the following SWITCAP special symbols
to your schematic:

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

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

Net Names
---------

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.  SWITCAP limits the length of node names to 7 characters.

Switches
--------

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.

Extracting the SWITCAP Netlist
==============================

To extract the SWITCAP netlist, run

  lepton-netlist -g switcap -o test.scn file1.sch [file2.sch ...]

For the example files contained in this directory, you can run:

  lepton-netlist -g switcap -o example.scn ckt.sch clocks.sch analysis.sch

The netlist will be left in example.scn.

Running SWITCAP
===============

You can do something like this:

  printf "example.scn\nexample.out" | sw

so you can use command history to rerun SWITCAP without having to
manually type the file names each time.

Refer to the SWITCAP manual for more details.
