Design and Compilation Data#

SiliconCompiler uses a data structure object, called Schema, also referred to as “the schema” in subsequent docs, to store all information associated with the compilation process and the design that’s being compiled.

The types of information stored by the schema include, but is not limited to:

How the design is defined (i.e. HW architectural definitions)
How the design is compiled (i.e. Build tools and technology specifics)
How the design is optimized (i.e. Different tool options for build experiments)

This data is stored in Schema parameters, and accessed through Schema methods.

The diagram above shows a few examples of Schema parameters and methods for an overview of how data is stored and accessed.

The following sections provide more detail on how information in the schema is initialized and manipulated.

Schema Configuration#

The schema is “configured,” or defined, based on its parameters.

Major Parameter Categories#

The SiliconCompiler Schema is divided into the following major sub-groups of parameters:

Group	Parameters	Description
`['constraint', ...]`	31	Design constraint settings
`['option', ...]`	63	Compilation options
`['unit', ...]`	11	Global units
`['fpga', ...]`	11	FPGA related settings
`['asic', ...]`	20	ASIC related settings
`['pdk', ...]`	40	PDK related settings
`['tool', ...]`	30	Individual tool settings
`['flowgraph', ...]`	10	Execution flow definition
`['checklist', ...]`	9	Checklist related settings
`['metric', ...]`	43	Metric tracking
`['record', ...]`	18	Compilation history tracking
`['datasheet', ...]`	174	Design interface specifications
`['package', ...]`	23	Packaging manifest
Total	483

Parameter Sub-tree Example#

Some parameters have their own subtrees in order to be fully defined. The table below shows an example of a parameter, called constraint, which specifies the design constraints, from timing-specific parameters to physical design parameters.

parameter	description
`['constraint', 'timing', ...]`	Contains sub-tree of parameters. See Schema.
`['constraint', 'component', ...]`	Contains sub-tree of parameters. See Schema.
`['constraint', 'pin', ...]`	Contains sub-tree of parameters. See Schema.
`['constraint', 'net', ...]`	Contains sub-tree of parameters. See Schema.
`['constraint', 'outline']`	Constraint: Layout outline
`['constraint', 'corearea']`	Constraint: Layout core area
`['constraint', 'coremargin']`	Constraint: Layout core margin
`['constraint', 'density']`	Constraint: Layout density
`['constraint', 'aspectratio']`	Constraint: Layout aspect ratio

Accessing Schema Parameters#

While all the design and compilation information are stored in the Schema object, this information is manipulated through a separate data structured called Chip.

The Chip Object#

This separate data structure is different from the Schema since it instantiates the Schema object and is used to define methods that manipulate the compilation process.

class siliconcompiler.Chip(design, loglevel=None)[source]

Object for configuring and executing hardware design flows.

This is the main object used for configuration, data, and execution within the SiliconCompiler platform.

Parameters:: design (string) – Name of the top level chip design module.

Examples

>>> siliconcompiler.Chip(design="top")
Creates a chip object with name "top".

Chip Creation and Schema Parameter Access#

The following example shows how to create a chip object and manipulate the input schema parameter in Python by setting the parameter with the Chip.set() method, accessing it with the Chip.get() method, and appending to the parameter field with the Chip.add() method.

>>> import siliconcompiler
>>> chip = siliconcompiler.Chip('fulladder')

>>> chip.set('input', 'rtl', 'verilog', 'fulladder.v')
>>> print(chip.get('input', 'rtl', 'verilog'))
['fulladder.v']

>>> chip.add('input', 'rtl', 'verilog', 'halfadder.v')

>>> print(chip.get('input', 'rtl', 'verilog'))
['fulladder.v', 'halfadder.v']

The Chip object provides many useful helper functions. For example, in the quickstart guide , the Chip.input() helper function was used to set the chip timing constraints file, a simpler call than using Chip.set().

>>> chip.input('fulladder.sdc')
| INFO    | fulladder.sdc inferred as constraint/sdc

>>> print(chip.get('input', 'constraint', 'sdc'))
['fulladder.sdc']

Chip.getkeys() is another example of a useful function, provided by the chip object, for checking your parameters.

>>> chip.getkeys('input')
['rtl', 'constraint']

>>> chip.getkeys('input', 'rtl')
['verilog']

>>> chip.getkeys('input', 'constraint')
['sdc']

You can see from the example above that using the Chip.getkeys() function, you’re able to query the subtree of the parameter called input, where the parameter tree can be visually represented as:

└── input
   ├── constraint
   │   └── sdc
   └── rtl
       └── verilog

If you further go one step further down, you’ll see that verilog is a leaf parameter, so the Chip.getkeys() function returns its parameter fields.

>>> chip.getkeys('input', 'rtl', 'verilog')
['type', 'scope', 'require', 'lock', 'switch', 'shorthelp', 'example', 'help', 'notes', 'pernode', 'node', 'hashalgo', 'copy']

Parameter fields are standardized variables which help to define the parameter. In the case below, you can see that Chip.get() can also be used to query parameter fields to provide more information about the parameters:

>>> chip.get('input', 'rtl', 'verilog', field='type')
'[file]'

>>> chip.get('input', 'rtl', 'verilog', field='example')
["cli: -input 'rtl verilog hello_world.v'", "api: chip.set(input, 'rtl','verilog','hello_world.v')"]

getkeys() is just one useful helpfer function; see Core API for more information on methods which can be used to manipulate Schema parameters.

Manifest#

The Schema is recorded to a manifest. This file serves not only as a reference of all the design and compilation parameters, it also provides a mechanism to reload a design.

If you ran the ASIC Demo, you should have a manifest written out to

build/<design>/job0/<design>.pkg.json

The Chip.read_manifest() and Chip.write_manifest() Python API methods handle reading and writing the Schema to/from disk. Besides JSON, other supported export file formats include TCL, and YAML. By default, only non-empty values are written to disk.

import siliconcompiler
chip = siliconcompiler.Chip('hello_world')
chip.write_manifest('hello_world.json')

The Chip.write_manifest() method above writes out the JSON file below, showing the standardized key/value pairs (“fields”) associated with the design parameter.

"design": {
    "lock": false,
    "node": {
        "default": {
           "default": {
                "signature": null,
                "value": null
           }
        },
        "global": {
            "global": {
                "signature": null,
                "value": "hello_world"
            }
        }
    },
    "notes": null,
    "pernode": "never",
    "require": "all",
    "scope": "global",
    "shorthelp": "Design top module name",
    "switch": [
        "-design <str>"
    ],
    "type": "str"
},

Additional Schema Information#

Refer to the Schema and Python API sections of the reference manual for more information. Another good resource is the schema configuration file Schema source code.