fabulous_cli

FABulous command-line interface module.

This module provides the main command-line interface for the FABulous FPGA framework. It includes interactive and batch mode support for fabric generation, bitstream creation, simulation, and project management.

Attributes

CMD_FABRIC_FLOW
CMD_GUI
CMD_HELPER
CMD_OTHER
CMD_SCRIPT
CMD_SETUP
CMD_TIMING_MODEL
CMD_TOOLS
CMD_USER_DESIGN_FLOW
INTO_STRING
KLAYOUT_LAYER_FILE_NAMES
META_DATA_DIR

Classes

FABulous_CLI

FABulous command-line interface for FPGA fabric generation and management.

Module Contents

CMD_FABRIC_FLOW = 'Fabric Flow'

CMD_GUI = 'GUI'

CMD_HELPER = 'Helper'

CMD_OTHER = 'Other'

CMD_SCRIPT = 'Script'

CMD_SETUP = 'Setup'

CMD_TIMING_MODEL = 'Timing Characterization'

CMD_TOOLS = 'Tools'

CMD_USER_DESIGN_FLOW = 'User Design Flow'

FABulous_CLI

class FABulous_CLI(writerType, force=False, interactive=False, verbose=False, debug=False, max_job=4)

Bases: Cmd

FABulous command-line interface for FPGA fabric generation and management.

This class provides an interactive and non-interactive command-line interface for the FABulous FPGA framework. It supports fabric generation, bitstream creation, project management, and various utilities for FPGA development workflow.

Parameters:

• writerType (str | None) – The writer type to use for generating fabric.

• force (bool) – If True, force operations without confirmation, by default False

• interactive (bool) – If True, run in interactive CLI mode, by default False

• verbose (bool) – If True, enable verbose logging, by default False

• debug (bool) – If True, enable debug logging, by default False

• max_job (int) – Maximum number of parallel jobs, -1 to use all CPU cores, by default 4

Variables:

• intro (str) – Introduction message displayed when CLI starts

• prompt (str) – Command prompt string displayed to users

• fabulousAPI (FABulous_API) – Instance of the FABulous API for fabric operations

• projectDir (Path) – Current project directory path

• top (str) – Top-level module name for synthesis

• allTile (list[str]) – List of all tile names in the current fabric

• csvFile (Path) – Path to the fabric CSV definition file

• extension (str) – File extension for HDL files (“v” for Verilog, “vhd” for VHDL)

• script (str) – Batch script commands to execute

• force (bool) – If true, force operations without confirmation

• interactive (bool) – If true, run in interactive CLI mode

• max_job (int) – Maximum number of parallel jobs for tile generation

• do_compile_design (Callable) – Method to compile user design through synthesis, PnR, and bitstream generation

• filePathOptionalParser (Cmd2ArgumentParser) – Argument parser for commands with an optional file path argument

• filePathRequireParser (Cmd2ArgumentParser) – Argument parser for commands with a required file path argument

• userDesignRequireParser (Cmd2ArgumentParser) – Argument parser for commands requiring a user design file path

• tile_list_parser (Cmd2ArgumentParser) – Argument parser for commands accepting a list of tile names

• tile_single_parser (Cmd2ArgumentParser) – Argument parser for commands accepting a single tile name

• clone_tile_parser (Cmd2ArgumentParser) – Argument parser for the clone_tile command

• install_oss_cad_suite_parser (Cmd2ArgumentParser) – Argument parser for the install-oss-cad-suite command

• install_FABulator_parser (Cmd2ArgumentParser) – Argument parser for the install-FABulator command

• geometryParser (Cmd2ArgumentParser) – Argument parser for the gen_geometry command

• simulation_parser (Cmd2ArgumentParser) – Argument parser for the run_simulation command

• gen_tile_parser (Cmd2ArgumentParser) – Argument parser for the gen_tile command

• gds_parser (Cmd2ArgumentParser) – Argument parser for the run_gds command

