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

Allowed keywords:

cell_defaults, debug, debug_dir, lib_name, logic_thresholds, multithreaded, named_nodes, omit_on_failure, operating_conditions, process, quiet, results_dir, simulator, temperature, units

cell_defaults

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

Allowed keywords:

area, clock, clock_skew, flops, footprint, functions, hold_time_range, inputs, loads, models, netlist, outputs, plots, reset, set, setup_time_range, simulation_timestep, slews

area

The physical area occupied by the cell layout, specified in um^2.

type:

float or int

default:

0

clock

The clock pin name and edge direction. The format is: <edge_direction> <clock_pin_name>, where edge_direction can be one of: posedge or negedge. E.g. posedge CLK or negedge CKB.

type:

string

pattern:

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

clock_skew

The slew rate to use for the clock signal in simulation. For sequential cells only. In units specified by settings.units.time.

type:

float or int

flops

A list of storage element names. These are the names of flip-flops that Charlib puts under ff keyword in the generated liberty file

type:

array

Every element of flops is:

type:

string

footprint

Footprint of the cell as placed into the liberty file.

type:

string

functions

A list of verilog functions describing each output as logical function of inputs. Shall be in the same order as outputs

type:

array

Every element of functions is:

type:

string

hold_time_range

A list of margins 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.

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.

type:

array

Every element of outputs is:

type:

string

plots

A string, or list of strings specifying which plots to show for this cell.

May satisfy any of the following definitions:

0
const:

all

1
const:

none

2
type:

array

Every element of 2 is:

Allowed values:

  • io

  • delay

  • energy

reset

The asynchronous reset pin name, and edge direction. For sequential cells only. If omitted, CharLib assumes the cell does not have a reset pin.The format is <edge_direction> <pin_name>. Where edge_direction can be one of: posedge or negedge. E.g. posedge AR defines active high reset pin.

type:

string

pattern:

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

set

The asynchronous set pin name, and edge direction. For sequential cells only. If omitted, CharLib assumes the cell does not have a set pin.The format is <edge_direction> <pin_name>, where edge_direction can be one of: posedge or negedge. E.g. negedge AS defines active low set pin.

type:

string

pattern:

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

setup_time_range

A list of margins to be used when characterizing setup time.

type:

array

Every element of setup_time_range is:

type:

float or int

simulation_timestep

The simulation timestep. Relative value to settings.units.time.

type:

float or int

slews

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

type:

array

Every element of slews is:

type:

float or int

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 to put to the exported liberty file.

type:

string

default:

unnamed_lib

logic_thresholds

Voltage thresholds to recognize signals as logical 0 or 1. Values are relative to voltage given by named_nodes.vdd

Allowed keywords:

high, high_to_low, low, low_to_high

high

The minimum fraction of supply voltage recognized as a logical 1.

type:

float or int

default:

0.8

high_to_low

The threshold which must be crossed before CharLib considers a signal falling from one to zero.

type:

float or int

default:

0.5

low

The maximum fraction supply voltage recognized as a logical 0.

type:

float or int

default:

0.2

low_to_high

The threshold which must be crossed before Charlib considers a signal rising from zero to one.

type:

float or int

default:

0.5

multithreaded

Run simulations in parallel, using as many threads as possible.

type:

boolean

default:

True

named_nodes

Allowed keywords:

nwell, pwell, vdd, vss

nwell

Devices N-WELL terminal

Allowed keywords:

name, voltage

name
type:

string

default:

VNW

voltage
type:

float or int

default:

3.3

pwell

Devicess P-WELL terminal

Allowed keywords:

name, voltage

name
type:

string

default:

VPW

voltage
type:

float or int

default:

0

vdd

Devices power supply terminal

Allowed keywords:

name, voltage

name
type:

string

default:

VDD

voltage
type:

float or int

default:

3.3

vss

Devices ground terminal

Allowed keywords:

name, voltage

name
type:

string

default:

GND

voltage
type:

float or int

default:

0

omit_on_failure

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

type:

boolean

default:

False

operating_conditions

The operating conditions to set in the exported liberty file.

type:

string

process

The process condition to set in the exported liberty file.

type:

string

default:

typ

quiet

Minimize the number of messages and data Charlib displays to the console.

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

simulator

Specifies which Spice simulator to use

default:

ngspice-shared

Allowed values:

  • ngspice-shared

  • ngspice-subprocess

  • xyce-serial

  • xyce-parallel

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

default:

pF

Allowed values:

  • fF

  • pF

  • nF

  • uF

current

The unit of electrical current

default:

uA

Allowed values:

  • pA

  • nA

  • uA

  • mA

energy

The unit of energy

default:

fJ

Allowed values:

  • aJ

  • fJ

  • nJ

leakage_power

The unit of power

default:

nW

Allowed values:

  • pW

  • nW

  • uW

pulling_resistance

The unit of resistance

default:

Ohm

Allowed values:

  • mOhm

  • Ohm

  • kOhm

time

The unit of time.

default:

ns

Allowed values:

  • fs

  • ps

  • ns

  • us

  • ms

voltage

The unit of electrical voltage.

default:

V

Allowed values:

  • mV

  • V

cell

Any of keys under cells can be omitted from cell entries by instead specifying them in the settings.cell_defaults. CharLib automatically merges any key-value pairs from settings.cell_defaults to each cell entry when characterizing the cell. If a key appears in a cell’s entry, and in cell_defaults, the value in the cell entry overrides the value from cell_defaults.

Allowed keywords:

area, clock, clock_skew, flops, footprint, functions, hold_time_range, inputs, loads, models, netlist, outputs, plots, reset, set, setup_time_range, simulation_timestep, slews

area

The physical area occupied by the cell layout, specified in um^2.

type:

float or int

default:

0

clock

The clock pin name and edge direction. The format is: <edge_direction> <clock_pin_name>, where edge_direction can be one of: posedge or negedge. E.g. posedge CLK or negedge CKB.

type:

string

pattern:

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

clock_skew

The slew rate to use for the clock signal in simulation. For sequential cells only. In units specified by settings.units.time.

type:

float or int

flops

A list of storage element names. These are the names of flip-flops that Charlib puts under ff keyword in the generated liberty file

type:

array

Every element of flops is:

type:

string

footprint

Footprint of the cell as placed into the liberty file.

type:

string

functions

A list of verilog functions describing each output as logical function of inputs. Shall be in the same order as outputs

type:

array

Every element of functions is:

type:

string

hold_time_range

A list of margins 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.

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.

type:

array

Every element of outputs is:

type:

string

plots

A string, or list of strings specifying which plots to show for this cell.

May satisfy any of the following definitions:

0

const:

all

1

const:

none

2

type:

array

Every element of 2 is:

Allowed values:

  • io

  • delay

  • energy

reset

The asynchronous reset pin name, and edge direction. For sequential cells only. If omitted, CharLib assumes the cell does not have a reset pin.The format is <edge_direction> <pin_name>. Where edge_direction can be one of: posedge or negedge. E.g. posedge AR defines active high reset pin.

type:

string

pattern:

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

set

The asynchronous set pin name, and edge direction. For sequential cells only. If omitted, CharLib assumes the cell does not have a set pin.The format is <edge_direction> <pin_name>, where edge_direction can be one of: posedge or negedge. E.g. negedge AS defines active low set pin.

type:

string

pattern:

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

setup_time_range

A list of margins to be used when characterizing setup time.

type:

array

Every element of setup_time_range is:

type:

float or int

simulation_timestep

The simulation timestep. Relative value to settings.units.time.

type:

float or int

slews

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

type:

array

Every element of slews is:

type:

float or int