Command Line Interface¶
BLADE is provided with a comprehensive command line interface that will be sufficient for most needs. It will allow you to parse a design and generate a DesignFormat blob which you can then use to drive other tools such as code generators.
BLADE requires Python 3.6 or newer to operate, it also needs a checkout of DesignFormat available on your system - with the path to the root directory exported as
DESIGN_FORMAT_DIR. DesignFormat is not distributed as part of BLADE as it is a standalone library.
You can access a quick description of BLADE and the options it takes by executing the following command:
$> export DESIGN_FORMAT_DIR=../design_format $> python3.6 -m blade -h usage: __main__.py [-h] [--include INCLUDE] --top TOP [--enable-convert] [--define DEFINE] --output OUTPUT [--report] [--report-path REPORT_PATH] [--dependencies] [--MT MT] [--MF MF] [--shallow] [--run-checks] [--waiver-file WAIVER_FILE] [--ignore-check-errors] [--quiet] [--profile] [--debug] Tool for elaborating the Phhidle YAML into DesignFormat optional arguments: -h, --help show this help message and exit --include INCLUDE, -i INCLUDE Include a files or folder --top TOP, -t TOP Path to the 'top' file to start elaborating from --define DEFINE, -D DEFINE Define a value for the preprocessor phase. Optionally you can specify the value '--define MYVAR=123'. --output OUTPUT, -o OUTPUT Output path to store the DFBlob or DFProject file. --report Enable HTML report generation after blob generation completes. --report-path REPORT_PATH Specify the output path for the report. --dependencies Enable dependency file generation. --MT MT The Makefile target to generate a dependency list for. --MF MF Output path for Makefile dependency lists for generating this blob. --shallow, -s Run in shallow mode - generating DesignFormat blobs with short hierarchy --run-checks, -c Enable rule checking - will test project before saving it to file --waiver-file WAIVER_FILE, -w WAIVER_FILE Provide waiver files to the checking stage, multiple files can be provided and all waivers considered --ignore-check-errors If enabled, when rule checks fail they will not cause an error exit code --quiet, -q Run in quiet mode - suppressing status messages --profile, -p Enable profiling, measures the execution time of each phase --debug Enable debug messages, including tracebacks after exceptions are caught.
Say you want to generate a DesignFormat blob starting from your design’s top-level
my_soc.yaml. You also have module, register, and interconnect definitions spread across multiple directories that you need to include to fully generate the design. In this case you need to use something like the following syntax:
$> python3.6 -m blade -i /path/to/my/his -i /path/to/my/reg -i /path/to/my/mods -i /path/to/a/specific/mod.md -t /path/to/my/mods/my_soc.yaml -o ./output.df_blob
Working through this command:
-i /path/to/my/...adds a directory, or file, to the search path - allowing the preprocessor to resolve any
#includedirectives that reference it.
-t .../my_soc.yamlspecifies which file contains the top-level of the design. BLADE will identify the root module and elaborate the design tree recursively.
-o ./output.df_blobspecifies the path where the output DesignFormat blob should be written to.
While this example uses a
!Mod as its top-level, you can equally provide files containing
!Def as the root nodes and the elaborator will adjust accordingly.
For top-levels that contain multiple documents, each tag will be separately elaborated and attached to a single DFProject. This can be especially useful when a file contains multiple nodes like
!Def, allowing you to store all of your constants in one place.
BLADE captures all of the debug, info, warning, and error messages raised as it runs and can write them out to file in a single page HTML report. By default this report is not generated, but you can easily switch it on:
$> python3.6 -m blade -i ... -t my_soc.yaml ... --report --report-path ./my_report.html
The important options here are:
--reportswitches on report generation. Log messages are always captured and printed on the command line, but won’t normally be written out to a file - this option forces a report to be written out.
--report-pathallows you to specify the path that the report will be written to. If you leave out this option then the report will be written to the default file of
report.htmlin the current working directory.
Generating Makefile Dependencies¶
BLADE can generate dependency files that can be included into Makefiles to reduce the recomputation necessary any time a file in your design changes.
$> python3.6 -m blade -i ... -t my_soc.yaml -o my_soc.df_blob --dependencies --MT my_soc.df_blob --MF my_soc.deps
The arguments largely use the same syntax as GCC:
--dependenciesenables dependency computation and file generation, in accordance with the next two parameters.
--MT my_soc.df_blobspecifies which Makefile target we want to generate dependencies for - this should normally match the name of your output blob file.
--MF my_soc.depsspecifies the path where the dependency file should be written - here we’re going to create
my_soc.depsin the current working directory.
Enabling Rule Checks¶
BLADE has an extensible engine for running automated rule checks against a fully elaborated design - although by default this feature is switched off. To enable it use the following command:
$> python3.6 -m blade ... --run-checks --waiver-file my.waivers --waiver-file ../freds.waivers
Here we’ve used some of the possible options:
--run-checksenables rule checking - without this the checking stage is bypassed silently.
--waiver-file my.waiversspecifies a waiver file - you can have as many of these as you require, the syntax is detailed on the checker’s architecture page.
One other option not used above is
--ignore-check-errors - this stops the tool exiting with an error code (exit code != 0) if any rule checks (critical or not) fail. This is not the default behaviour.
Passing in Defined Values¶
When the preprocessor executes, it will replace any values that it is aware of with constants defined in the scope. There are three ways to define a constant:
You can use a
#define MY_KEY 2declaration within your source code;
You can export a value into your environment before executing BLADE (e.g.
Or, you can define a value on the command line using
$> python3.6 -m blade ... --define MY_KEY_W_VAL=3 --define JUST_A_KEY
As shown above you can optionally provide a value to a defined key by using the syntax
--define <KEY>=<VAL>. If you do not provide a value, then it will be given a boolean
True value by default.
Limiting the Elaboration Depth¶
By default BLADE will recursively elaborate the design until it is fully resolved. However, you can limit the depth of the recursion by using the
--shallow option. This will restrict
!Mod elaboration to just one level - or in other words it will fully elaborate the parent module, but will only calculate the boundary IO for any child modules.
$> python3.6 -m blade -i ... -t top.yaml --shallow
This is especially useful when you want to produce small blobs for driving autogeneration, rather than caring about the fully elaborated design.