• io_pin_config_parser (Cmd2ArgumentParser) – Argument parser for the gen_io_pin_config command

• gen_all_tile_parser (Cmd2ArgumentParser) – Argument parser for the gen_all_tile command

• gui_parser (Cmd2ArgumentParser) – Argument parser for the open_gui command

• timing_model_parser (Cmd2ArgumentParser) – Argument parser for the timing_model command

Notes

This CLI extends the cmd.Cmd class to provide command completion, help system, and command history. It supports both interactive mode and batch script execution.

Easy but powerful framework for writing line-oriented command interpreters, extends Python’s cmd package.

Parameters:

• completekey – readline name of a completion key, default to Tab

• stdin – alternate input file object, if not specified, sys.stdin is used

• stdout – alternate output file object, if not specified, sys.stdout is used

• persistent_history_file – file path to load a persistent cmd2 command history from

• persistent_history_length – max number of history items to write to the persistent history file

• startup_script – file path to a script to execute at startup

• silence_startup_script – if True, then the startup script’s output will be suppressed. Anything written to stderr will still display.

• include_py – should the “py” command be included for an embedded Python shell

• include_ipy – should the “ipy” command be included for an embedded IPython shell

• allow_cli_args – if True, then [cmd2.Cmd.__init__][] will process command line arguments as either commands to be run or, if -t or --test are given, transcript files to run. This should be set to False if your application parses its own command line arguments.

• transcript_files – pass a list of transcript files to be run on initialization. This allows running transcript tests when allow_cli_args is False. If allow_cli_args is True this parameter is ignored.

• allow_redirection – If False, prevent output redirection and piping to shell commands. This parameter prevents redirection and piping, but does not alter parsing behavior. A user can still type redirection and piping tokens, and they will be parsed as such but they won’t do anything.

• multiline_commands – list of commands allowed to accept multi-line input

• terminators – list of characters that terminate a command. These are mainly intended for terminating multiline commands, but will also terminate single-line commands. If not supplied, the default is a semicolon. If your app only contains single-line commands and you want terminators to be treated as literals by the parser, then set this to an empty list.

• shortcuts – dictionary containing shortcuts for commands. If not supplied, then defaults to constants.DEFAULT_SHORTCUTS. If you do not want any shortcuts, pass an empty dictionary.

• command_sets – Provide CommandSet instances to load during cmd2 initialization. This allows CommandSets with custom constructor parameters to be loaded. This also allows the a set of CommandSets to be provided when auto_load_commands is set to False

• auto_load_commands – If True, cmd2 will check for all subclasses of CommandSet that are currently loaded by Python and automatically instantiate and register all commands. If False, CommandSets must be manually installed with register_command_set.

• allow_clipboard – If False, cmd2 will disable clipboard interactions

• suggest_similar_command – If True, cmd2 will attempt to suggest the most similar command when the user types a command that does not exist. Default: False.

“param intro: Intro banner to print when starting the application.

Methods

do_clone_tile(args) → None

Clone a tile or supertile directory and register it in fabric.csv.

Copies the source tile directory to a new destination directory, renaming all files and replacing all internal references to match the new tile name. Also appends the required Tile/Supertile entries to fabric.csv.

Notes

Only works correctly for tiles that follow the default FABulous tile naming scheme, where the tile name is used as a prefix for all files and internal references (e.g. LUT4AB.csv, LUT4AB_switch_matrix.list).

Parameters:

args (Namespace) –

Command arguments containing:

• src_tile: Name of the existing tile (looked up in Tile/) or path to a tile directory

• dst_tile: Name for the new tile (placed in Tile/) or path to the destination directory

• no_register: If True, skip updating fabric.csv

do_exit(*_ignored) → bool

Exit the FABulous shell and log info message.

do_gen_all_tile(*_ignored) → None

Generate all tiles by calling do_gen_tile.

