
Preliminary spicepp documentation, awaiting sgmlification.

Spicepp is a preprocessor for spice netlist and command files.

It is based on EP3, the Extensible Perl Preprocessor.
See "perldoc Text::EP3" for a description of general
processing and text-substitution directives, including:

@define
@replace
@eval
@include
@if/@elsif/@else/@endif
@ifdef
@perl_begin, @perl_end

In addition, spicepp provides these spice-specific directives
for use in command files:

@wfm wavename

Insert a verbatim waveform file.  For compatibility with cazmpp.

@clock +node -node clockname [ period  [ delay ] ]

Generate a piecewise-linear repeating clock waveform.  Clockname is
used to look for a waveform template named <clockname>.<simcase>

The optional Period argument is used to adjust the period of the
generated waveform by adding additional "dead" time in the high and low
parts of the clock waveform.  If no period is specfied, the command-line
default period is used.  The period cannot be decreased below the value
used for generating the clock waveform template.

The optional Delay argument delays the start of the PWL clock without
affecting its period.

@wavebit +node -node {bits} ETFO=fanout+delay,edge,wavename

Generate a piecewise linear waveform for a data bit.  bits is a string
of ascii 0's and 1's.  Wavename is used to look for a waveform
template named <wavename>.<simcase>. Edge can be r, f, or b to specify
the edge of the default clock on which the signal changes.

example: @wavebit foo GND {0101} ETFO=10+1,r,petff

@trans increment duration

Emits a .tran spice card to run a transient simulation with the specified
timestep and duration.  If duration is of the form <number>clk, the number
is multipled by the clock period specified with the --period option.

-----------------------------------------------------------------------------
The following directives are intended for use in netlist and loads
files to be processed by spicepp:
 
@ladder instance inputnode outputnode rseg cseg nsegs

Emits nsegs each resistor and capacitor elements to consruct an RC
ladder network.  Each resistor and capacitor has value rseg and cseg,
respectively.  The first resistor connects to inputnode, and the last
capactor goes from outputnode to GND.  rseg and seg are strings passed
unchanged into the spice output, so for example they can be HSPICE
expressions enclosed in single quotes.

Complex variations on the "ladder" idea and other repetitive
structures can be constructed using for-loops written within
@perl_begin and @perl_end directives.  Here is an example fragment
copied from a working .loads file that puts equal load capacitance on
all wires of a wide differential bus:

@perl_begin
for($i = 0; $i <= 9; $i++) {
print "c${i}H dc${i}H GND 30f\n";
print "c${i}L dc${i}L GND 30f\n";
}
@perl_end




@xladder in0,in1,... out0,out1,... [com0,com1,...] subckt N [parr=val ... ]

Xladder is a more generalized ladder statement that generates a
sequence of N subcircuit instances.   The subcircuit must have
K input terminals K output terminals, and may have zero or more common
terminals. The subcircuit must be written with its terminals grouped in
order with all inputs first, followed by outputs, followed by any common
terminals.  There are no implicit common terminals; if the subcircuit
needs a GND connection, specify it as a common terminal.

the generated subcircuit instances have their input and output
terminals connected in series, with the common terminals all connected
together:

com0 -------+----------+---------------------------
com1 -----+-|--------+-|---------------------------
          | |        | |
          | |        | |
         -----      -----
  in0----|   |------|   |---- out0 
  in1----|   |------|   |---- out1
         -----      -----






Spicepp accepts these command-line options in addition to the standard 
EP3 ones:

--period period
	Default clock period for @clock.
	The period for @wavebit and @trans; --period must be specified if
	either of these directives are used.
	Causes three macros to be defined for use within the processed
	files: __period__, __period_num__, and __period_suf__

--case case
	The simulation corner case, used to generate filenames for waveform
	templates.  Also causes the __case__ macro to be defined within
	spicepp for use with @ifdef, etc.

--wavedir dir
	Directory in which to look for waveform template files.
	Spicepp looks for templates in the current directory, and then in
	the wavedir directory, if any.




Predefined spicepp macros.

Spicepp macros (@defines) surrounded by two underscores are generated internaly
by spicepp itself.  These include:

   __case__
   __period__
   __period_num__
   __period_suf__

When dospice calls spicepp, it passes a number of --define arguments that set
spicepp macros whose names are usually surrounded by a single underscore.
These may include:

_cmdfile_	The name of the user's command file, in the current directory
_loadsfile_	The name of the user's loads file (if any), in the current directory
vsupply		The main Vdd supply voltage.
_temperature_	The temperature at which to do simulation
_fafile_	The name of the user's transitor netlist file
_fetmodel_	The name of the FET model (or low-voltage-fet model) file
_modeldir_	The directory in which model files are to be found.
		To be used for generating full pathnames names for spice's .include.

The cases file may define these:

_ivdd1_supply_	Optional, the higher I/O-VDD (IVdd) supply voltage
_resmodel_	Optional, the name of the file containing resistor models
_hvmodel_	Optional, the name of the file containing high-voltage transistor models



Additional examples:

Conditionals based on simulation corner case.  

Normally the same loads file is used across all simulation corners,
but when different values or constructs are needed depending on the
simulation case, @if can be used:

@if __case__ eq N
Cfoo foo GND 10f
@elsif __case__ eq B
Cfoo foo GND 5f
@elsif __case__ eq W
Cfoo foo GND 20f
@else
* unknown case
@endif

Note that since cases have alphabetic names, they must be compared in
@if with perl's "eq" string-comparison operator, and not with the ==
numeric-comparison operator.

The __case__ macro is only defined if --case is specified on the
spicepp command line.  Dospice always calls spicepp with --case, but
independent uses may not.   To prevent errors or undesired behavior, try this:

@ifndef __case__
@replace __case__ N
* Defaulted case to be N
@endif




