Electronic System Design Group

Modules

helpers/arguments.py

BSD © 2018-2019 Science and Technology Facilities Council & contributors

arguments.py is a helpers module provided to define and configure the argument passing and parsing for the main modules.

class arguments.Arguments

Creates arguments for passing files and configuration data to the script.

A Class which configures and retrieves Arguments for use by a python script. Dictionaries retrieved from YAML files are added as attributes to this class with no sub-processing. Information including the filename of each YAML file parsed is also added as an attribute.

See Arguments

config

dict – the parsed dictionary of the config.yml passed using to script --config

settings

dict – the parsed dictionary of the settings.yml passed to script using --settings

checkout_enabled

bool – set True using optional --checkout_enabled, otherwise False

dev_flag

bool – set True using optional --dev, otherwise False

open_gui

str – Valid values: 'fpga', 'sim'. Using optional --open_gui, otherwise None

clean

list of str – Valid values: 'all', 'fpga', 'ip', 'precompiled_sim', 'sim'. Using optiona clean, otherwise: None

helpers/customlogging.py

BSD © 2018-2019 Science and Technology Facilities Council & contributors

customlogging.py is a helpers module provided to define and configure consistent logging. The logging configuration is handled via ../logging.yml YAML file and uses colorlog for console output. A rolling system is used for outputting to files.

class customlogging.LogLevelsConsts

Logger level equivalent strings as constants, used to pass log level to helpers functions.

DEBUG

str – String matching DEBUG logger level.

INFO

str – String matching INFO logger level.

WARNING

str – String matching WARNING logger level.

CRITICAL

str – String matching CRITICAL logger level.

ERROR

str – String matching ERROR logger level.

customlogging.config_logger(name, class_name=None)

Allows a logger to be set up and/or configured in all modules/module classes

Parameters:

• name (str) – Name of the logger.
• class_name (str, optional) – Name of the class to which the logger is associated. Default value: None

Returns:

A configured logger object.

Return type:

logging (obj)

customlogging.constant(f)

setters and getters for constants used throughout

Prevents setting of existing objects. Raises a TypeError.

Returns:property Raises:TypeError – On setter.

customlogging.errorexit(logr)

Inserts a exit on error message in the logger output and performs a sys.exit(-1)

Parameters:logr (obj) – A logger object to pass the exit on error message to. Returns:None

customlogging.mand_missing(obj, field)

Inserts a mandatory field missing error message in the logger output and calls errorexit()

Parameters:

• logr (obj) – A logger object to pass the error message to.
• field (str) – field to report in the error message.

Returns:

None

customlogging.path_missing(obj, name, path)

Inserts a path missing error message in the logger output and calls errorexit()

Parameters:

• logr (obj) – A logger object to pass the error message to.
• name (str) – Name of processing element which caused the error message.
• path (str) – Missing Path which caused the error message.

Returns:

None

customlogging.sect_break(logr, level=<property object>)

Inserts a section break in the logger output.

Parameters:

• logr (obj) – A logger object to pass the section break to.
• level (attr of LogLevelsConsts obj, optional) – Logger level of the section break. Default value: LogLevelsConsts.INFO

Returns:

None

customlogging.setup_logging(logr_settings='../logging.yml', default_level=20)

Setup logging configuration from a YAML file

Parameters:

• logr_settings (str, optional) – Defines the relative location of the logging configuration file,
• the root module. Default value (from) – logging.yml
• default_level (logging attr, optional) – Sets the default logging level. Default value: logging.INFO

Returns:

None

docflow.py

BSD © 2018-2019 Science and Technology Facilities Council & contributors

docflow.py is a module provided to setup and manage the auto-documentation generation using doxygen and sphinx. Project specific values are extracted from the corresponding settings.yml YAML file and the projects structure is determined from the config.yml YAML file, each passed to the module via arguments (see Arguments).

Todo

• Consider Moving doxygen and sphinx template values to config.yml YAML file for improved flexibility.
• Determine the name to assign to: breathe_project_name.

class docflow.ProjectDoc(**kwargs)

An object describing the configuration and settings for the projects documentation generation.

Inherits: project.RepoFlow (obj): Inherited RepoFlow object. See projectmanager.RepoFlow.

Keyword Arguments:  **include_dependencies (bool, optional) – Process and include project dependencies in the generated documentation. Default value: False

generate_automodule(**kwargs)

Generates sphinx reStructuredText auto-module directive

Generates the auto-module directive, in the form:

.. automodule:: module
   :members:

Keyword Arguments:  

• **module (str, optional) – The name of the module to auto-module. Default value: False
• **indent_size (int, optional) – Number of spaces in indent. Default value: 3

Returns:

A line-by-line list of the complete sphinx reStructuredText auto-module directive

Return type:

list of str

generate_doxyfile(**kwargs)

Generate the doxygen .doxyfile from project derived values and template.

Warning

EXAMPLE_PATH is set with fixed locations and should be modified to be defined in project settings.yml YAML file.

Keyword Arguments:  

• **repo_root (str, optional) – Full resolved path defined by $REPO_ROOT Default value: ''
• **name (str, optional) – The name of the .doxyfile to generate. Default value: ''
• **doxy_input_paths (list of str, optional) – List of paths to include as input sources for the generation of documentation. Default value: list()
• **doxy_source_path (str, optional) – Path to doxygen source directory which includes common documentation files (*.md) to include in generated documentation. Default value: ''
• **doxy_build_path (str, optional) – Full path where to build documentation. Default value: ''
• **doxy_mainpage_name (str, optional) – Name of the mainpage to use as index.html in generated HTML documentation. Default value: 'README.md'
• **doxy_template (str, optional) – Full path of template file to use for generic .doxyfile configuration options. Default value: ''
• **doxy_extra_style_sheets (str, optional) – Extra CSS style sheets used in the generation of HTML pages. Default value: ''
• **image_path (str, optional) – Full path of images to include in generated documentation. Default value: False
• **restricted_src (bool, optional) – If set True stops source code from being published in the generated documentation. Default value: True
• **project_title (str, optional) – The project title used in the generated documentation. Default value: ''
• **project_version (str, optional) – The project version number, in the form: YYYY.NN used in the generated documentation. Default value: ''
• **project_logo (bool, optional) – Full path to the logo to use in the generated documentation. Default value: False
• **project_language (str, optional) – The language of the project being generated, used to optimise the output of the generated documentation. Default value: ''
• **doxypypy_script (str, optional) – Full path of doxypypy.py for parsing python code in doxygen. sphinx is preferred over this option. Default value: ''
• **dot_path (str, optional) – Full path to dot for using graphviz to generate diagrams in generated documentation. Default value: ''

Returns:

tuple containing:

• str: Full path of the generated doxyfile
• str: Full path of the generated xml to be used by breathe to bridge doxygen and sphinx generated documentation.

or:

int: -1 on failure.

Return type:

tuple

generate_doxymainpage(**kwargs)