do_gen_all_tile_macros(args) → None

Generate GDSII files for all tiles in the fabric.

do_gen_bitStream_binary(args) → None

Generate bitstream of a given design.

deprecated: Use compile_design which includes bitstream generation.

do_gen_bitStream_spec(*_ignored) → None

Generate bitstream specification of the fabric.

By calling genBitStreamSpec and saving the specification to a binary and CSV file.

Also logs the paths of the output files.

do_gen_config_mem(args) → None

Generate configuration memory of the given tile.

Parsing input arguments and calling genConfigMem.

Logs generation processes for each specified tile.

do_gen_fabric(*_ignored) → None

Generate fabric based on the loaded fabric.

Calling gen_all_tile and genFabric.

Logs start and completion of fabric generation process.

do_gen_fabric_macro(*_args) → None

Generate GDSII files for the entire fabric.

do_gen_geometry(args) → None

Generate geometry of fabric for FABulator.

Checking if fabric is loaded, and calling ‘genGeometry’ and passing on padding value. Default padding is ‘8’.

Also logs geometry generation, the used padding value and any warning about faulty padding arguments, as well as errors if the fabric is not loaded or the padding is not within the valid range of 4 to 32.

do_gen_io_fabric(_args) → None

Generate I/O BELs for the entire fabric.

This command generates Input/Output Basic Elements of Logic (BELs) for all applicable tiles in the fabric, providing external connectivity across the entire FPGA design.

Parameters:

_args (str) – Command arguments (unused for this command).

do_gen_io_pin_config(args) → None

Generate an IO pin configuration YAML file for a tile or supertile.

do_gen_io_tiles(args) → None

Generate I/O BELs for specified tiles.

This command generates Input/Output Basic Elements of Logic (BELs) for the specified tiles, enabling external connectivity for the FPGA fabric.

Parameters:

args (Namespace) –

Command arguments containing:

• tiles: List of tile names to generate I/O BELs for

do_gen_model_npnr(*_ignored) → None

Generate Nextpnr model of fabric.

By parsing various required files for place and route such as pips.txt, bel.txt, bel.v2.txt and template.pcf. Output files are written to the directory specified by metaDataDir within projectDir.

Logs output file directories.

do_gen_switch_matrix(args) → None

Generate switch matrix of given tile.

Parsing input arguments and calling genSwitchMatrix.

Also logs generation process for each specified tile.

do_gen_tile(args) → None

Generate given tile with switch matrix and configuration memory.

Parsing input arguments, call functions such as genSwitchMatrix and genConfigMem. Handle both regular tiles and super tiles with sub-tiles.

Also logs generation process for each specified tile and sub-tile.

do_gen_tile_macro(args) → None

Generate GDSII files for a specific tile.

This command generates GDSII files for the specified tile, allowing for the physical representation of the tile to be created.

Parameters:

args (Namespace) –

Command arguments containing:

• tile: Name of the tile to generate GDSII files for

do_gen_top_wrapper(*_ignored) → None

Generate top wrapper of the fabric by calling genTopWrapper.

do_gen_user_design_wrapper(args) → None

Generate a user design wrapper for the specified user design.

This command creates a wrapper module that interfaces the user design with the FPGA fabric, handling signal connections and naming conventions.

Parameters:

args (Namespace) –

Command arguments containing:

• user_design: Path to the user design file

• user_design_top_wrapper: Path for the generated wrapper file

Raises:

CommandError – If the fabric has not been loaded yet.

do_generate_custom_tile_config(args) → None

Generate a custom tile configuration for a given tile folder.

Or path to bel folder. A tile .csv file and a switch matrix .list file will be generated.

The provided path may contain bel files, which will be included in the generated tile .csv file as well as the generated switch matrix .list file.

do_install_FABulator(args) → None

Download and install the latest version of FABulator.

Sets the the FABULATOR_ROOT environment variable in the .env file.

