../_images/stfc_technology.gif

Electronic System Design Group

Documentation Status

Settings

The script uses settings using a YAML file passed using the --settings argument (see Arguments).

The description of the YAML file is described here.

python ./projectflow.py --settings <SETTINGS.YML>

Sections

<CATEGORY>:

The category of the project from list of categories: in the configuration file (see Configuration). Ths defines the repository layout of the project (see <CATEGORY>_layout:).

name:

Name of the project.

Note

The value here is used by Tag Substitution replacing the <NAME> tags in the Configuration file.

contrib_lib:

Name of the contributor’s library. This defines the owner of the project and is used in the path to the location/structure of the project as it is stored in the externally hosted repository.

Note

contributors: defines a list of all of the contributors. The value here is used by Tag Substitution replacing <CONTRIB_LIB> tags in the Configuration file.

top_level:

Name of the top-level entity HDL component. This can be a str or list and the entity name should appear in the HDL filename. If no top-levels are supplied the script will search for files in library (determined from name:) for filenames which contain name: and one term from: ['top_', '_top']. If none are found the script will exit.

Used by projectflow in conjunction with board_id: to generate the FPGA Vendor project name, if no board_id: is supplied:

<TOP_LEVEL>

where <TOP_LEVEL> is the first item in top_level: list (or the str of top_level: is supplied as a single entry).

The project name can be overwritten by project_name_override:

top_level_tb_entity:

Name of the top-level test-bench used when executing VUnit simulations.

vendor:

Name of the FPGA vendor the project is targeting.

Note

The value here is used by Tag Substitution replacing <VENDOR> tags in the Configuration file.

family:

Name of the FPGA family the project is targeting.

Note

The value here is used by Tag Substitution replacing <FAMILY> tags in the Configuration file.

tool_version:

Version of the FPGA vendor tool to use for the generation of the project.

Note

The value here is used by Tag Substitution replacing <TOOL_VERSION> tags in the Configuration file.

tool_mode:

Value to set the corresponding system environment variable to define the FPGA vendor tool operating mode. Sets either 32 or 64 bit operation.

device:

FPGA vendor defined device identifier to use for the generation of the project.

board_id:

A hex represented 32 bit number to insert into the FPGA project via a top-level generic named: g_board_id. This will be converted into a integer.

Generated Quartus settings file entry for board_id
set_parameter -name g_board_id 0
board_id generic
generic(
    g_board_id        : integer := 0
);

This can then be used in user logic using:

board_id user logic constant
constant c_board_id        : std_logic_vector(31 downto 0) := std_logic_vector(to_unsigned(g_board_id, 32));

Note

This is a board only option.

board_timestamp_enabled:

The script will generate a Unix 32 bit timestamp for when the corresponding FPGA project is generated by the script. If this option is enabled using True the timestamp will be inserted via a top-level generic named: g_board_timestamp.

Generated Quartus settings file entry for board_timestamp
set_parameter -name g_board_timestamp 0
board_timestamp generic
generic(
    g_board_timestamp        : integer := 0
);

This can then be used in user logic using:

board_timestamp user logic constant
constant c_board_timestamp    : std_logic_vector(31 downto 0) := std_logic_vector(to_unsigned(g_board_timestamp, 32));

Note

This is a board only option.

board:

Predefined hardware to target when generating the project. If supplied projectflow will use this value to generate the FPGA Vendor project name in the form:

<BOARD>_<TOP_LEVEL>

where <BOARD> is the board_id: name and <TOP_LEVEL> is the first item in top_level: list (or the str of top_level: is supplied as a single entry).

The project name can be overwritten by project_name_override:

board_settings:

Name of the settings file to parse when associating board with design.

Warning

Options in this file will overwrite options in the calling settings file.

project_name_override:

Option to override the automatically generated project name with a custom name.

sim_vendor:

Simulation vendor to use when running simulations.

sim_version:

Version of the simulation tool to use when running simulations.

Note

The value here is used by Tag Substitution replacing <SIM_VERSION> in the Configuration file.

sim_mode:

Value to set the corresponding system environment variable to define the simulation tool operating mode. Sets either 32 or 64 bit operation.

sim_init_script:

Name of the simulation initialisation script to usw when running simulations in GUI mode.

Note

Use: $env(REPO_ROOT) to avoid including user specific absolute paths in this file.

use_glbl:

If True adds glbl dependencies to xilinx simulations.

Note

This is a xilinx only option and is ignored for altera projects.

vunit_args:

Allows options from settings.yml YAML file to be passed to VUnit as if they are command-line arguments. For detailed information see: VUnit Documentation.

