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_TOOLS
CMD_USER_DESIGN_FLOW
INTO_STRING
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_TOOLS = 'Tools'

CMD_USER_DESIGN_FLOW = 'User Design Flow'

FABulous_CLI

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

Inheritance: → FABulous_CLI

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.

param writerType:

The writer type to use for generating fabric.

type writerType:

str | None

param force:

If True, force operations without confirmation, by default False

type force:

bool

param interactive:

If True, run in interactive CLI mode, by default False

type interactive:

bool

param verbose:

If True, enable verbose logging, by default False

type verbose:

bool

param debug:

If True, enable debug logging, by default False

type debug:

bool

ivar intro:

Introduction message displayed when CLI starts

vartype intro:

str

ivar prompt:

Command prompt string displayed to users

vartype prompt:

str

ivar fabulousAPI:

Instance of the FABulous API for fabric operations

vartype fabulousAPI:

FABulous_API

ivar projectDir:

Current project directory path

vartype projectDir:

pathlib.Path

ivar top:

Top-level module name for synthesis

vartype top:

str

ivar allTile:

List of all tile names in the current fabric

vartype allTile:

list[str]

ivar csvFile:

Path to the fabric CSV definition file

vartype csvFile:

pathlib.Path

ivar extension:

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

vartype extension:

str

ivar script:

Batch script commands to execute

vartype script:

str

ivar force:

If true, force operations without confirmation

vartype force:

bool

ivar interactive:

If true, run in interactive CLI mode

vartype interactive:

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.

param completekey:

readline name of a completion key, default to Tab

param stdin:

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

param stdout:

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

param persistent_history_file:

file path to load a persistent cmd2 command history from

param persistent_history_length:

max number of history items to write to the persistent history file

param startup_script:

file path to a script to execute at startup

param silence_startup_script:

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

param include_py:

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

param include_ipy:

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

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

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

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

param multiline_commands:

list of commands allowed to accept multi-line input

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

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

param 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

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

param allow_clipboard:

If False, cmd2 will disable clipboard interactions

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

do_exit*_ignored      :module:

Exit the FABulous shell and log info message.

do_gen_all_tile*_ignored      :module:

Generate all tiles by calling do_gen_tile.

do_gen_all_tile_macrosargs      :module:

Generate GDSII files for all tiles in the fabric.

do_gen_bitStream_binaryargs      :module:

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.

do_gen_bitStream_spec*_ignored      :module:

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_memargs      :module:

Generate configuration memory of the given tile.

Parsing input arguments and calling genConfigMem.

Logs generation processes for each specified tile.

do_gen_fabric*_ignored      :module:

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      :module:

Generate GDSII files for the entire fabric.

do_gen_geometryargs      :module:

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      :module:

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.

param _args:

Command arguments (unused for this command).

type _args:

str

do_gen_io_tilesargs      :module:

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.

param args:

Command arguments containing: - tiles: List of tile names to generate I/O BELs for

type args:

argparse.Namespace

do_gen_model_npnr*_ignored      :module:

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_matrixargs      :module:

Generate switch matrix of given tile.

Parsing input arguments and calling genSwitchMatrix.

Also logs generation process for each specified tile.

do_gen_tileargs      :module:

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_macroargs      :module:

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.

param args:

Command arguments containing: - tile: Name of the tile to generate GDSII files for

type args:

argparse.Namespace

do_gen_top_wrapper*_ignored      :module:

Generate top wrapper of the fabric by calling genTopWrapper.

do_gen_user_design_wrapperargs      :module:

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.

param args:

Command arguments containing: - user_design: Path to the user design file - user_design_top_wrapper: Path for the generated wrapper file

type args:

argparse.Namespace

raises CommandError:

If the fabric has not been loaded yet.

do_generate_custom_tile_configargs      :module:

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_FABulatorargs      :module:

Download and install the latest version of FABulator.

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

do_install_oss_cad_suiteargs      :module:

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_fabricargs      :module:

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_routeargs      :module:

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.

do_print_belargs      :module:

Print a Bel object to the console.

do_print_tileargs      :module:

Print a tile object to the console.

do_q*_ignored      :module:

Exit the FABulous shell and log info message.

do_quit*_ignored      :module:

Exit the FABulous shell and log info message.

do_run_FABulous_bitstreamargs      :module:

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.

do_run_FABulous_eFPGA_macro*_arg      :module:

Run the full FABulous eFPGA macro generation flow.

do_run_FABulous_fabric*_ignored      :module:

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_scriptargs      :module:

Execute script.

do_run_simulationargs      :module:

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.

do_run_tclargs      :module:

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      :module:

Start FABulator if an installation can be found.

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

do_start_klayout_guiargs      :module:

Start OpenROAD GUI if an installation can be found.

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

do_start_openroad_guiargs      :module:

Start OpenROAD GUI if an installation can be found.

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

do_synthesisargs      :module:

Run synthesis on the specified design.

onecmdstatement, *, add_to_history = True      :module:

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
    run_FABulous_bitstream ./user_design/sequential_16bit_en.v
    run_simulation fst ./user_design/sequential_16bit_en.bin
"""

META_DATA_DIR = '.FABulous'