do_install_oss_cad_suite(args) → None

Download and extract the latest OSS CAD suite.

The installation will set the FAB_OSS_CAD_SUITE environment variable in the .env file.

do_load_fabric(args) → None

Load ‘fabric.csv’ file and generate an internal representation of the fabric.

Parse input arguments and set a few internal variables to assist fabric generation.

do_place_and_route(args) → None

Run place and route with Nextpnr for a given JSON file.

deprecated: Use compile_design --pnr-only instead.

do_print_bel(args) → None

Print a Bel object to the console.

do_print_tile(args) → None

Print a tile object to the console.

do_q(*_ignored) → None

Exit the FABulous shell and log info message.

do_quit(*_ignored) → None

Exit the FABulous shell and log info message.

do_run_FABulous_bitstream(args) → None

Run FABulous to generate bitstream on a given design.

deprecated: Use compile_design instead.

do_run_FABulous_eFPGA_macro(*_arg) → None

Run the full FABulous eFPGA macro generation flow.

do_run_FABulous_fabric(*_ignored) → None

Generate the fabric based on the CSV file.

Create bitstream specification of the fabric, top wrapper of the fabric, Nextpnr model of the fabric and geometry information of the fabric.

do_run_script(args) → None

Execute script.

do_run_simulation(args) → None

Simulate given FPGA design.

Uses Taskfile.yml (preferred) or falls back to Make (deprecated). The bitstream_file argument should be a binary file generated by ‘gen_bitStream_binary’.

do_run_tcl(args) → None

Execute TCL script relative to the project directory.

Specified by <tcl_scripts>. Use the ‘tk’ module to create TCL commands.

Also logs usage errors and file not found errors.

do_start_FABulator(*_ignored) → None

Start FABulator if an installation can be found.

If no installation can be found, a warning is produced.

do_start_klayout_gui(args) → None

Start OpenROAD GUI if an installation can be found.

If no installation can be found, a warning is produced.

do_start_openroad_gui(args) → None

Start OpenROAD GUI if an installation can be found.

If no installation can be found, a warning is produced.

do_synthesis(args) → None

Run Yosys synthesis for the specified Verilog files.

deprecated: Use compile_design --synth-only instead.

do_timing_model(args) → None

Generate a timing model for the fabric.

Timing information is extracted from the GDS layout and used to create a timing model compatible with nextpnr for timing-aware place and route. This command generates a timing model for the FPGA fabric based on the specified mode (physical or structural) and outputs it to a file named pips.txt in the .FABulous directory. If no config file is provided, the automated flow must be run first to generate post-layout files. If a config file is provided, it will be used for timing model generation instead of CLI arguments. This allows for more complex configurations like different PDK support. If emit-config-template is specified, a config template will be output and no timing model will be generated.

onecmd(statement, *, add_to_history=True) → bool

Override the onecmd method to handle exceptions.

INTO_STRING = Multiline-String

Show Value

"""
     ______      ____        __
    |  ____/\   |  _ \      | |
    | |__ /  \  | |_) |_   _| | ___  _   _ ___
    |  __/ /\ \ |  _ <| | | | |/ _ \| | | / __|
    | | / ____ \| |_) | |_| | | (_) | |_| \__ \
    |_|/_/    \_\____/ \__,_|_|\___/ \__,_|___/


Welcome to FABulous shell
You have started the FABulous shell with following options:


Type help or ? to list commands
To see documentation for a command type:
    help <command>
or
    ?<command>

To execute a shell command type:
    shell <command>
or
    !<command>

The shell support tab completion for commands and files

To run the complete FABulous flow with the default project, run the following command:
    run_FABulous_fabric
    compile_design ./user_design/sequential_16bit_en.v
    run_simulation fst ./user_design/sequential_16bit_en.bin
"""

KLAYOUT_LAYER_FILE_NAMES: dict[str, str]

META_DATA_DIR = '.FABulous'