Generates the doxygen Main Page to act as link between doxygen and sphinx documentation

Parses generated_html_path looking for HTML files where the filename ends with htmlpagefilter and added the file to the generated mainpage, along with the pages title extracted from the HTML page.

Keyword Arguments:  

• **doxy_mainpage_dict (dict, optional) – Dictionary of mainpage settings defining the structure and configuration of the mainpage to generate. Default value: dict()
• **doxy_source_path (str, optional) – Full path to the doxygen source path. Default value: None
• **generated_html_path (str, optional) – Full path to the generated doxygen generated HTML. Default value: None
• **doxy_mainpage_title (str, optional) – Tile of the generated mainpage which is referenced in the generated documentation. Default value: 'Doxygen Index
• **htmlpagefilter (str, optional) – The suffix of the HTML pages to add to the generated mainpage (excluding the file extension). Default value: 'page

Returns:

Name of the generated main page

Return type:

str

generate_include(**kwargs)

Generates sphinx reStructuredText include directive

Generates the include directive, in the form:

.. include:: <include_ref>

Keyword Arguments:  

• **include_ref (str, optional) – The name of the reference to include. Default value: ''
• **indent_size (int, optional) – Number of spaces in indent. Default value: 3

Returns:

A line-by-line list of the complete sphinx reStructuredText include directive

Return type:

list of str

generate_index_heading(**kwargs)

Generates reStructuredText headings matching sphinx recommended formatting.

see: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

Keyword Arguments:  

• **heading_text (str, optional) – The heading string. Default value: False
• **heading_char (str, optional) –

  A single character representing the reStructuredText heading level. Default value: #

  Valid values: #, *, =, -, ^, "

Returns:

A line-by-line list of the complete reStructuredText heading

Return type:

list of str

generate_indices_and_tables(**kwargs)

Generates sphinx reStructuredText Indices and Tables List

Generates the TOC Tree, in the form:

===================
Indices and Tables:
===================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Keyword Arguments:  

• **indent_size (int, optional) – Number of spaces in indent. Default value: 3
• **language (str, optional) – Language to determine if module index is included. Included if set to: python. Excluded if set to anything else. Default value: python

Returns:

A line-by-line list of the complete sphinx reStructuredText Indices and Tables

Return type:

list of str

generate_sphinx_index_file(**kwargs)

Generates sphinx reStructuredText Index File

Searches for .rst and .md files in the source_path and adds them to the generated index file.

If a file matching the index_name is found it is not added to the generated index file.

If a html directory is found, using the /html/ string, it is added once to the generated index file.

Keyword Arguments:  

• **source_code_path (str, optional) – Top-Level Path of Source-Code Location. Default value: ''
• **source_path (str, optional) – Documentation source path to parse for valid files to add to index. Default value: ''
• **static_path (str, optional) – The name of the sphinx Static Path. Default value: _static
• **index_name (str, optional) – The name of the index file to generate. Default value: index.rst
• **readme_name (str, optional) – The name of a valid README file. Could have .rst or .md file extension. Default value: README
• **src_code_path_list (list of str, optional) – List of source code paths to parse to add to Sphinx documentation. These paths are relative to source_path. Default value: list()
• **max_depth (int, optional) – The maximum depth of the toctree. Default value: 2
• **indent_size (int, optional) – Number of spaces in indent. Default value: 3
• **language (str, optional) – Language to determine if module index is included. Included if set to: python. Excluded if set to anything else. Default value: python
• **header (str, optional) – Common header file to use in generated documentation. Default value: '_static/esdg_header.rst'

Returns:

None

generate_sphinx_modules(**kwargs)

Generates sphinx reStructuredText Module File

Searches for .py files in locations found in src_code_path_list, then passes that list to: docflow.ProjectDoc.generate_automodule()

Keyword Arguments:  

• **source_code_path (str, optional) – Top-Level Path of Source-Code Location. Default value: ''
• **source_path (str, optional) – Documentation source path where the <filename>.rst should be generated. Default value: ''
• **filename (str, optional) – The name of module file to generate. Default value: modules.rst
• **src_code_path_list (list of str, optional) – List of source code paths to parse to add to Sphinx documentation. Default value: list()
• **indent_size (int, optional) – Number of spaces in indent. Default value: 3
• **header (str, optional) – Header file to reference at the top of the generated file. Default value: _static/esdg_header.rst

Returns:

None

generate_toctree(**kwargs)

Generates sphinx reStructuredText Table-of-Contents Tree

Generates the TOC Tree, in the form:

===================
Index:
===================

..toctree::
  :maxdepth: 2

  srcs[0]
  srcs[1]
  srcs[n]
  Doxygen Index <_static/html/index.html#://>

Keyword Arguments:  

• **max_depth (int, optional) – The maximum depth of the toctree. Default value: 2
• **indent_size (int, optional) – Number of spaces in indent. Default value: 3
• **srcs (list of str, optional) – List of srcs to include in the toctree. Default value: list()
• **reference_static_html (bool, optional) – Allows the addition of a link to page external to sphinx. Default value: False
• **static_index_text (str, optional) – The human readable string for the reference_static_html link. Default value: Doxygen Index
• **static_index_link (str, optional) – The location of the reference_static_html link, relative to the sphinx top-level source path. Default value: _static/html/index.html

Returns:

A line-by-line list of the complete sphinx reStructuredText Table-of-Contents Tree

Return type:

list of str

load_settings_from_yaml(**kwargs)

Loads a settings.yml YAML file and returns the ‘documentation’ key.

Keyword Arguments:  

• **settings_root (str, optional) – Path to the project’s root settings directory. Default value: ''
• **settings_filename (str, optional) – Name of settings file to use. Default value: default_settings.yml

Returns:

None

preprocess_sphinxconf(**kwargs)

Preprocessing for the sphinx conf.py File based on the current settings

Checks locations of directories and files exist and copies relevant files to documentation source directory prior to generating the configuration file.

Keyword Arguments:  

