Electronic System Design Group

Configuration

The script is configured using a YAML file passed using the --config argument (see Arguments).

python ./docflow.py --config <CONFIG.YML>

The description of the YAML file is described below.

Tag Substitution

The configuration file operates using tag substitution with values set in the corresponding Settings file. Tags are all uppercase enclosed in <> characters.

<UPPERCASE_TAG>

where the UPPERCASE tag represents a key in the Settings which will be substituted when the script is executed. The repository_required fields in the configuration file should include all tag substitution keys.

Sections

repository:

The repository section configures the expected directory structure of each supported category for code stored in the externally hosted repository.

complete example of config.yml entry for repository section

repository:
  required:
    - name
    - contrib_lib
    - vendor
    - tool_version
    - sim_vendor
    - sim_version
  categories:
    - boards
    - library
    - tools
    - vendor_ip
  category_mapping:
    library: libraries
  lib_append_categories:
    - boards
    - library
  boards_layout:
    - boards:
      - <VENDOR>:
        - <NAME>:
          - <TOOL_VERSION>:
            - constraints:
            - docs:
              - common:
                - logo:
              - doxygen:
                - <DOXY_VERSION>:
                  - source:
              - sphinx:
                - <SPHINX_VERSION>:
                  - build:
                  - source:
                    - _static:
                    - _templates:
            - scripts:
              - python:
              - tcl:
            - settings:
              - <NAME>.yml
            - simulation:
              - testbenches:
                - EXCLUDE
            - src:
              - vhdl:
                - EXCLUDE
                - generated:
              - vhdl_packages:
              - xml:
  library_layout:
    - libraries:
      - <CONTRIB_LIB>:
        - <NAME>:
            - constraints:
              - <VENDOR>:
                - pre_flow:
                - post_module:
                - post_flow:
                - pre_synth:
                - pre_opt:
            - docs:
              - common:
                - logo:
              - doxygen:
                - <DOXY_VERSION>:
                  - source:
              - sphinx:
                - <SPHINX_VERSION>:
                  - source:
                    - _static:
                    - _templates:
            - netlists:
            - scripts:
              - tcl:
              - python:
            - settings:
              - <NAME>.yml
            - simulation:
              - testbenches:
                - EXCLUDE
            - src:
              - vhdl:
                - EXCLUDE
                - generated:
              - vhdl_packages:
              - xml:
  tools_layout:
    - tools:
      - <NAME>:
        - docs:
          - common:
                - logo:
          - doxygen:
            - <DOXY_VERSION>:
              - source:
          - sphinx:
            - <SPHINX_VERSION>:
              - build:
              - source:
                - _static:
                - _templates:
        - scripts:
          - python:
            - <NAME>-<ORG>:
              - <NAME>:

required:

This provides a list of required field from the Settings file required to execute the script correctly. The script expects each of the list items to be populated in the settings YAML file ready for Tag Substitution.

categories:

This provides a list of categories supported by the script. The layout of each repository item is defined by its category and the <CATEGORY>_layout: settings defined in the configuration YAML file. The list of categories is used by Tag Substitution to determine the <CATEGORY>_layout:.

category_mapping:

If the category is stored in the repository using a different reference category_mapping can be used to map the different category name to the category name.

lib_append_categories:

The convention employed by this script is to name libraries matching their name in the repository. This section allows categories to be listed where _lib should be appended to the name.

Note

Names which already have _lib included in their name in the repository will NOT have _lib re-appended.

<CATEGORY>_layout:

A layout should be defined for each category in the categories: list.

This defines the layout for all files stored in the corresponding repository location. Tag Substitution is used to fully construct the <CATEGORY>_layout> and it is expected that all tags are listed in the repository_required section of the configuration file.

contributors:

complete example of config.yml entry for contributors section

contributors:
  contrib_lib_list:
    - common
    - lib_ox
    - lib_stfc

contrib_lib_list:

A list of contributors for source-code and development within the project. The values here define the ownership and responsibility of items stored in the repository.

Note

It is expected that modifications, enhancements and bugfixes should be undertaken by the owner of the source-code in question.

fpga:

complete example config.yml entry for fpga using xilinx and altera

