Syntax reference

This section describes syntax of CharLibs YAML configuration file. All configuration data is passed as key-value pairs in the YAML file. The format of YAML contains two obligatory keywords:

• settings

• cells

An example of the file is following:

settings:
    Settings keywords placed here
cells:
    <first_cell_name>:
        Cell keywords placed here
    <last_cell_name>:
        Cell keywords placed here

The example above defines two cells to be characterized:

• first_cell_name

• last_cell_name

There may be arbitrary number of cells defined under cells keyword. The cell name must match the .subckt name in the SPICE netlist that represents the circuit of this cell.

settings

All keywords under settings are optional. If a keyword is not present, CharLib uses the default value.

Allowed keywords:

cell_defaults, debug, debug_dir, lib_name, logic_thresholds, multithreaded, named_nodes, omit_on_failure, results_dir, simulation, temperature, units

cell_defaults

Default values to use for all cells. See the cells keyword for more information. May contain any key-value pair valid for a cell entry.

Allowed keywords:

debug

Display debug messages, and store simulation SPICE files.

type:

boolean

default:

False

debug_dir

The directory where simulation SPICE files are stored if debug keyword is set to True

type:

string

default:

debug

lib_name

The library name for the liberty file. If the filename is not specified on the command line with the --output option, this is also used as the filename.

type:

string

default:

unnamed_lib

logic_thresholds

Voltage thresholds for tuning edge timing. Values are specified as percentages of VDD. See section 2.3 in the Liberty User Guide, Vol. 1 for more information.

Allowed keywords:

falling, high, low, rising

falling

The percentage of the supply voltage at which a signal is considered falling for timing measurements. See figure 2-1 and sections 2.3.1 & 2.3.3 in the Liberty User Guide, Vol. 1.

type:

float or int

default:

50.0

high

The percentage of the supply voltage at which a signal is considered logic 1 for timing measurements. See figure 2-2 and sections 2.3.8-9 in the Liberty User Guide, Vol. 1.

type:

float or int

default:

80.0

low

The percentage of the supply voltage at which a signal is considered logic 0 for timing measurements. See figure 2-2 and sections 2.3.6-7 in the Liberty User Guide, Vol. 1.

type:

float or int

default:

20.0

rising

The percentage of the supply voltage at which a signal is considered rising for timing measurements. See figure 2-1 and sections 2.3.2 & 2.3.4 in the Liberty User Guide, Vol. 1.

type:

float or int

default:

50.0

multithreaded

Run simulations in parallel, using as many threads as possible. Using the --jobs flag on the command line overrides this value.

type:

boolean

default:

True

named_nodes

Allowed keywords:

nwell, primary_ground, primary_power, pwell

nwell

Library-wide n-type biasing node name & voltage

Allowed keywords:

name, voltage

name

type:

string

default:

VNW

voltage

type:

float or int

default:

3.3

primary_ground

Library-wide primary ground node name & voltage.

Allowed keywords:

name, voltage

name

type:

string

default:

VSS

voltage

type:

float or int

default:

0

primary_power

Library-wide primary power supply node name & voltage.

Allowed keywords:

name, voltage

name

type:

string

default:

VDD

voltage

type:

float or int

default:

3.3

pwell

Library-wide p-type biasing node name & voltage

Allowed keywords:

name, voltage

name

type:

string

default:

VPW

voltage

type:

float or int

default:

0

omit_on_failure

Specifies whether to terminate if a cell fails to characterize (False), or continue with the remaining cells (True).

type:

boolean

default:

False

results_dir

The directory where Charlib exports characterization results. If omitted, CharLib creates a results directory in the current folder.

type:

string

default:

results

simulation

Specifies which simulation backend to use and which procedures to apply for acquiring various types of measurements.

Allowed keywords:

backend, combinational_delay_procedure, input_capacitance_procedure

backend

Which PySpice simulator backend to use. For available options, see https://pyspice.fabrice-salvaire.fr/releases/v1.4/faq.html#how-to-set-the-simulator

