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 –

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

• 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: str = '') -> 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

  (str, default: '' ) –

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

Returns:

• Circuit ( Circuit ) –

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

read

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

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

The Verilog file is first converted to a JSON file using Yosys (via the generate_json_netlist function), which is then read by the read_json function. The Circuit represented by the provided Verilog file is returned as a result.

Parameters:

• verilog_paths

  (Union[str, Path]) –

  The path to the Verilog file. Alternatively, a list of paths.

• top

  (str, default: '' ) –

  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: '' ) –

  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: '' ) –

  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[bytes]

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[bytes] –

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