netlist_carpentry.io.read.read_utils

Module for simple access of read methods to transform circuits from a text file into Python objects.

Functions:

• read_json –

  Reads a JSON file and converts it to a Circuit object using the YosysNetlistReader.

• read_via_cfg –

  Reads a Verilog file and converts it to a Circuit object based on the given config.

• read –

  Reads a Verilog file and converts it to a Circuit object.

• generate_json_netlist –

  Generate a JSON netlist from the given input file using Yosys.

read_json

read_json(
    json_path: Union[str, Path], circuit_name: Optional[str] = None
) -> Circuit

Reads a JSON file and converts it to a Circuit object using the YosysNetlistReader.

Parameters:

• json_path

  (Union[str, Path]) –

  The path to the JSON file.

• circuit_name

  (Optional[str], default: None ) –

  The name of the circuit to be created. Defaults to None, in which case the default name will be used.

Returns:

• Circuit ( Circuit ) –

  A Circuit object representing the circuit defined in the JSON file.

read_via_cfg

read_via_cfg(
    cfg: ReadConfig, circuit_name: Optional[str] = None, verbose: bool = False
) -> Circuit

Reads a Verilog file and converts it to a Circuit object based on the given config.

The config is used to create the Yosys script that generates the JSON netlist, which is then read by the read_json method, which produces a circuit object based on the content of the netlist.

Parameters:

• cfg

  (ReadConfig) –

  The Yosys config which contains the properties and passes that will be used when creating the JSON netlist.

• circuit_name

  (Optional[str], default: None ) –

  The chosen name for this circuit. Defaults to None, in which case the circuit receives a generic name.

• verbose

  (bool, default: False ) –

  Whether to show Yosys output. If True, all Yosys output is shown. Defaults to False.

Raises:

• YosysError –

  Whenever Yosys fails to generate a JSON netlist. Also shows what exactly went wrong.

Returns:

• Circuit ( Circuit ) –

  The circuit object represented in the JSON netlist that was generated via the given Yosys config.

read

read(
    cfg_or_files: Union[ReadConfig, str, Path, List[Union[str, Path]]],
    top: Optional[str] = None,
    circuit_name: Optional[str] = None,
    verbose: bool = False,
    *,
    out: Union[str, Path, None] = None,
    source_paths: Optional[List[str]] = None,
    no_hierarchy: bool = False
) -> Circuit

Reads a Verilog file and converts it to a Circuit object.

Under the hood, the Verilog file is first converted to a JSON file using Yosys, for which the config is built using read_via_cfg for the given parameters. The config is then used to create and run Yosys to create a JSON netlist, which is then read by the read_json function. The Circuit represented by the provided Verilog file is returned as a result.

Parameters:

• cfg_or_files

  (Union[ReadConfig, str, Path, List[Union[str, Path]]]) –

  The ReadConfig object containing data and settings required to read the circuit. Alternatively, a path to an RTL file (or a list of paths) can be provided, from which the circuit will then be built.

• top

  (str, default: None ) –

  The name of the top-level module in the Verilog file. If not provided, no top module is set, which means that the circuit will not have a specified hierarchy until set manually via Circuit.set_top().

• circuit_name

  (str, default: None ) –

  The name of the circuit to be created. If not provided, the default name will be used.

• verbose

  (bool, default: False ) –

  Whether to show output from the Yosys tool. Defaults to False.

• out

  (Union[str, Path], default: None ) –

  A path to a directory, where the generated JSON file will be located. Defaults to '', in which case the generated JSON netlist is saved in a temporary directory.

• source_paths

  (Optional[List[str]], default: None ) –

  A list of paths to files to source before running Yosys. Can be used to enable plugins or activate environments, e.g. the OSS CAD SUITE. Defaults to None, in which case no additional files are sourced.

• no_hierarchy

  (bool, default: False ) –

  Whether to resolve the hierarchy of the given circuit or not. If True, the yosys "hierarchy" path is skipped. Defaults to False.

Returns:

• Circuit ( Circuit ) –

  A Circuit object representing the circuit defined in the Verilog file.

generate_json_netlist

generate_json_netlist(
    input_file_path: Union[str, Path],
    output_file_path: Union[str, Path],
    top_module_name: str = "",
    verbose: bool = False,
    yosys_script_path: Union[str, Path] = "",
    no_hierarchy: bool = False,
) -> CompletedProcess[str]

Generate a JSON netlist from the given input file using Yosys.

Parameters:

• input_file_path

  (Union[str, Path]) –

  Path to the input Verilog file.

• output_file_path

  (Union[str, Path]) –

  Path where the output JSON netlist should be saved.

• top_module_name

  (str, default: '' ) –

  The name of the top module. Defaults to ''.

• verbose

  (bool, default: False ) –

  Whether to print Yosys log to the console. Defaults to False.

• yosys_script_path

  (Union[str, Path], default: '' ) –

  Path to a custom Yosys synthesis script. If empty, an appropriate script is generated with common synthesis settings. Defaults to ''.

• no_hierarchy

  (bool, default: False ) –

  Whether to resolve the hierarchy of the given circuit or not. If True, the yosys "hierarchy" path is skipped. Defaults to False.

Returns:

• CompletedProcess[str] –

  subprocess.CompletedProcess[str]: The return object of the subprocess that executed Yosys.