• **source_path (str, optional) – Documentation source path. Default value: ''
• **src_code_path (str, optional) – Top-level path of source code to add to sphinx documentation. This path will searched recursively, directories name: template will be added to a list to be used to add template files to the configuration. Default value: ''
• **sphinx_source_path (str, optional) – The path of sphinx source code to add in the generated documentation. Default value: ''
• **sphinx_build_path (str, optional) – The path where sphinx will generate the documentation. Default value: ''
• **project_name (str, optional) – The project name. Default value: ''
• **project_version (str, optional) – The projects documentation version. Default value: ''
• **project_release (str, optional) – The project release. Default value: ''
• **project_author (str, optional) – The project documentation’s author. Default value: ''
• **project_org (str, optional) – The project’s organisation. Default value: ''
• **project_logo (str, optional) – The name of the project logo to use in the project’s documentation. Default value: False
• **release_uri (str, optional) – The URL for releases to determine the release version. Default value: False
• **issue_uri (str, optional) – The URL for releases to determine the issue reference. Default value: False
• **releases_document_name (str or list of str, optional) – The name of the Changelog used by releases. Default value: False
• **style_sheets (str, optional) – Additional Style-Sheets to use when generating HTML documentation. Default value: False
• **breathe_project (str, optional) – Breathe project to use when bridging doxygen generated documentation with sphinx. Default value: False
• **toc_depth (int, optional) – The depth of the toctree used in the generated documentation. Default value: 4
• **image_path (str, optional) – Path to directory of images to add to the generated sphinx documentation. Files in this directory will be copied to the static_path used by sphinx. Default value: False
• **source_path – Path to directory of source files to add to the generated sphinx documentation. Files in this directory will be copied to the static_path used by sphinx. Default value: False
• **static_path (str, optional) – Path to directory where source files will be copied for the generation of sphinx documentation. Default value: '_static'
• **doxygen_html_path (str, optional) – Path where doxygen has generated HTML documentation prior to generating the sphinx documentation. These pages will be copied to a ‘html’ directory in the sphinx static_path for inclusion in the generated sphinx documentation. Default value: None'
• **sphinx_conf_template (str, optional) – Relative Path, from docflow.py, to the sphinx configuration file template to append to the generated configuration file. Default value: ''
• **sphinx_make_template (str, optional) – Relative Path, from docflow.py, to the sphinx Makefile file template to append to the generated configuration file. Default value: ''
• **language (str, optional) – Language to determine if module index is included. Included if set to: python. Excluded if set to anything else. Default value: python
• **header (str, optional) – Header file to reference at the top of the generated file. Default value: _static/esdg_header.rst

Returns:

None

process_sphinx_conf_file(**kwargs)

Generates sphinx conf.py File based on the current settings

Completes options from passed values and completes the remaining file by copying the contents from a template file.

Keyword Arguments:  

• **source_path (str, optional) – Documentation source path. Default value: ''
• **src_code_path_list (list of str, optional) – List of source code paths to parse to add to sphinx documentation. Default value: list()
• **conf_name (str, optional) – The name of sphinx configuration file to generate. Default value: conf.py
• **project_name (str, optional) – The project name. Default value: ''
• **project_version (str, optional) – The projects documentation version. Default value: ''
• **project_release (str, optional) – The project release. Default value: ''
• **project_author (str, optional) – The project documentation’s author. Default value: ''
• **project_org (str, optional) – The project’s organisation. Default value: ''
• **project_logo (str, optional) – The name of the project logo to use in the project’s documentation. Default value: False
• **release_uri (str, optional) – The URL for releases to determine the release version. Default value: False
• **issue_uri (str, optional) – The URL for releases to determine the issue reference. Default value: False
• **releases_document_name (str or list of str, optional) – The name of the Changelog used by releases. Default value: False
• **style_sheets (str, optional) – Additional Style-Sheets to use when generating HTML documentation. Default value: False
• **template_file (str, optional) – The name of sphinx configuration template file. file extension. Default value: ''
• **breathe_project (str, optional) – Breathe project to use when bridging doxygen generated documentation with sphinx. Default value: False
• **toc_depth (int, optional) – The depth of the toctree used in the generated documentation. Default value: 4
• **indent_size (int, optional) – Number of spaces in indent. Default value: 4

Returns:

None

process_sphinx_makefile(**kwargs)

Processes a sphinx Makefile from a supplied template.

Keyword Arguments:  

• **build_path (str, optional) – absolute path of the sphinx build location. Default value: ''
• **make_file_template (list of str) – line-by-line list of Makefile template contents. Default value: ''
• **makefile (str, optional) – name of the makefile. Default value: Makefile

Returns:

None

run_doxygen(**kwargs)

doxygen runner

Keyword Arguments:  

• **doxyfile (str, optional) – The full path of doxygen .doxyfile used to generate documentation. Default value: ''
• **doxy_bin (str, optional) – The name of the bin to use to execute doxygen Default value: 'doxygen'

Returns:

None

run_sphinx(**kwargs)

sphinx runner

Keyword Arguments:  

• **sphinx_source_path (str, optional) – The path of sphinx source to generate documentation. Default value: ''
• **sphinx_build_path (str, optional) – The path where sphinx will generate the documentation. Default value: ''
• **builder (str, optional) – builder to invoke. Valid values: html. Default value: html
• **use_make (bool ,optional) – Use the Makefile to generate documentation instead of executing directly. Default value: False

Returns:

0 on Success

Return type:

int

set_doxy_paths(**kwargs)

Sets the doxygen source and build paths.

Note

The keyword argument doxy_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).

Keyword Arguments:  

• **doc_root (str, optional) – Path to projects root docs directory. Default value: ''
• **doxy_version (str, optional) – version number of doxygen - determines the build path. Default value: ''
• **clean (bool, optional) – if set to True, removes all existing files from the build directory. Default value: False

Returns:

tuple containing:

• str: Full path of doxygen source location.
• str: Full path of doxygen build location.

Return type:

tuple

set_image_path(**kwargs)

Sets the full-path to the images directory to use in generated documentation.

Keyword Arguments:  

• **doc_root (str, optional) – Path to projects root docs directory. Default value: ''
• **image_path (str, optional) – Relative Path, from doc_root, to the project’s image directory. Default value: ''

Returns:

the full-path to the images directory if found on file-system.

or:

bool: False if not found.

Return type:

str

set_logo(**kwargs)

Sets the full-path to the logo to use in generated documentation.

Keyword Arguments:  

• **doc_root (str, optional) – Path to projects root docs directory. Default value: ''
• **logo_path (str, optional) – Relative Path, from doc_root, to the project’s logo directory. Default value: ''
• **logo_name (str, optional) – Name of logo file to use. Default value: ''

Returns:

the full-path to the logo if found on file-system.

or:

bool: False if not found.

Return type:

str

set_source_path(**kwargs)

Sets the full-path to the source directory to use in generated documentation.

Keyword Arguments:  

• **doc_root (str, optional) – Path to projects root docs directory. Default value: ''
• **source_path (str, optional) – Relative Path, from doc_root, to the project’s source_path directory. Default value: ''

Returns:

the full-path to the source directory if found on file-system

or:

bool: False if not found.

Return type:

str

set_sphinx_paths(**kwargs)

Sets the sphinx source, build and static paths.

Note

The keyword argument sphinx_version should be available on the host system and this value must be included in the documentation: sphinx: support_tools: within the configuration file (see Configuration).

Keyword Arguments:  

• **doc_root (str, optional) – Path to projects root docs directory. Default value: ''
• **sphinx_version (str, optional) – version number of sphinx to use - determines the build path. Default value: ''
• **sphinx_static (str, optional) – sphinx static directory name. Where existing source files are copied to in order to be included in the generated documentation. Default value: '_static'
• **clean (bool, optional) – if set to True, removes all existing files from the build directory. Default value: False

Returns:

tuple containing:

• str: Full path of sphinx source location.
• str: Full path of sphinx build location.
• str: Full path of sphinx static location.