fpga:
  supported_vendors:
    - xilinx
    - altera
  xilinx:
    license:
      xilinxd_license_file:
        - 2100@<LICENSE.SERVER1>
    paths:
      root_path: /path_to/xilinx/<TOOL_VERSION>/
      root_name: vivado_rootdir
      additional_paths:
        installdir: Vivado/<TOOL_VERSION>
        xilinx_vivado: Vivado/<TOOL_VERSION>
      add_to_path:
        - Vivado/<TOOL_VERSION>/bin
        - Vivado_HLS/<TOOL_VERSION>/bin
   family:
     - kintex_ultrascale
   devices:
     - xcku040-ffva1156-2-e
     - xcku040-fbva676-1-c
   boards:
     - avnet_ku040
     - itpm_v1_1
   tools:
     - 2016.2
     - 2016.3
     - 2018.1
     - 2018.3
   default_lib:
     xil_defaultlib

  altera:
    license:
      lm_license_file:
        - 1800@<LICENSE.SERVER1>
    mode:
      supported_modes:
        - 0
        - 1
      env_name: quartus_64bit
      ld_library_path_0:
      ld_library_path_1:
    paths:
      root_path: /path_to/Altera/prime/<TOOL_VERSION>
      root_name: quartus_installdir
      additional_paths:
        quartus_rootdir: quartus
        qsys_rootdir: qsys/bin
      add_to_path:
        - quartus/bin
        - nios2eds/bin
        - quartus/sopc_builder/bin
        - hld/bin
    family:
      - arria_10
      - stratix_10
    family_mappings:
      arria_10:     'Arria 10'
      stratix_10:   'Stratix 10'
    devices:
      - 10AS066N2F40I2SGES
      - 1SX280LU3F50I3XG
    boards:
      - a10_soc_dev_kit
      - xpressgx_s10fh200g
    tools:
      - pro/17.0
      - pro/17.1
      - pro/18.0
      - pro/18.1
      - std/17.0
      - std/17.1
      - std/18.0
      - std/18.1

supported_vendors:

List of supported simulation vendors. Each entry in this list should have a corresponding entry under supported_vendors:.

<FPGA VENDOR>:

license:

A dictionary of key value pairs defining the license system environment variable name and values to assign when configuring the system environment. Values can be a single value, or a list of values. For xilinx:

example config.yml entry for fpga license

xilinx:
   license:
     xilinxd_license_file:
       - 2100@<LICENSE.SERVER1>
       - 2100@<LICENSE.SERVER2>

# or:

xilinx:
   license:
     xilinxd_license_file:
       2100@<LICENSE.SERVER1>

paths:

A dictionary of key value pairs defining path based system environment variables and values to assign when configuring the system environment. Supported keys:

root_path:

Path to <FPGA VENDOR> root installation path.

Note

Tag Substitution works here, where <TOOL_VERSION> is defined in the --settings YAML file.

root_name:

Name of system variable to create with reference to root_path:

add_to_path:

A list of sub-paths relative to root_path: to append to the system $PATH variable.

xilinx:
  paths:
      root_path: /path_to/xilinx/<TOOL_VERSION>/
      root_name: vivado_rootdir
      additional_paths:
        installdir: Vivado/<TOOL_VERSION>
        xilinx_vivado: Vivado/<TOOL_VERSION>
      add_to_path:
        - Vivado/<TOOL_VERSION>/bin
        - Vivado_HLS/<TOOL_VERSION>/bin

Will result in the following system environment variables to modified or created when tool_version: 2018.3 is set in the tool_version: file as an example:

setenv VIVADO_ROOTDIR '/path_to/xilinx/2018.3'
setenv INSTALLDIR '/path_to/xilinx/2018.3'
setenv XILINX_VIVADO '/path_to/xilinx/2018.3'
setenv PATH '/path_to/xilinx/2018.3/Vivado/2018.3/bin':${PATH}
setenv PATH '/path_to/xilinx/2018.3/Vivado_HLS/2018.3/bin':${PATH}

mode:

A dictionary of key value pairs defining execution mode of FPGA tool. Support keys with example values:

supported_modes:

A list of supported modes which are accepted by the system environment variable named by mode: under env_name:

env_name:

Name of the system environment variable which sets the tools mode of execution.

ld_library_path_<MODE_IN_SUPPORTED_MODES>:

Path to append to LD_LIBRARY_PATH which points to location of non-standard libraries required for the correct operation of the simulation tool when running in <MODE_IN_SUPPORTED_MODES> bit mode.

