FABulous.FABulous_CLI.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.

Classes

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

Bases:

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

intro

Introduction message displayed when CLI starts

Type:

str

prompt

Command prompt string displayed to users

Type:

str

fabulousAPI

Instance of the FABulous API for fabric operations

Type:

FABulous_API

projectDir

Current project directory path

Type:

Path

top

Top-level module name for synthesis

Type:

str

allTile

List of all tile names in the current fabric

Type:

list[str]

csvFile

Path to the fabric CSV definition file

Type:

Path

extension

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

Type:

str

script

Batch script commands to execute

Type:

str

force

If true, force operations without confirmation

Type:

bool

interactive

If true, run in interactive CLI mode

Type:

bool

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.

• writerType (str | None)

• force (bool)

• interactive (bool)

• verbose (bool)

• debug (bool)

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

Properties:

Methods:

do_exit(*_ignored)

Exit the FABulous shell and log info message.

Parameters:

_ignored (str)

Return type:

bool

do_gen_all_tile(*_ignored)

Generate all tiles by calling do_gen_tile.

Parameters:

_ignored (str)

Return type:

None

do_gen_bitStream_binary(args)

Generate bitstream of a given design.

Using FASM file and pre-generated bitstream specification file bitStreamSpec.bin. Requires bitstream specification before use by running gen_bitStream_spec and place and route file generated by running place_and_route.

Also logs output file directory, Bitstream generation error and file not found error.

Parameters:

args (Namespace)

Return type:

None

do_gen_bitStream_spec(*_ignored)

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.

Parameters:

_ignored (str)

Return type:

None

do_gen_config_mem(args)

Generate configuration memory of the given tile.

Parsing input arguments and calling genConfigMem.

Logs generation processes for each specified tile.

Parameters:

args (Namespace)

Return type:

None

do_gen_fabric(*_ignored)

Generate fabric based on the loaded fabric.

Calling gen_all_tile and genFabric.

Logs start and completion of fabric generation process.

Parameters:

_ignored (str)

Return type:

None

do_gen_geometry(args)

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.

Parameters:

args (Namespace)

Return type:

None

do_gen_io_fabric(_args)

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).

Return type:

None

do_gen_io_tiles(args)

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

Return type:

None

do_gen_model_npnr(*_ignored)

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.

Parameters:

_ignored (str)

Return type:

None

do_gen_switch_matrix(args)

Generate switch matrix of given tile.

Parsing input arguments and calling genSwitchMatrix.

Also logs generation process for each specified tile.

Parameters:

args (Namespace)

Return type:

None

do_gen_tile(args)

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.

Parameters:

args (Namespace)

Return type:

None

do_gen_top_wrapper(*_ignored)

Generate top wrapper of the fabric by calling genTopWrapper.

Parameters:

_ignored (str)

Return type:

None

do_gen_user_design_wrapper(args)

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.

Return type:

None

do_generate_custom_tile_config(args)

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.

Parameters:

args (Namespace)

Return type:

None

do_install_FABulator(args)

Download and install the latest version of FABulator.

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

Parameters:

args (Namespace)

Return type:

None

do_install_oss_cad_suite(args)

Download and extract the latest OSS CAD suite.

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

Parameters:

args (Namespace)

Return type:

None

do_load_fabric(args)

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.

Parameters:

args (Namespace)

Return type:

None

do_place_and_route(args)

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

Generated by Yosys, which requires a Nextpnr model and JSON file first, generated by synthesis.

Also logs place and route error, file not found error and type error.

Parameters:

args (Namespace)

Return type:

None

do_print_bel(args)

Print a Bel object to the console.

Parameters:

args (Namespace)

Return type:

None

do_print_tile(args)

Print a tile object to the console.

Parameters:

args (Namespace)

Return type:

None

do_q(*_ignored)

Exit the FABulous shell and log info message.

Parameters:

_ignored (str)

Return type:

None

do_quit(*_ignored)

Exit the FABulous shell and log info message.

Parameters:

_ignored (str)

Return type:

None

do_run_FABulous_bitstream(args)

Run FABulous to generate bitstream on a given design.

Does this by calling synthesis, place and route, bitstream generation functions. Requires Verilog file specified by <top_module_file>.

Also logs usage error and file not found error.

Parameters:

args (Namespace)

Return type:

None

do_run_FABulous_fabric(*_ignored)

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.

Parameters:

_ignored (str)

Return type:

None

do_run_script(args)

Execute script.

Parameters:

args (Namespace)

Return type:

None

do_run_simulation(args)

Simulate given FPGA design using Icarus Verilog (iverilog).

If <fst> is specified, waveform files in FST format will generate, <vcd> with generate VCD format. The bitstream_file argument should be a binary file generated by ‘gen_bitStream_binary’. Verilog files from ‘Tile’ and ‘Fabric’ directories are copied to the temporary directory ‘tmp’, ‘tmp’ is deleted on simulation end.

Also logs simulation error and file not found error and value error.

Parameters:

args (Namespace)

Return type:

None

do_run_tcl(args)

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.

Parameters:

args (Namespace)

Return type:

None

do_start_FABulator(*_ignored)

Start FABulator if an installation can be found.

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

Parameters:

_ignored (str)

Return type:

None

do_synthesis(args)

Run synthesis on the specified design.

Parameters:

args (Namespace)

Return type:

None

onecmd(statement, *, add_to_history=True)

Override the onecmd method to handle exceptions.

Parameters:

• statement (Statement | str)

• add_to_history (bool)

Return type:

bool

Functions

Module Attributes

CMD_FABRIC_FLOW

CMD_GUI

CMD_HELPER

CMD_OTHER

CMD_SCRIPT

CMD_SETUP

CMD_TOOLS

CMD_USER_DESIGN_FLOW

INTO_STRING

META_DATA_DIR