example settings.yml entry for vunit_args
vunit_args:
  version:                False
  list:                   False
  files:                  False
  log_level:              warning
  output_path:            simulation/vunit_output
  test_patterns:
    - None
  keep_compiling:         True
  num_threads:            2
  elaborate:              False
  verbose:                False
  xunit_xml:              xunit_report.xml
  coverage:
  unique_sim:             False
  exit_0:                 False
  no_color:               False
  quiet:                  True
  xunit_xml_format:       'bamboo'
  dont_catch_exceptions:  False
  export_json:            ''
  with_attributes:
  without_attributes:
  compile:                False
  fail_fast:              False

version:

Reports the version being used. See: vunit_cli

Warning

If True This will report the version number and exit, not running VUnit. The script will raise a warning log if this option is set.

list:

Lists the test-cases being used without executing the simulation. See: vunit_cli

Warning

If True This will list the test-cases being used by simulation and exit, not running VUnit. The script will raise a warning log if this option is set.

files:

Lists the HDL files being used without executing the simulation. See: vunit_cli

Warning

If True This will list the files being used by simulation and exit, not running VUnit. The script will raise a warning log if this option is set.

log_level:

Sets the log-level for simulation. See: vunit_cli

output_path:

Sets the output_path for generated simulation files. See: vunit_cli

test_patterns:

List of test-cases or test-case patterns to simulate. - None will not run any test-cases.

keep_compiling:

If True keep compiling HDL if errors are found. Otherwise will exit on first error. See: vunit_cli

num_threads:

Number of threads to use running simulations. See: vunit_cli

elaborate:

Use elaborate. See: vunit_cli See: vunit_cli

verbose:

Run in verbose mode. See: vunit_cli

xunit_xml:

Name of the XML Report file. See: vunit_cli

coverage:

Use full coverage. See: vunit_cli

unique_sim:

Use unique simulations. See: vunit_cli

exit_0:

Exit with code 0 on errors. See: vunit_cli

no_color:

Disables colour logging when True. See: vunit_cli

xunit_xml_format:

Sets the format for the generated xunit_xml report file. Set to 'bamboo'. See: vunit_cli

dont_catch_exceptions:

From VUnit Documentation: “Let exceptions bubble up all the way. Useful when running with “python -m pdb”.”.
See: vunit_cli

export_json:

From VUnit Documentation: “Export project information to a JSON file.”

json file will be generated in the output_path:. Leave blank to skip generation. See: vunit_cli

with_attributes:

List of test-cases or test-case to simulate which do have these attributes. Leave blank or have a single item of '' to ignore.

From VUnit Documentation: “Only select tests with these attributes set”

without_attributes:

List of test-cases or test-case to simulate which do not have these attributes. Leave blank or have a single item of '' to ignore.

From VUnit Documentation: “Only select tests without these attributes set” See: vunit_cli See: vunit_cli

compile:

When `True compiles HDL and exits. See: vunit_cli

fail_fast:

When True stop on first failed test. See: vunit_cli

repository_config:

Defines location in externally hosted source-code repository for the top-level project and each dependency required to execute projectmanager

git:

example settings.yml entry for respository_config
repository_config:
  git:
    <NAME>:
      enabled:            True
      vunit_default:      False
      url:                <https://<GIT_BITBUCKET_URL/>
      path:               tools/xml2vhdl
      branch:             master
      tag:
      required_vhdl_libs: []

Warning

Tag Substitution has not been tested here. <> Should be replaced by actual values.

<NAME>:

The name of the project or project dependency.

enabled:
Location is processed by the script if set to: True, otherwise skipped if set to: False.
vunit_default:
Location is processed by Vunit` if set to: True, otherwise skipped by Vunit if set to: False.
url:

Top-Level URL of externally hosted git repository hosted on bitbucket.

Note

This is the clone URL from bitbucket with the username@ portion removed. username@ will be generated by projectmanager from $BITBUCKET_USERNAME system environment variable.

path:
Path of location on the local file-system. Should match project path based on categories: and <CATEGORY>_layout: for the project or project dependency being defined.
branch:
Specific git branch to use.
tag:

Specific git tag to use.

Note

tag: is not used in the context of using FPGAFlow to clone git repositories. The user is expected to manage tags and branches for development purposes after the repository has been cloned.

required_vhdl_libs:

List of required VHDL libraries, names matching corresponding <NAME> entry in git: or subversion:.

Note

required_vhdl_libs: is currently only used to ensure the VHDL libraries used by XML2VHDL script are included and enabled in projectflow.

subversion:

example settings.yml entry for respository_config
repository_config:
  subversion:
    <NAME>:
      enabled:            True
      vunit_default:      True
      url:                <https://<SVN_REPO_ROOT_URL/>
      path:               <CATEGORY>/<CONTRIB_LIB>/<NAME>
      subpath:            trunk
      rev:                HEAD
      required_vhdl_libs: []

Warning

Tag Substitution has not been tested here. <> Should be replaced by actual values.

<NAME>:

The name of the project or project dependency.