example config.yml entry for fpga mode

altera:
  mode:
    supported_modes:
      - 0
      - 1
    env_name: quartus_64bit
    ld_library_path_0:
    ld_library_path_1:

Will result in the following system environment variables to be modified or created, using tool_mode: 1 is set in the tool_mode: as an example:

setenv QUARTUS_64BIT 1

family:

A list of FPGA families supported by FPGAFlow. The names here should match the corresponding name as it appears in the FPGA vendor’s project file.

devices:

A list of FPGA devices supported by FPGAFlow. The names here should match the corresponding part number as it appears in the FPGA vendor’s project file.

boards:

A list of hardware platforms to which can be targeted by FPGAFlow.

Note

The values here will be used by Tag Substitution to populate the <NAME> and corresponding fields when processing the settings.yml YAML file (see Settings) and when determining the boards_layout: directory structure.

tools:

A list of FPGA tool versions supported by FPGAFlow.

Note

The values here will be used by Tag Substitution to populate <TOOL_VERSION> when processing the settings.yml YAML file (see Settings) and when setting up the system environment and paths required to allow FPGAFlow to execute the correct versions of FPGA vendor’s tools. This also determines then``build`` directory structure and which vendor_ip to use in the project.

default_lib:

The name of the default library used by the FPGA vendor.

simulation:

complete example config.yml entry for simulation using modelsim

simulation:
  supported_vendors:
    - modelsim
  modelsim:
    license:
      mgls_license_file:
        - 1717@<LICENSE.SERVER1>
        - 1717@<LICENSE.SERVER2>
    paths:
      root_path: /path_to/modelsim/<SIM_VERSION>/modeltech
      root_name: model_tech
      additional_paths:
        modelsim_installdir: bin
      add_to_path:
        - bin
    mode:
      supported_modes:
        - 32
        - 64
      env_name: mti_vco_mode
      ld_library_path_32:
        - /path_to/non-standard/lib32
      ld_library_path_64:
        - /pack_to/non-standard/lib64
  xilinx:
    sim_libs:
      - 'unisims_ver'
      - 'unimacro_ver'
      - 'unifast_ver'
      - 'secureip'
      - 'xpm'
      - 'unisim'
      - 'unimacro'
      - 'unifast'
      - 'simprims_ver'
    verilog_sim_libs: None
    vhdl_sim_libs: None
  altera:
    sim_libs: None
    verilog_sim_libs:
      - 'altera_ver'
      - 'lpm_ver'
      - 'sgate_ver'
      - 'altera_mf_ver'
      - 'altera_lnsim_ver'
      - 'fourteennm_ver'
      - 'fourteennm_ct1_ver'
      - 'cyclone10gx_ver'
      - 'cyclone10gx_hip_ver'
      - 'cyclone10gx_hssi_ver'
      - 'tennm_ct1_ver'
      - 'tennm_ver'
      - 'twentynm_ver'
      - 'twentynm_hip_ver'
      - 'twentynm_cssi_ver'
    vhdl_sim_libs:
      - 'altera'
      - 'lpm'
      - 'sgate'
      - 'altera_mf'
      - 'altera_lnsim'
      - 'fourteennm'
      - 'fourteennm_ct1'
      - 'cyclone10gx'
      - 'cyclone10gx_hip'
      - 'cyclone10gx_hssi'
      - 'tennm_ct1'
      - 'tennm'
      - 'twentynm'
      - 'twentynm_hip'
      - 'twentynm_hssi'

supported_vendors:

List of supported simulation vendors. Each entry in this list should have a corresponding entry under supported_vendors:.

<SIM TOOL VENDOR>:

supported_tools:

A list of supported versions. The items in this list are used to differentiate between installed versions of the tool on the host system. Therefore it is expected that each version listed is installed on the system using the value in the list to define the version of the tool. This allows multiple tools to be installed for device and legacy support.

license:

A dictionary of key value pairs defining the license system environment variable name and values to assign when configuring the system environment. Values can be a single value, or a list of values. For modelsim:

example config.yml entry for simulation license

modelsim:
   license:
     mgls_license_file:
       - 1717@<LICENSE.SERVER1>
       - 1717@<LICENSE.SERVER2>

# or:

modelsim:
   license:
     mgls_license_file:
       1717@<LICENSE.SERVER1>