default:

ngspice-shared

Allowed values:

• ngspice-shared

• ngspice-subprocess

• xyce-serial

• xyce-parallel

combinational_delay_procedure

The name of a procedure used to measure delays associated with a combinational cell.

type:

string

default:

combinational_worst_case

input_capacitance_procedure

The name of a procedure used to measure the capacitance of each input pin for each cell.

type:

string

default:

ac_sweep

temperature

The temperature to use during spice simulations.

type:

float or int

default:

25

units

Specifies physical units to use for input and output values.

Allowed keywords:

capacitive_load, current, energy, leakage_power, pulling_resistance, time, voltage

capacitive_load

The unit of capacitance

type:

string

pattern:

^((yocto|y)|(zepto|z)|(atto|a)|(femto|f)|(pico|p)|(nano|n)|(micro|u)|(milli|m)|()|(kilo|k)|(mega|M)|(giga|G)|(tera|T)|(peta|P)(exa|E)|(zetta|Z)|(yotta|Y))(f|F|farads|Farads)

default:

pF

current

The unit of electrical current

type:

string

pattern:

^((yocto|y)|(zepto|z)|(atto|a)|(femto|f)|(pico|p)|(nano|n)|(micro|u)|(milli|m)|()|(kilo|k)|(mega|M)|(giga|G)|(tera|T)|(peta|P)(exa|E)|(zetta|Z)|(yotta|Y))(a|A|amp|amps|Amp|Amps)

default:

uA

energy

The unit of energy

type:

string

pattern:

^((yocto|y)|(zepto|z)|(atto|a)|(femto|f)|(pico|p)|(nano|n)|(micro|u)|(milli|m)|()|(kilo|k)|(mega|M)|(giga|G)|(tera|T)|(peta|P)(exa|E)|(zetta|Z)|(yotta|Y))(j|J|joules|Joules)

default:

fJ

leakage_power

The unit of power

type:

string

pattern:

^((yocto|y)|(zepto|z)|(atto|a)|(femto|f)|(pico|p)|(nano|n)|(micro|u)|(milli|m)|()|(kilo|k)|(mega|M)|(giga|G)|(tera|T)|(peta|P)(exa|E)|(zetta|Z)|(yotta|Y))(w|W|watts|Watts)

default:

nW

pulling_resistance

The unit of resistance

type:

string

pattern:

^((yocto|y)|(zepto|z)|(atto|a)|(femto|f)|(pico|p)|(nano|n)|(micro|u)|(milli|m)|()|(kilo|k)|(mega|M)|(giga|G)|(tera|T)|(peta|P)(exa|E)|(zetta|Z)|(yotta|Y))(Ω|ohm|ohms|Ohm|Ohms)

default:

Ohm

time

The unit of time.

type:

string

pattern:

^((yocto|y)|(zepto|z)|(atto|a)|(femto|f)|(pico|p)|(nano|n)|(micro|u)|(milli|m)|()|(kilo|k)|(mega|M)|(giga|G)|(tera|T)|(peta|P)(exa|E)|(zetta|Z)|(yotta|Y))(s|seconds|Seconds)

default:

ns

voltage

The unit of electrical voltage.

type:

string

pattern:

^((yocto|y)|(zepto|z)|(atto|a)|(femto|f)|(pico|p)|(nano|n)|(micro|u)|(milli|m)|()|(kilo|k)|(mega|M)|(giga|G)|(tera|T)|(peta|P)(exa|E)|(zetta|Z)|(yotta|Y))(v|V|volts|Volts)

default:

V

cell

Keys under a cell entry may be omitted by instead specifying them in under settings.cell_defaults. CharLib automatically merges any key-value pairs from settings.cell_defaults into each cell entry prior to characterization. If any key appears under both settings.cell_defaults and under a cell entry, the value in the cell entry overrides the default.

Required keywords:

netlist, models, functions, data_slews, loads

Allowed keywords:

area, clock, clock_slews, data_slews, enable, functions, hold_time_range, inputs, loads, models, netlist, outputs, pairs, plots, reset, set, setup_time_range, state

area

The physical core area occupied by the cell layout. Often given in square microns or gate equivalents. See Section 5.1.2 of the Liberty User Guide, Vol. 1 for details and examples.

type:

float or int

default:

0.0

clock

The clock pin name and trigger type, in the format <trigger> <name>. For edge-sensitive devices, trigger should be posedge or negedge. For level-sensitive devices, trigger may be not or omitted altogether. (For example: posedge CLK or negedge CKB)

type:

string

pattern:

^(posedge|negedge)[ ]*[a-zA-Z0-9_]+

clock_slews

A list of clock slew rates to characterize. The cell must have a clock pin in order to use this parameter. Unit is specified by settings.units.time.

type:

array

Every element of clock_slews is:

type:

float or int

data_slews

A list of input pin slew rates to characterize. Unit is specified by settings.units.time.

type:

array

Every element of data_slews is:

type:

float or int

enable

The enable pin name and trigger type, in the format <trigger> <name>. For edge-sensitive devices, trigger should be posedge or negedge. For level-sensitive devices, trigger may be not or omitted altogether. (For example: not CLK or GE)

type:

string

pattern:

^(not |())[ ]*[a-zA-Z0-9_]+

functions

A list of verilog functions describing each output as logical function of inputs. Input and output names must match ports names in the spice subcircuit.

type:

array

Every element of functions is:

type:

string

hold_time_range

A list containing the upper and lower bound to be used when characterizing hold time.

type:

array

Every element of hold_time_range is:

type:

float or int

inputs

A list of input pin names as they appear in the cell netlist. If present, used to verify function inputs.

type:

array

Every element of inputs is:

type:

string

loads

A list of output capacitive loads to characterize. Unit is specified by settings.units.capacitive_load.

type:

array

Every element of loads is:

type:

float or int

models

A list of paths to the spice models for transistors used in this cell’s netlist. If omitted, CharLib assumes each cell has no dependencies. * Using the syntax path/to/file will result in .include path/to/file in SPICE simulations. * Using the syntax path/to/dir will allow CharLib to search the directory for subcircuits used in a particular cell and include them using .include path/to/dir/file. * Using the syntax path/to/file section will result in .lib path/to/file section in SPICE simulations.

type:

array

Every element of models is:

type:

string

netlist

The path to the spice file containing the netlist for this cell.

type:

string

outputs

A list of output pin names as they appear in the cell netlist. If present, used to verify function outputs.

type:

array

Every element of outputs is:

type:

string

pairs

A list of pairs of pins to treat as differential pairs. Pairs must be listed in the format <noninverting_pin> <inverting_pin>.

type:

array

Every element of pairs is:

type:

string

plots

A string (or list of strings) specifying which plot(s) to show for this cell.

May satisfy any of the following definitions:

0

const:

all

1

const:

none

2

const:

io

3

const:

delay

4

type:

array

Every element of 4 is:

type:

string

reset

The name and trigger type of the cell’s reset pin, in the format {TRIGGER_FORMAT} (for example: negedge RN defines an active-low asynchronous reset pin).

type:

string

pattern:

^(posedge|negedge|not|!|())[ ]*[a-zA-Z0-9_]+

set

The name and trigger type of the cell’s set pin, in the format <trigger> <name>. For edge-sensitive devices, trigger should be posedge or negedge. For level-sensitive devices, trigger may be not or omitted altogether. (for example: not SN defines an active-low synchronous set pin).

type:

string

pattern:

^(posedge|negedge|not|!|())[ ]*[a-zA-Z0-9_]+

setup_time_range

A list containing the upper and lower bound to be used when characterizing setup time.

type:

array

Every element of setup_time_range is:

type:

float or int

state

A list of feedback paths which encode state in a sequential cell. Paths should be specified as <internal node> = <output pin>.

type:

array

Every element of state is:

type:

string