enabled:
Location is processed by the script if set to: True, otherwise skipped if set to: False.
vunit_default:
Location is processed by Vunit` if set to: True, otherwise skipped by Vunit if set to: False.
url:
Top-Level URL of externally hosted SVN repository.
path:
Path of location in repository. Should match project path based on categories: and <CATEGORY>_layout: for the project or project dependency being defined.
subpath:
'trunk', 'branches/<BRANCH_NAME>' or 'tag/<TAG_NAME>' for the project or project dependency being defined.
rev:
Specific SVN revision or HEAD.
required_vhdl_libs:
List of required VHDL libraries, names matching corresponding <NAME> entry in git: or subversion:.

documentation:

example settings.yml entry for documentation
documentation:
  project_title:          'Project Documentation Title'
  project_version:        '2019.1'
  project_author:         'Electronic System Design Group, Technology'
  project_org:            'Science and Technology Facilities Council'
  project_release:
  doxy_version:           1.8.14
  dot_version:            2.40.1
  sphinx_version:         1.8.2
  image_path:             common/images
  logo_path:              common/logo
  logo_name:              logo.png
  source_path:            common/source
  language:               vhdl
  restricted_src:         False
  doc_clean:              True
  release_uri:            'https://bitbucket.org/mjroberts/fpgaflow/branch/release'
  issue_uri:              False
  releases_document_name: False
  doxy_mainpage:
    name:                 'README.md'
    autogen_pagelinks:    True
    autostruct:
      - 'readme_header.md'
      - 'readme_description.md'

project_title:

The Name of the Current Project Documentation.

project_version:

The Version Number of the Project Documentation in the form:

YYYY.NN

project_author:

The Project Documentation Author.

project_org:

The Project Documentation Organisation.

project_release:

The Project Documentation Release Tag.

doxy_version:

The Version of doxygen to use to build VHDL documentation.

Note

This version should be available on the host system and this value must be included in the documentation: doxygen: support_tools: within the configuration file (see Configuration).

dot_version:

The Version of graphviz used by doxygen when building documentation.

Note

This version should be available on the host system and this value must be included in the documentation: dot: support_tools: within the configuration file (see Configuration).

sphinx_version:

The Version of sphinx used when building documentation.

Note

This version should be available on the host system, either globally installed or included in the python virtual environment (see Python Modules) and this value must be included in the documentation: sphinx: support_tools: within the configuration file (see Configuration).

image_path:

The path of the image directory to include in the generated documentation. This path is relative to: ./docs

logo_path:

The path of the logo directory to include in the generated documentation. This path is relative to: ./docs

logo_name:

The name of the logo file, which must exist in the logo_path: to use in the generated documentation.

source_path:

The path additional source directory to include in the generated documentation. This path is relative to: ./docs

language:

The main language used in the project.

python
Documentation will be generated using sphinx only.
vhdl

Documentation will be generated using doxygen from VHDL source code. This will then be included and referenced by sphinx which provides the top-level documentation for the project.

Note

This language must be included in the documentation: supported_languages: within the configuration file (see Configuration).

restricted_src:

When this option is set True doxygen is prevented from including source code in the generated documentation. Valid values are: True or False.

Note

restricted_src: defaults to True if the option is not included in the settings file.

doc_clean:

When this option is set True the documentation build paths are deleted prior to building the project documentation. Valid values are: True or False.

release_uri:

Using releases to handle changelogs. See releases_usage. This is currently configured for bitbucket so /%s is appended to the end of the supplied URL automatically.

Note

release_uri: is optional, if not used it should be set to False in the settings file.

issue_uri:

Using releases to handle changelogs. See releases_usage.

Note

issue_uri: is optional, if not used it should be set to False in the settings file.

releases_document_name:

Using releases to handle changelogs. See releases_usage. If not defined here it will default to changelog.rst.

Note

releases_document_name: is optional, if not used it should be set to False in the settings file.

doxy_mainpage:

These options define the doxygen mainpage used to reference any pages generated by doxygen from source code, which is then referenced by the top-level documentation generated by sphinx.

name:
Name of the mainpage to generate.
autostruct:
A list of files, which should be placed in the projects docs/doxygen/source directory, which should be added to the mainpage used by doxygen. The order of the list defines the order the contents of these files will by added to the mainpage.
autogen_pagelinks:

Configures if the documentation generated by doxygen should be parsed to (re)generate links to pages to include on the mainpage. Valid values are: True or False.

This will automatically generate a file named: <lowercase_name>_links.md where <lowercase_name> matches the name of the mainpage to generate defined by name:.

Note

When generating documentation doxygen uses either the @page uniquename or \page uniquename tags to define the name of the generated page. By using the convention of suffixing page to the uniquename so that it becomes: uniquenamepage it is possible for the docflow.py script to automatically add these pages as a list of links on mainpage generated by doxygen.

This option will cause doxygen to generate documentation twice, once to generate the pages, the second time to reference the pages on it’s mainpage.