paths:

A dictionary of key value pairs defining path based system environment variables and values to assign when configuring the system environment. Supported keys:

root_path:

Path to <SIM TOOL VENDOR> root installation path.

Note

Tag Substitution works here, where <SIM_VERSION> is defined in the --settings YAML file.

root_name:

Name of system variable to create with reference to root_path:

add_to_path:

A list of sub-paths relative to root_path: to append to the system $PATH variable.

example config.yml entry for simulation paths

modelsim:
  paths:
    root_path: /path_to/modelsim/<SIM_VERSION>/modeltech
    root_name: model_tech
    additional_paths:
      modelsim_installdir: bin
    add_to_path:
      - bin

Will result in the following system environment variables to modified or created when sim_version: 10.6e is set in the sim_version: file as an example:

setenv MODEL_TECH '/path_to/modelsim/10.6e/modeltech'
setenv MODELSIM_INSTALLDIR '/path_to/modelsim/10.6e/modeltech/bin'
setenv PATH '/path_to/modelsim/10.6e/modeltech/bin':${PATH}

mode:

A dictionary of key value pairs defining execution mode of simulation tool. Support keys with example values:

supported_modes:

A list of supported modes which are accepted by the system environment variable named by mode: under env_name:

env_name:

Name of the system environment variable which sets the tools mode of execution.

ld_library_path_<MODE_IN_SUPPORTED_MODES>:

Path to append to LD_LIBRARY_PATH which points to location of non-standard libraries required for the correct operation of the simulation tool when running in <MODE_IN_SUPPORTED_MODES> bit mode.

example config.yml entry for simulation mode

modelsim:
  mode:
    supported_modes:
      - 32
      - 64
    env_name: mti_vco_mode
    ld_library_path_32:
      - /path_to/non-standard/lib32
    ld_library_path_64:
      - /pack_to/non-standard/lib64

Will result in the following system environment variables to be modified or created, using sim_mode: 32 is set in the sim_mode: as an example:

setenv MTI_VCO_MODE 32
setenv LD_LIBRARY_PATH '/path_to/non-standard/lib32':${LD_LIBRARY_PATH}

xilinx:

sim_libs:

A list of standard verilog and VHDL library mappings for adding to simulations. These are precompiled once and should be available in the path defined by SIM_PRE_COMPILED_LIBS_PATH

verilog_sim_libs:

A list of standard verilog library mappings for adding to simulations. These are precompiled once and should be available in the path defined by SIM_PRE_COMPILED_LIBS_PATH

Note

For xilinx this can be unset, i.e. left empty: verilog_sim_libs:

vhdl_sim_libs:

A list of standard VHDL library mappings for adding to simulations. These are precompiled once and should be available in the path defined by SIM_PRE_COMPILED_LIBS_PATH

Note

For xilinx this can be unset, i.e. left empty: vhdl_sim_libs:

altera:

sim_libs:

A list of standard verilog and VHDL library mappings for adding to simulations. These are precompiled once and should be available in the path defined by SIM_PRE_COMPILED_LIBS_PATH

Note

For altera this must be unset, i.e. left empty: sim_libs:

verilog_sim_libs:

A list of standard verilog library mappings for adding to simulations. These are precompiled once and should be available in the path defined by SIM_PRE_COMPILED_LIBS_PATH

vhdl_sim_libs:

A list of standard VHDL library mappings for adding to simulations. These are precompiled once and should be available in the path defined by SIM_PRE_COMPILED_LIBS_PATH

vhdl:

example

vhdl:

documentation:

Configuration for documentation tools.

complete example of config.yml entry for contributors section

documentation:
  required:
    - doxy_version
    - dot_version
    - sphinx_version
  supported_languages:
    - vhdl
    - python
  doxygen:
    supported_tools:
      - 1.8.14
    paths:
      root_path: /path_to/doxygen-<DOXY_VERSION>/
      root_name: doxygen_installdir
      add_to_path:
        - bin
      internal_references:
        doxypypy_script: ../../../scripts/shell/doxypypy/py_filter
        doxy_template: templates/doxygen/<DOXY_VERSION>/templates/doxy_template.Doxyfile
        doxy_extra_style_sheets:
          - templates/doxygen/<DOXY_VERSION>/stylesheets/regtables.css
  dot:
    supported_tools:
      - 2.38.0
      - 2.40.1
    paths:
      root_path: /path_to/graphviz-<DOT_VERSION>/bin
      root_name: dot_path
  sphinx:
    supported_tools:
      - 1.8.2
    paths:
      internal_references:
        sphinx_conf_template: templates/sphinx/<SPHINX_VERSION>/templates/conf.py
        sphinx_make_template: templates/sphinx/<SPHINX_VERSION>/templates/Makefile