Return type:

tuple

source_code_publication_msg(**kwargs)

Sends a Critical Warning to the Console if Source Code Will be Published in the Documentation

Keyword Arguments:  

• **name (str, optional) – Name of project which is publishing source code in the generated documentation. Default value: ''
• **restricted_flag (bool, optional) – Flag to determine if source-code is being published in the generated documentation. Default value: True

Returns:

None

environmentsetup.py

BSD © 2018-2019 Science and Technology Facilities Council & contributors

environmentsetup.py is a module provided to configure the host environment for each project, setting up environment variables which persist during the execution of the script which defined paths and license references for each tool using the the flow. Specific values are extracted from the corresponding settings.yml YAML file and the tool installation structure is determined from the config.yml YAML file, each passed to the module via arguments (see Arguments).

Todo

• Add breathe configuration to ProjectEnvironment.configure_documentation_tool()

class environmentsetup.ProjectEnvironment(**kwargs)

An object containing attributes defining the environment variables required for processing a project.

Specific values are extracted from the corresponding settings.yml YAML file and the tool installation structure is determined from the config.yml YAML file, each passed to the module via arguments (see Arguments).

add_environment_variable(**kwargs)

Adds a system environment variable for the running script.

If the system environment variable already exists this will add the new value as the first value and append the old value using ':' as a delimiter.

Keyword Arguments:  

• **name (str) – Name of the system environment variable to create/append. Default value: None
• **value (str) – Value to assign to the system environment variable. Default value: None
• **overwrite (bool, optional) – Default value: False

Returns:

None

check_if_supported(**kwargs)

Checks if value in settings.yml is supported in config.yml

Checks value against a list of supported_values and exits with error if not found with reference to the full-path of the failing settings.yml YAML used.

Keyword Arguments:  

• **value (str) – Default value: None
• **supported_values (list of str) – Default value: list()
• **settings_fileref (str) – Full path, including filename, of settings file used. Default value: None

Returns:

None

configure_documentation_tool()

Configures and validates the system environment variables for running documentation tools.

Supports the following automatic documentation generation tools:

• doxygen
• breathe
• sphinx

Returns:None

configure_fpga_vendor_tool()

Configures and validates the system environment variables for running the FPGA vendor tool.

Returns:None

configure_license(**kwargs)

Configures license environment variables.

Gets configuration from config.yml YAML file (see Configuration).

Keyword Arguments:  **license_settings (dict) – The license settings from configuration dictionary. Default value: None Returns:None

configure_mode(**kwargs)

Configure tool execution mode.

Provides support for running the tools in 32 or 64 bit modes as well as referencing libraries not supported by the host operating system distribution.

Keyword Arguments:  

• **mode (str) – Default value: None
• **mode_config (dict) – Dictionary defining the mode of running the tool being configured. Default value: None
• **mode_type (str) – Default value: sim

Returns:

None

configure_modelsim_environment()

Configures and validates the system environment variables for running modelsim

Returns:None

configure_paths(**kwargs)

Configures system environment paths required for tool execution.

Keyword Arguments:  **paths_config (dict) – Dictionary defining the paths and values for the tool being configured. Default value: None Returns:None

get_envvar(**kwargs)

Method to get system environment variable using os.environ

If the system environment variable does not exist customlogging.errorexit() is called.

Keyword Arguments:  **variable_name (str) – Name of the system environment variable to get from system. Default value: None Returns:The retrieved system environment variable. Return type:(str)

set_args_from_dict(**kwargs)

Sets arguments from a dictionary.

Creates attributes from a dictionary based on key or key[subkey], from the item or items in list found in dictionary[key] or dictionary[key][subkey]. If using: from_envvars=True the attribute will be sourced from the system environment variable.

Keyword Arguments:  

• **key (str) – Name of the dictionary key to process. Default value: None
• **subkey (str, optional) – Name of the dictionary sub-key to process. Default value: None
• **dictionary (dict) – Dictionary to extract [key] or [key][subkey] value from. Default value: dict()
• **from_envvars (bool, optional) – If True gets the value from the corresponding system environment variable. Default value: False

Returns:

None

set_attr_from_path(**kwargs)

Sets an attribute: name containing a full-path, without file name.

Keyword Arguments:  

• **name (str) – Name of the attribute to set. Default value: None
• **path (str) – Full path, excluding any filenames, of reference to attribute. Default value: `None
• **create_if_missing (bool, optional) – If True Creates the directory structure on the file-system, using os.makedirs(). If the directory structure does not exist on the file-system. Default value: False
• **force_attr (bool, optional) – If True Creates the attribute even if the directory structure does not exist on the file-system. Default value: False

Returns:

None

set_envattr(**kwargs)

Checks to see if the attribute already exists before setting.

Keyword Arguments:  **env (str) – Name of the system environment variable to check. Default value: None Returns:None

set_path_environ(**kwargs)

Sets system environment $path variable.

This performs the equivalent of running:

setenv env path

If $env already exists it will append to the existing value:

setenv env path:${env}

Keyword Arguments:  

• **env (str) – Name of the system environment variable name. Default value: None
• **path (str) – System environment variable value. Default value: None
• **delimiter (str, optional) – Delimiter to use between multiple environment variable values Default value: ':'
• **overwrite (bool, optional) – If True overwrite existing value instead of appending. Default value: False

Returns:

None

setattr_from_envvar(**kwargs)

Sets attribute from system environment variable.

Gets the value from corresponding $envs` and sets attribute matching the system environment variable name with the value retrieved.

Keyword Arguments:  **envs (str) – Name of the system environment variable to process. Default value: None Returns:None

fpgavendor_iface.py

BSD © 2018-2019 Science and Technology Facilities Council & contributors

fpgavendor_iface.py is a module to handle the generation of FPGA projects and interfacing with vunit_iface, to include the compilation of FPGA vendor simulation modules based on tool version and FPGA device family.

class fpgavendor_iface.FpgaProject(**kwargs)

add_ip(**kwargs)

Keyword Arguments:  

• **vunit_obj (obj) – A vunit_iface.VunitProject object. Default value: self.vu
• **project_file (str) – Absolute path to project file.
• **rebuild_project (bool, optional) – If True rebuild existing project. Default value: False

Returns:

None

backup_project(**kwargs)

Backup project using timestamp.

Appends time stamp to the project directory in the form: _%Y%m%d%H%M%S and uses shutil.copytree() to backup the project. Then cleans the original directory (using shutil.rmtree() and remaking the location using: os.makedirs())

Keyword Arguments:  **project_path (str) – Absolute path to project root. Returns:None

create_quartus_project(**kwargs)

Creates a quartus project using supplied settings.

Copy constraints from .qsf file line-by-line directly, ignoring blank and commented lines, into project file replacing any instance of $REPO_PATH with $env(REPO_ROOT). Leaves the original constraints file untouched, which should have the same effect as having sourced the constraints file.

Keyword Arguments:  