required:

This provides a list of required field from the Settings file required to execute the script correctly. The script expects each of the list items to be populated in the settings YAML file ready for Tag Substitution.

supported_languages:

A list of languages supported by the script for the auto-generation of documentation.

doxygen:

Configuration for doxygen tool used to auto-document VHDL files.

support_tools:

A list of supported versions.

Note

Versions of these tools should be available on the host system and one of these values must be included in the settings file (see Settings).

paths:

Configuration of the paths for the installation directories for doxygen.

root_path:

Path to doxygen root installation path.

Note

Tag Substitution works here, where <DOXY_VERSION> is defined in the --settings YAML file.

root_name:

Name of system variable to create with reference to root_path:

add_to_path:

A list of sub-paths relative to root_path: to append to the system $PATH variable.

internal_references:

A list of reference names and values for addition specific items to the doxygen configuration. This includes references to additional scripts, template files and a list of css files.

Note

internal_references: are relative to: $REPO_ROOT/tools/fpgaflow/scripts/python/

Tag Substitution works here, where <DOXY_VERSION> is defined in the --settings YAML file.

sphinx:

Configuration for sphinx tool used to auto-document python files.

Note

Sphinx and its dependencies is installed in the the python virtual environment and managed by pipenv

support_tools:

A list of supported versions.

Note

Versions of these tools should be available on the host system via pipenv virtual environment and one of these values must be included in the settings file (see Settings).

paths:

internal_references:

A list of reference names and values for addition specific items to the sphinx configuration. This includes references template files.

Note

internal_references: are relative to: $REPO_ROOT/tools/fpgaflow/scripts/python/

Tag Substitution works here, where <DOXY_VERSION> is defined in the --settings YAML file.

dot:

Configuration for graphviz tool used by doxygen for the generation of diagrams.

support_tools:

A list of supported versions.

Note

Versions of these tools should be available on the host system and one of these values must be included in the settings file (see Settings).

paths:

Configuration of the paths for the installation directories for graphviz.

root_path:

Path to graphviz root installation path

Note

Tag Substitution works here, where <DOT_VERSION> is defined in the --settings YAML file.

root_name:

Name of system variable to create with reference to root_path:

environment:

Configuration options for the user environment, to prevent user based locations and information being stored in source-code repositories.

complete example of config.yml entry for environment section

environment:
  required:
     - REPO_ROOT
     - PIPENV_SHELL
     - BITBUCKET_USERNAME
     - GIT_USERNAME
     - SVN_USERNAME
     - SIM_PRE_COMPILED_LIBS_PATH
  exclude_keywords:
     - 'build/'
     - 'synosys'
     - 'aldec'
     - 'cadence'
     - '.svn'
     - 'template'
     - '.Xil'
     - '.cache'
     - '.hw'
     - '.ip_user_files'
     - 'scripts'
     - 'ref_design'
     - 'bin'
     - 'docs'
     - 'settings'
     - 'constraints'
     - '.settings'
     - 'modelsim_'
     - 'vunit_output'

required:

This provides a list of required system environment variables required to successfully execute the script correctly. The script expects each of the list items to declared prior to the script executing and are validated when the script is executed.

REPO_ROOT

Sets the top-level root path where all projects/libraries will be checkout out to and processed from.

PIPENV_SHELL

Path to the executable for the shell pipenv should run.

BITBUCKET_USERNAME

The username used to access user controlled private bitbucket cloud hosted repositories.

GIT_USERNAME

The username used to access user controlled private git server hosted repositories (which may be bitbucket).

SVN_USERNAME

The username used to access user controlled private subversion repositories.

SIM_PRE_COMPILED_LIBS_PATH

The root path to precompiled Modelsim libraries.

exclude_keywords:

A list of exclude keywords to use throughout the flow. Files or directories containing any term in the list will automatically be excluded from the project build.