• **project_name (str, optional) – Name of project file to generate. Default value: 'project'
• **build_path (str) – Absolute path to build location for generated project
• **target_language (str, optional) – Target default language for the generated project. Default value: 'VHDL_2008'
• **top_level_entity (str) – Top-level HDL entity name.
• **hdl_files (list of tuples) – containing HDL libraries and absolute path to HDL file.
• **tb_hdl_file (list of tuples) – containing HDL libraries and absolute path to Test Bench HDL file.
• **ip_files (list of str) – List of absolute paths fof IP files to add to project.
• **constraint_files (list of str) – List of absolute paths of constraints to add to project.

Returns:

None

create_vivado_project(**kwargs)

Creates a vivado project using supplied settings.

Keyword Arguments:  

• **project_name (str, optional) – Name of project file to generate. Default value: 'project'
• **build_path (str) – Absolute path to build location for generated project
• **target_language (str, optional) – Target default language for the generated project. Default value: 'VHDL'
• **top_level_entity (str) – Top-level HDL entity name.
• **hdl_files_dict (dict) – Dictionary of HDL libraries (keys) and list of absolute HDL files.
• **ip_files (list of str) – List of absolute paths fof IP files to add to project.
• **constraint_files (list of str) – List of absolute paths of constraints to add to project.

Returns:

None

get_project_file()

Gets the absolute path of the project file.

Returns:Absolute path of project file. None if not found. Return type:str

fpgavendor_iface.generate_timestamp()

Generates a Unix 32 Bit Time Stamp from the systems time as an integer value.

Returns:Timestamp as an integer for conversion to a VHDL unsigned std_logic_vector(31 downto 0). Return type:str

fpgavendor_iface.resolve_tool_version(**kwargs)

Resolves the tool_version based on vendor

Keyword Arguments:  

• tool_version (str) – Version of tool to resolve.
• vendor (str, optional) – Vendor name. Valid values: 'altera', 'xilinx'. Default 'xilinx'

Returns:

The resolved tool_version when successful, otherwise False

Return type:

str

fpgavendor_iface.run_ip_generate(**kwargs)

Executes the Quartus qsys-generate

Executes the qsys-generate to generate Quartus IP.

Keyword Arguments:  

• **exe (str, optional) – Executable to run. Default value: 'qsys-generate'
• **ip_file (str) – Absolute path to IP file to generate.
• **output_path (str) – Absolute path where output files are generated.
• **synth (bool, optional) – generate for synthesis if True otherwise generate for simulation. Default value: True
• **synth_language (str, optional) – HDL language used to generate synthesis files. Valid values: 'VHDL' or 'VERILOG'. Default value: 'VERILOG'
• **sim_language (str, optional) – HDL language used to generate simulation files. Valid values: 'VHDL' or 'VERILOG'. Default value: 'VHDL'
• **family (str, optional) – FPGA Family. Default value: False
• **device (str, optional) – FPGA Device. Default value: False
• **clean (bool, optional) – Cleans IP Path Prior to Generating IP. Default value: False

Returns:

None

fpgavendor_iface.run_ip_setup_simulation(**kwargs)

Executes the Quartus run-ip-setup-simulation

Executes the run-ip-setup-simulation to gather simulation setup commands for all Vendor IP libraries used in current design.

Keyword Arguments:  

• **exe (str, optional) – Executable to run. Default value: 'ip-setup-simulation'
• **project_file (str) – Absolute path to project file to process.
• **output_path (str) – Absolute path where output files are generated.

Returns:

None

fpgavendor_iface.run_quartus_sh(**kwargs)

Runs quartus_sh to execute compilation for standard HDL simulation libraries.

Keyword Arguments:  

• **quartus_bin (str, optional) – Name of executable to run quartus. Default value: 'quartus_sh'
• **script_mode (bool, optional) – Run quartus_sh in script mode. Default value: False
• ** –
• **tool (str) – Name of the tool to run. Should be derived from: simulator_class = SIMULATOR_FACTORY.select_simulator() simname = simulator_class.name
• **language (str, optional) – Valid options: 'verilog' or 'vhdl'. Default value: 'vhdl'
• **modelsim_path (str) – Absolute path to the version of Modelsim to use to compile standard HDL libraries.
• **output_path (str) – Absolute path where to compile standard HDL libraries.
• **tcl_file_name (str) – Absolute path to the tcl script used by vivado
• **tcl_args (str, optional) – Additional positional arguments needed to execute tcl_file_name Default value: None
• **gui (bool, optional) – Runs Quartus in GUI Mode. Default value: False
• **project_file (str) – Absolute path to project file.

Returns:

None

fpgavendor_iface.run_vivado(**kwargs)

Runs vivado in specified mode.

When running in 'gui' mode, the tcl_file keyword argument is the project file to open.

Note

The shell=True in check_call is important in windows where vivado is just a bat file.

Keyword Arguments:  

• **vivado_bin (str, optional) – Name of executable to run vivado. Default value: 'vivado'
• **mode (str, optional) – Name of the mode to run. Valid values: 'batch', 'tcl' or 'gui'. Default value: 'batch'
• **tcl_file_name (str) – Absolute path to the tcl script used by vivado when running in 'tcl' mode, and the project file to open when running in 'gui' mode.
• **tcl_args (str, optional) – Additional positional arguments needed to execute tcl_file_name Default value: None

Returns:

None

helpers/funcs.py

BSD © 2018-2019 Science and Technology Facilities Council & contributors

funcs.py is a helpers module to provide functions commonly used throughout.

class funcs.Const

Allows attributes to be treated like constants where they can be set one time only.

Raises:ConstError if attribute already exists.

exception ConstError

funcs.clean_path(**kwargs)

Cleans given path, by removing and recreating empty path.

Keyword Arguments:  **path (str) – Absolute path to clean. Returns:None

funcs.copy_files_from_dir(src_path, dst_path)

Copy files from source directory to destination directory.

Uses shutil.copy2 to copy files recursively from one directory to another directory.

Parameters:

• src_path (str) – Full-path of the source directory.
• dst_path (str) – Full-path of the destination directory.

Returns:

None

funcs.get_kwarg(arg, kwargs, default)

Finds arg in kwargs and returns the value. If arg is not found return the provided default value.

Parameters:

• arg (str) – Name of argument to extract
• kwargs (dict) – Dictionary of keys, values to find and return arg value from.
• default – The value to assign if arg is not a key in kwargs

Returns:

default

funcs.readfile_as_list(full_path)

Takes a full-path to file and returns the contents as a list.

Parameters:full_path (str) – Full path, including file name, of the file to read from. Returns:Line-by-line list of file contents. Return type:(list)

funcs.replace_tag_with_attr_value(obj, tag)

Replaces a <TAG> with a corresponding attribute value.

Looks for <TAG> (enclosed in <>) in tag string passed to the function, and if found returns a string with the tag replaced by the value as obj.<TAG> attribute.

If the attribute exists but is not populated with a value an “empty” string '' is returned. This allows all <TAG> options in the layout configuration to be optional.

Parameters:

• obj (obj) – Object to assign replaced <TAG> as attribute.
• tag (str) – string to check for sub-strings enclosed in <>.

Returns:

An empty string if corresponding attribute for the <TAG> is not found; or the corresponding attribute if found; or the original <TAG> if anything else.

Return type:

(str)

funcs.set_kwargs(obj, kwargs)

Sets attributes to specified existing object.

Parameters:

• obj (str) – name of the object to assign attribute(s).
• kwargs (dict) – dictionary of key, values, where key is the attribute and value is the vaule to assign

Returns:

None

funcs.strip_tag(tag)

Removes the < and > from tag and returns the lowercase string enclosed.

Parameters:tag (str) – UPPERCASE tag enclosed in < and > Returns:lowercase TAG with < and > stripped. Return type:(str)

funcs.validate_file(f, touch=False)

Checks the given file exists on the file-system. If touch is True, create the file if it is missing.

Parameters:

• f (str) – Full path, including file name, of the file to validate.
• touch (bool, optional) – If set creates an empty file if not found on the file-system. Default value: False

Returns:

True on success, False otherwise.

funcs.writefile_as_list(full_path, contents)

Takes a list and writes contents line-by-line to file.

Parameters:

• full_path (str) – Full path, including file name, of the file to write.
• contents (list) – Line-by-line list of contents to write.

Returns:

None

projectmanager.py

BSD © 2018-2019 Science and Technology Facilities Council & contributors

projectmanager.py is a module provided to setup, validate and execute source-code retrieval from externally hosted repositories. Project specific values are extracted from the corresponding settings.yml YAML file and the projects structure is determined from the config.yml YAML file, each passed to the module via arguments (see Arguments).

class projectmanager.ProjectDependency(repo_root, name, category, url, local_path, remote_path, remote_rev, required_vhdl_libs=[], vunit_default=False, top_level=False, board_name=None, board_settings=None, family=None, device=None, **kwargs)

Processes project dependencies.

Takes a dictionary and converts keys to attributes before parsing configuration to construct all attributes required to describe a Dependency Object

Parameters:

• repo_root (str) – The resolved $REPO_ROOT system environment variable. Required by: projectmanager.ProjectDependency.layout_to_dir and projectmanager.ProjectDependency.prune_path_list
• name (str) – Name of dependency
• category (str) – The dependency’s category
• url (str) – Root URL to remote repository location for the dependency
• local_path (str) – Local path of the working copy for the dependency
• remote_path (str) – Remote path, from the url for the dependency
• remote_rev (str) – Specific repository revision for the dependency
• required_vhdl_libs (list of str, optional) – List of required HDL libraries required by the dependency. Default value: list()
• vunit_default (bool, optional) – VUnit dependency flag. Default value: False
• top_level (bool, optional) – Project Top-level dependency flag. Default value: False
• board (str, optional) – Target board for dependency. Default value: None
• board_settings (str, optional) – Settings file name for target board for dependency. Default value: None
• family (str, optional) – Target FPGA Family for HDL dependency. Default value: None
• device (str, optional) – Target FPGA Device for HDL dependency. Default value: None

Keyword Arguments:  

• **repo_config_dict (dict) – The layout dictionary which defines the projects layout within the repository and working copy on the local file-system. Required by projectmanager.ProjectDependency.layout_to_dir Default value: dict()
• **lib_append_categories (list of str) – Default value: list()
• **bitbucket_username (str, optional) – Default value: None
• **tag_replacement_dict (dict) – Dictionary of required tag replacement fields required by projectmanager.ProjectDependency.layout_tag_attr_replace. This is variable based on category Default value: dict()
• **retag_layout (bool, optional) – True

get_lib_from_name(**kwargs)

Determines the VHDL library name from project name.

Determines the VHDL library name from the project name, ignoring if suffix already exists. the suffix is only appended if the category exists in the lib_append_categories list

Keyword Arguments:  

• **name (str) – The project name being processed. Default value: ''
• **category (str) – The category of the project being processed. Default value: ''
• **lib_append_categories (list of str, optional) – List of categories to append lib_suffix from config.yml configuration file (see categories:). If the category is not in this list the suffix will not be appended. Default value: list().
• **lib_suffix (str, optional) – The library suffix to append. Default value: '_lib'

Returns:

The name of the VHDL library

Return type:

(str)

layout_tag_attr_replace(**kwargs)

Replaces <TAG> with corresponding attribute

Looks for <TAG> (enclosed in <>) in tag string passed to the function, and if found returns a string with the tag replaced by the value in the self.<TAG> attribute.

If the attribute exists but is not populated with a value an “empty” string '' is returned. This allows all <TAG> options in the layout configuration to be optional. Although self.name should always have a value as it is also used to determine filenames in the directory structure.

Keyword Arguments:  **tag (str) – string to check for sub-strings enclosed in <>. Returns:An empty string if corresponding attribute for the <TAG> is not found; or the corresponding attribute if found; or the original <TAG> if anything else. Return type:(str)

layout_to_dir(**kwargs)

Takes a single top-level and creates the directory and file structure as a list.

This layout structure is expected to be defined in the layout_dict keyword passed to the module.

Uses top_refs list to look for a reference to indicate the top reference string, which is used to populate self._top_dirs, this can then be used to create attributes for top_level reference directories.

Keyword Arguments:  

• **layout_dict (dict) – Default value: dict()
• **repo_root (str) – Default value: None
• **top_refs (list of str) – Default value: list()
• **replace_tags (bool) – Default value: True

Returns:

None

prune_path(**kwargs)

Prunes path down towards root_path.

Takes a path and prunes that path until prune_to is found, if root_path is reached it means that prune_to was not found in the path.

Returns path up to and including prune_to, or False if not found.

Keyword Arguments:  

• **path (str) – Path to prune. Default value: None
• **prune_to (str) – Prune down to this path. Default value: None
• **root_path (str) – If root_path is reached the prune fails. Default value: None

Returns:

The found pruned path. The bool: False is returned if root_path is reached without finding the prune criteria.

Return type:

(str)

prune_path_list(**kwargs)

Prunes list of paths based on keyword matching.

Keyword Arguments:  

• **path_list (list of str) – List of paths to prune. Default value: None
• **keyword (str) – Keyword which must exist in path_list item for prune. Default value: ''
• **root_path (str) – If root_path is reached the prune fails. Default value: None

Returns:

A list of pruned paths.

Return type:

(list of str)

retag_path(**kwargs)

Re-tags path(s).

Keyword Arguments:  

• **term (str) – Term to retag.
• **tag (str) – Tag value to replace term with.
• **paths (str or list of str) – absolute path(s) to retag. This assumes the absolute path is in the form: $REPO_ROOT/<TERM>/xx/xx/xx/<TERM> where the second term will be replaced with tag.
• **repo_root (str) – The actual path of the system environment variable $REPO_ROOT

Returns:

List of retagged absolute paths. Empty list() if no repo_root supplied.

Return type:

list of str

static set_top_refs(category, name, tool_version)

Parameters:

• category (str) – category to determine the top-level reference to return.
• name (str) – returned if category is not boards or vendor_ip
• tool_version (str) – returned if category is boards or vendor_ip

Returns:

list of str

static top_dir_lookup(**kwargs)

Maps supported top-level directory names to known values for specified usage throughout

Keyword Arguments:  **dir_name (str) – Name of directory name to attempt to map. Returns:Mapped name if matched. dir_name if not matched. Return type:str

class projectmanager.RepoFlow(**kwargs)

Parses the project settings file for repository_config key and processes locations found under the key. This provides enough information to construct the local working_copy path using repo_root inherited from projectenvironment.ProjectEnvironment and the URL of the remote repository.

Inherits: projectenvironment.ProjectEnvironment (obj): Inherited RepoFlow object. See projectenvironment.projectenvironment.

Username is assumed to be the same for each repository top-level URL (using self.svn_username,

self.bitbucket_username and/or self.git_username inherited from projectenvironment.ProjectEnvironment)

construct_local_path(**kwargs)

Constructs the local path for the local working-copy.

Constructed by joining root and path.

Parameters:

• **root (str) – The top-level root. Usually derived from the $REPO_ROOT environment variable. Default value: None
• **path (str) – The path, derived from subversion:, but with the subpath: removed. This allows the switching between trunk, branches and tags to be managed by the repository client. Default value: None

Returns:

Full path of the local working-copy path.

Return type:

(str)

construct_remote_path(**kwargs)

Constructs the remote path in the externally hosted repository.

Determines if the URL is git and/or bitbucket from urlparse.netloc Uses urlparse to construct URL, where username is constructed manually at the front of urlparse.netloc

Uses posixpath to construct path portion of URL by joining urlparse.path, path and subpath.

Parameters:

• **url (str) – The top-level root URL. See subversion:. Default value: None
• **path (str) – The path. See subversion:. Default value: None
• **subpath (str) – The sub-path. See subversion:. Default value: None

Returns:

• (str): Full path of the remote URL.
• (str): Username for remote URL.
• (str): Repo type <'subversion' or 'git'>. Determined from URL.

Return type:

tuple containing

get_category_from_path(**kwargs)

Gets category: from path.

The first directory in the path string represents the category.

Keyword Arguments:  

• **path (str) – Default value: ''
• **category_mapping (dict, optional) – Category mapping (see categories:). Default value: dict().
• **supported_categories (list of str, optional) – List of supported categories from config.yml configuration file (see categories:). Default value: list().

Returns:

the category extracted from path.

Return type:

(str)

get_contrib_lib_from_path(**kwargs)

Gets contrib_lib: from path.

Assumes (i know!) that contrib_lib exists between the category and name. For a valid contrib_lib to exist the number of elements in path should be = 3.

Keyword Arguments:  

• **name (str) – The project name being processed. Default value: ''
• **path (str) – The path of the project on the file-system. Default value: ''
• **category_mapping (dict, optional) – Category mapping (see categories:). Default value: dict().

Returns:

the contrib_lib extracted from path.

Return type:

(str)

process_repository_config(**kwargs)

Process repository configuration for current project

Keyword Arguments:  **repository_config (dict) – Dictionary of Repository Configuration for Repository Type extracted from settings.yml YAML file. Returns:A list of processed ProjectDependency objects. Return type:(list of obj)

class projectmanager.VendorIpDependency(**kwargs)

Vendor IP is an Vendor IP object containing methods and attributes required for processing vendor_ip

Keyword Arguments:  

• **repo_root (str) – Absolute path to the system environment $REPO_ROOT.
• **master_vendor_ip (obj) – A project dependency object for the master vendor_ip dependency for the project.
• **vendor (str) – FPGA Vendor. Used to determine vendor_ip locations. Valid values: 'xilinx' and altera'. Default value: 'xilinx'
• **tool_version (str) – FPGA Tool Version. Used to determine vendor_ip locations.
• **family (str) – FPGA Family. Used to determine vendor_ip locations.
• **device (str) – FPGA Device. Used to determine vendor_ip locations.
• **ip_dict (dict) –
• **settings_file (str) – Absolute path to settings YAML file, used in logs.

resolved_master_tags(**kwargs)

Keyword Arguments:  

• **paths (str, or list of str) – Absolute path to resolve tags
• **vendor (str) – FPGA Vendor. Used to determine vendor_ip locations. Valid values: 'xilinx' and altera'. Default value: 'xilinx'
• **tool_version (str) – FPGA Tool Version. Used to determine vendor_ip locations.
• **family (str) – FPGA Family. Used to determine vendor_ip locations.
• **device (str) – FPGA Device. Used to determine vendor_ip locations.

Returns:

List of absolute paths with tags resolved.

Return type:

list of str

setup.py

BSD © 2018-2019 Science and Technology Facilities Council & contributors

helpers/version.py

BSD © 2018-2019 Science and Technology Facilities Council & contributors

version.py is a helpers module provided to handle public version numbering which follows the PEP440 guidelines.

Note

The __version__ uses the version.Version (defined in this module), therefore is used towards the end of this module.

class version.Version(major, minor, micro, prerelease='', svn_rev='', disable_svn_logging=False)

Creates a Class with methods to construct and fetch PEP440 Public Version Numbering

Creates an initial PEP440 Public Version Identifier from the supplied parameters after validating the prerelease parameter,

Parameters:

• major (int) – Representing the Major Version Number (changes affecting execution method)
• minor (int) – Representing the Minor Version Number (bugfixes)
• micro (int) – Representing the Micro Version Number (correction of typos/release notes)
• prerelease (int, optional) – Addition Pre-Release Indicator. Valid values: a, b, rc, where: a = alpha; b = beta; and rc = release candidate
• svn_rev (str, optional) – SVN Revision Number
• disable_svn_logging (bool) – Do not include SVN output in logs. Default value: False

get_version()

Method to get the string representation of the version number.

Returns:String of Version Number

set_version(major, minor, micro, pre)

Method to set the string representation of a Version Number.

Parameters:

• major – Integer Value Representing the Major Version Number (changes affecting execution method)
• minor – Integer Value Representing the Minor Version Number (bugfixes)
• micro – Integer Value Representing the Micro Version Number (correction of typos/release notes)
• pre – Optional Addition Pre-Release Indicator… a = alpha b = beta rc = release candidate

Returns:

string

version.about(modname, ver, revision)

Method to Create an About String, to display Method Name and Version/Rev

Parameters:

• modname (str) – Module Name
• ver (str) – Version Number, in the form: MAJOR.MINOR.MICRO
• revision (str) – SVN Revision Number

Returns:

Return type:

str

vunit_iface.py

BSD © 2018-2019 Science and Technology Facilities Council & contributors

vunit_iface.py is a module to handle interfacing and utilising external VUnit module.

See VUnit Documentation.

class vunit_iface.VUnitProject(**kwargs)

VUnit Project is a VUnit object used to configure and execute simulation test-cases.

Keyword Arguments:  

• **simulation_path (str) – Absolute simulation root path for the VUnit project.
• **sim_pre_compiled_libs (str) – Absolute path to the location for precompiled simulation libraries.
• **fpga_vendor (str) – FPGA Vendor. Used to determine build and precompiled library locations. Valid values: 'xilinx' and altera'. Default value: 'xilinx'
• **fpga_toolversion (str) – FPGA Tool Version. Used to determine build and precompiled library locations.
• **sim_version (str) – Simulation Version. Used to determine build and precompiled library locations.
• **hdl_lib_file_dict (dict, optional) – A dictionary containing library keys and absolute paths to HDL files for each library. Default value: dict()
• **tb_hdl_lib_file_dict (dict, optional) – A dictionary containing library keys and absolute paths to test-bench HDL files for each library. Default value: dict()
• **args (obj, optional) – argparse object containing arguments passed to script. If one is not supplied it will be generated here.
• **use_osvvm (bool, optional) – Use OSVVM Components. Default value False
• **use_verification_components (bool, optional) – Use VUnit Verification Components. Default value False
• **settings_file (str) – Absolute path to settings YAML file, used in logs.
• **clean_precompiled_libs (bool, optional) – If True clean precompiled standard simulation libraries for the current project. Default value: False
• **msim_64bit (bool, optional) – If False uses -32bit flag to execute Modelsim.
• **hdl_sim_libs (dict) – Dictionary of Vendor Standard HDL Libraries to add to VUnit.
• **modelsim_installdir (str, optional) – Absolute path to the Modelsim install directory. Used when compiling altera standard libraries.
• **repo_root (str) – Absolute path to the resolved system environment variable $REPO_ROOT.

vu

obj – The VUnit object.

add_hdl_files(**kwargs)

Adds HDL Files to corresponding library.

Keyword Arguments:  **hdl_lib_file_dict (dict) – A dictionary containing library keys and absolute paths to files for each library. Returns:None

add_standard_libraries(**kwargs)

Adds Standard Simulation Libraries to VUnit

This method is derived from : VUnit supplied example

Keyword Arguments:  

• **vunit_obj (obj, optional) – A VUnit object. Default value: self.vu
• **standard_library_path (str, optional) – Absolute path to the location for precompiled simulation libraries. Default value: self.sim_pre_compiled_libs_path
• **hdl_sim_libs (dict) – Dictionary of Vendor Standard HDL Libraries to add to VUnit.

Returns:

True when successful, False when unsuccessful.

Return type:

bool

add_vivado_sim_dependencies(**kwargs)

Add Vivado simulation dependencies to VUnit object

Keyword Arguments:  

• **vivado_path (str) – Absolute path to Vivado.
• **src_paths (list of str, optional) – List of absolute paths to search for dependencies relative to vivado_path. Default value: ['data/verilog/src']
• **src_files (list of str, optional) – List of source file dependencies. Default value: ['glbl.v']
• **glbl (bool, optional) – Include glbl dependency. Default value: False
• **glbl_lib (str, optional) – Library to add glbl to. Default value: 'xil_defaultlib'
• **vunit_obj (obj, optional) – VUnit object. Default value: self.vu

Returns:

True if successful, False if unsuccessful

Return type:

bool

compile_project_ip(**kwargs)

Compiles FPGA Project Specific IP Simulation Libraries

Keyword Arguments:  

• **project_file (str) – Absolute path to project file to parse.
• **simulation_path (str, optional) – Absolute path to the location for simulation path Default value: self.simulation_path
• **project_ip_subpath (str, optional) – Name of project_ip libraries subpath. Default value: 'project_ip'
• **msim_setup_script (str, optional) – Filename of .tcl to compile Vendor IP simulation files in Modelsim. Default value: 'mentor/msim_setup.tcl'
• **top_level_lib (str, optional) – Top-level library to add Vendor IP simulation file to in Modelsim, if False the library name will match the filename, as configured in the generated .qip file. Default value: False

Returns:

None

compile_standard_libraries(**kwargs)

Compiles Standard Simulation Libraries

This method is derived from : VUnit supplied example

Keyword Arguments:  

• **sim_pre_compiled_libs (str, optional) – Absolute path to the location for precompiled simulation libraries. Default value: self.sim_pre_compiled_libs_path
• **standard_lib_subpath (str, optional) – Name of standard library subpath. Default value: 'standard'
• **fpga_vendor (str) – FPGA Vendor. Valid values: 'xilinx' or 'altera'.
• **settings_file (str) – Absolute path to settings YAML file, used in logs.
• **clean (bool, optional) – If True cleans the standard library path. Default value: False
• **msim_64bit (bool, optional) – If False uses -32bit flag to execute Modelsim. Default value: False
• **hdl_sim_libs (dict) – Dictionary of Vendor Standard HDL Libraries to add to VUnit.
• **modelsim_installdir (str, optional) – Absolute path to the Modelsim install directory. Used when compiling altera standard libraries.

Returns:

True when successful, False when unsuccessful.

Return type:

bool

configure_gui(**kwargs)

Pre-processing of additional simulation init file to use when GUI mode is enabled.

Keyword Arguments:  

• **sim_init_script (str) – Absolute path to initialisation file for GUI mode.
• **repo_root (str) – Replacement str for $REPO_ROOT.

Returns:

None

static is_verilog_header(filename)

Checks if filename indicates the file is a verilog header file.

Parameters:filename (str) – Filename to check if it matches the criteria of a verilog header file. Returns:True if a verilog header file, otherwise False Return type:bool

read_compile_order(**kwargs)

Read the vendor_ip simulation compile order file and filter out duplicate files

Keyword Arguments:  **filename (str) – Absolute path to compile order filename to process. Returns:list of str, set, list of str Return type:tuple containing

resolve_gui_init_script(**kwargs)

Parses Simulation GUI Initialisation Script

There appears to be an issue with Modelsim directly using $env(REPO_ROOT) in scripts passed from VUnit to Modelsim, so this workaround creates a file with REPO_ROOT resolved and uses the created resolved file instead:

Keyword Arguments:  

• **sim_init_script (str) – Absolute path to initialisation file to resolve.
• **repo_root (str) – Replacement str for $REPO_ROOT.

Returns:

Return type:

str

setup_simulation_options(**kwargs)

Sets up the compile and sim options.

Keyword Arguments:  

• **glbl (bool, optional) – Include glbl dependency. Default value: False
• **glbl_lib (str, optional) – Library to add glbl to. Default value: 'xil_defaultlib'

Returns:

None

vunit_iface.tb_cfg_encode(tb_cfg)

Encodes a VUnit test-case dictionary configuration to a string to pass to VUnit Test-Case

String is passed to VHDL test-bench file using the encoded_tb_cfg generic.

Parameters:tb_cfg (dict) – Returns:str