sonar package

Submodules

sonar.api module

The Sonar API is defined here to interact with the sonar database and perform the CLI tasks.

class sonar.api.Board

Bases: object

The Board class defines functions to interact with sonar’s list of hardware boards.

static activate(args)

Activate a board by name

Parameters:args (object) – Holds attributes name (str): Name of board to activate
static add(args)

Add a new board to sonar database

Parameters:args (object) – Holds attributes path (str): Path to the board definition
static clear(_args)

Remove all boards from the sonar database

Parameters:_args (object) – Unused
static deactivate(_args)

Deactivate the active board

Parameters:_args (object) – Unused
static f_list(_args)

List the active board and all boards in the sonar database

Parameters:_args (object) – Holds attributes
static remove(args)

Remove a board from the sonar database

Parameters:args (object) – Holds attributes name (str): Name of board to remove
static show(args)

Print a particular board by name

Parameters:args (object) – Holds attributes name (str): Name of board to show
class sonar.api.Create

Bases: object

The Create class defines functions to create new IPs and repos in sonar.

static ip(args)

Create a new sonar IP in the current working directory.

Parameters:args (object) – Should have “name” attribute
static repo(args)

Create a new sonar repo in the current working directory.

Parameters:args (object) – Should have “name” attribute
class sonar.api.Database

Bases: object

The Database class defines functions to interact with sonar’s sonar database.

static f_list(_args=None)

Print the database to stdout.

Parameters:_args (object) – unused
class sonar.api.Env

Bases: object

The Env class defines functions to interact with sonar’s environments. Environments define a particular set of tools, board and repository that users can switch between.

static activate(args)

Activate a particular environment by name.

Parameters:args (object) – Holds attributes name (str): Name of the enviroment to activate
static add(args)

Add a new environment to the database.

Parameters:args (object) – Holds attributes cad (str): CAD tool of the form “name:version” sim (str): Simulation tool of the form “name:version” hls (str): HLS tool of the form “name:version” name (str): Name of the environment board (str): Name of the board repo (str): Name of the repository
static clear(_args)

Clear all environments in the database

Parameters:_args (object) – Unused
static f_list(_args)

List the environments in the database

Parameters:_args (object) – Unused
static remove(args)

Remove an environment from the database

Parameters:args (object) – Holds attributes name (str): Name of the environment to remove
class sonar.api.Init

Bases: object

The Init class defines functions to initialize sonar in various ways.

static one_time_setup(_args)

Performs initial setup for sonar. It creates the database, copies files over to the user sonar directory and adds the default boards to the database.

Parameters:_args (object) – Unused
static vivado(args)

Helper function to initialize Xilinx tools

Parameters:args (object) – Holds attributes path (str): Path to the Xilinx directory containing Vivado
class sonar.api.Repo

Bases: object

The Repo class defines functions to interact with sonar’s repositories.

static activate(args)

Activate a particular repository

Parameters:args (object) – Should have “name” attribute
static add(_args)

Add a new repository to the database

Parameters:_args (object) – Unused
static clear(_args)

Clear the list of repositories in the database

Parameters:_args (object) – Unused
static f_list(_args)

List all the repositories in the database

Parameters:_args (object) – Unused
class sonar.api.Tool

Bases: object

The Tool class defines functions to interact with sonar’s CAD, HLS and simulation tools.

static add(args)

Add a new tool to the database.

Parameters:args (object) – Holds attributes name (str): Name of tool version (str): Version of tool cad (str): Name of CAD executable hls (str): Name of HLS executable sim (str): Name of simulation executable script (str): Shell script to initialize tool
static clear(_args)

Clear the database of tools

Parameters:_args (object) – Unused
static f_list(_args)

List the tools in the sonar database

Parameters:_args (object) – Unused
sonar.api.activate(args)

Activate a particular environment by name.

Parameters:args (object) – Holds attributes name (str): Name of the enviroment to activate
sonar.api.check_database()

Checks to see if the sonar database exists. If it does not, performs the setup to initialize the database.

sonar.base_types module

This module defines basic object types used throughout sonar.

class sonar.base_types.Clock(name, size, period)

Bases: sonar.base_types.Signal

Defines a clock

asdict()

Placeholder function that’s overridden in the child classes

Raises:NotImplementedError – This function should not be called
class sonar.base_types.ClockPort(name, size, period, direction)

Bases: sonar.base_types.Clock

Defines a clock port on a module

asdict()

Placeholder function that’s overridden in the child classes

Raises:NotImplementedError – This function should not be called
class sonar.base_types.InOutPorts

Bases: sonar.base_types.SonarObject

Maintains a list of input and output signals

asdict()

Placeholder function that’s overridden in the child classes

Raises:NotImplementedError – This function should not be called
class sonar.base_types.InterfacePorts

Bases: sonar.base_types.SonarObject

Maintains lists of the different interface directions

asdict()

Placeholder function that’s overridden in the child classes

Raises:NotImplementedError – This function should not be called
class sonar.base_types.ModulePorts

Bases: object

Holds a module’s ports

add_clock(signal)

Add a clock to the module

Parameters:signal (ClockPort) – A ClockPort object
add_interface(interface)

Add an interface to the module

Parameters:interface (BaseInterface) – An interface
add_reset(signal)

Add a reset to the module

Parameters:signal (SignalPort) – A SignalPort object
add_signal(signal)

Add a signal to the module

Parameters:signal (SignalPort) – A SignalPort object
asdict()

Return the Module ports object as a dict

Returns:Module ports
Return type:dict
get_clocks(directions: Tuple[str, str] = ('input', 'output'), collapse: bool = True)

Get the module’s clocks

Parameters:
  • directions (tuple, optional) – Clock directions to get. Defaults to (“input”, “output”).
  • collapse (bool, optional) – Return one list with all clocks if true
  • return a dict whose indices are the directions. Defaults to True. (or) –
Returns:

Module clocks
Return type:

Union[list, dict]
get_interfaces(directions=('master', 'slave', 'mixed'), collapse=True)

Get the module’s interfaces

Parameters:
  • directions (tuple, optional) – Reset directions to get. Defaults to (“master”, “slave”, “mixed”).
  • collapse (bool, optional) – Return one list with all interfaces if true
  • return a dict whose indices are the directions. Defaults to True. (or) –
Returns:

Module interfaces
Return type:

Union[list, dict]
get_resets(directions=('input', 'output'), collapse=True)

Get the module’s resets

Parameters:
  • directions (tuple, optional) – Reset directions to get. Defaults to (“input”, “output”).
  • collapse (bool, optional) – Return one list with all resets if true
  • return a dict whose indices are the directions. Defaults to True. (or) –
Returns:

Module resets
Return type:

Union[list, dict]
get_signals(directions=('input', 'output'), collapse=True)

Get the module’s signals (excludes clocks, resets, and signals that are a part of interfaces).

Parameters:
  • directions (tuple, optional) – Signal directions to get. Defaults to (“input”, “output”).
  • collapse (bool, optional) – Return one list with all signals if true
  • return a dict whose indices are the directions. Defaults to True. (or) –
Returns:

Module signals
Return type:

Union[list, dict]
class sonar.base_types.Signal(name, size)

Bases: sonar.base_types.SonarObject

Defines a signal

asdict()

Placeholder function that’s overridden in the child classes

Raises:NotImplementedError – This function should not be called
class sonar.base_types.SignalPort(name, size, direction)

Bases: sonar.base_types.Signal

Defines a signal port on a module

asdict()

Placeholder function that’s overridden in the child classes

Raises:NotImplementedError – This function should not be called
class sonar.base_types.SonarObject

Bases: object

The basic object. It enforces that the object has a method to turn itself into a dictionary (for easy printing).

asdict()

Placeholder function that’s overridden in the child classes

Raises:NotImplementedError – This function should not be called

sonar.cli module

Defines all the CLI argument parsing functions

sonar.cli.activate(parser)

Parse the “activate” argument

Parameters:parser (argparse._SubParsersAction) – The parser object
sonar.cli.add_help(parser)

Add generic help message to parsers

Parameters:parser (argparse._SubParserAction) – The parser object
sonar.cli.board(parser)

Parse the “board” argument

Parameters:parser (argparse._SubParserAction) – The parser object
sonar.cli.create(parser)

Parse the “create” argument

Parameters:parser (argparse._SubParserAction) – The parser object
sonar.cli.database(parser)

Parse the “database” argument

Parameters:parser (argparse._SubParserAction) – The parser object
sonar.cli.env(parser)

Parse the “env” argument

Parameters:parser (argparse._SubParserAction) – The parser object
sonar.cli.init(parser)

Parse the “init” argument

Parameters:parser (argparse._SubParserAction) – The parser object
sonar.cli.repo(parser)

Parse the “repo” argument

Parameters:parser (argparse._SubParserAction) – The parser object
sonar.cli.tool(parser)

Parse the “tool” argument

Parameters:parser (argparse._SubParserAction) – The parser object

sonar.database module

Manage the sonar database

class sonar.database.Board

Bases: object

Manage the boards in the database

static activate(name)

Activate a board

Parameters:name (str) – Name of board
Raises:SonarInvalidArgError – If board is not in the database
static add(path)

Add a new board to the database

Parameters:path (str) – Path to the board files
static clear()

Remove all boards from the database

static deactivate()

Deactivate the active board

static get(name=None)

Get all boards or a particular one from the database

Parameters:name (str, optional) – Name of board to get. Defaults to None.
Raises:SonarInvalidArgError – If board is not in the database
Returns:Board entry from the database
Return type:dict
static get_active()

Get the active board

Returns:Board entry from the database
Return type:dict
static remove(name)

Remove a board from the database

Parameters:name (str) – Name of board to remove
class sonar.database.Env

Bases: object

Manage the environments in the database

static activate(name)

Activate an environment

Parameters:name (str) – Name of the environment
Raises:SonarInvalidArgError – If environment is not found in the database
static add(name, cad_tool, hls_tool, sim_tool, board, repo)

Add a new environment to the database

Parameters:
  • name (str) – Name of environment
  • cad_tool (str) – Name of CAD tool
  • hls_tool (str) – Name of HLS tool
  • sim_tool (str) – Name of SIM tool
  • board (str) – Name of board
  • repo (str) – Name of repository
static clear()

Clear all environments from the database

static deactivate()

Deactivate the active environment

static get(name=None)

Get information about an environment or all environments

Parameters:name (str, optional) – Name a particular env to get. Defaults to None.
Raises:SonarInvalidArgError – If named env is not found in the database
Returns:Environment entry from the database
Return type:dict
static get_active()

Get active environment

Returns:Environment entry from the database
Return type:Dict
static remove(name)

Remove a particular environment from the database

Parameters:name (str) – Name of environment
class sonar.database.IP

Bases: object

Manage the IPs in the database

static add_new(name, path)

Add a new IP to the database

Parameters:
  • name (str) – Name of the IP
  • path (str) – Path for the IP
class sonar.database.Repo

Bases: object

Manage the repositories in the database

static activate(name)

Activate a repository

Parameters:name (str) – Name of repository
Raises:SonarInvalidArgError – If repository not found
static add(path=None)

Add a new repository

Parameters:path (str, optional) – Path to the repository. Defaults to CWD.
static clear()

Clear all repositories from the database and deactivate the active repo

static deactivate()

Deactivate the active repo

static get(name=None)

Get a particular repository or all of them

Parameters:name (str, optional) – Name of repository. Defaults to None.
Raises:SonarInvalidArgError – If repository is not found in the database
Returns:Repository entry from the database
Return type:dict
static get_active()

Get the active repository

Returns:Repository entry from the database
Return type:Dict
class sonar.database.Tool

Bases: object

Manage the tools in the database

static activate(cad_tool, hls_tool, sim_tool)

Activate a set of tools

Parameters:
  • cad_tool (str) – Name of CAD tool
  • hls_tool (str) – Name of HLS tool
  • sim_tool (str) – Name of SIM tool
static add(tool_name, version, cad_exe, hls_exe, sim_exe, script)

Add a new tool to the database

Parameters:
  • tool_name (str) – Name of the tool
  • version (str) – Tool version
  • cad_exe (str) – Name of CAD tool executable. None if not applicable
  • hls_exe (str) – Name of HLS tool executable. None if not applicable
  • sim_exe (str) – Name of simulation tool executable. None if not applicable
  • script (str) – Shell script to initialize the tool
Raises:

SonarInvalidOpError – Raised if attempting to add an already existing tool.
static clear()

Clear all tools from the database

static deactivate()

Deactivate all active tools

static get(tool=None)

Get a tool from the database

Parameters:tool (str, optional) – Get a particular tool only. Defaults to None.
Raises:SonarInvalidArgError – Raised if named tool not found in the database
Returns:Tool entry from the database
Return type:dict
static get_active()

Get the active tool

Returns:Tool entry from the database
Return type:dict
sonar.database.check_database()

Check if the database exists

Returns:True if database exists
Return type:Bool
sonar.database.init()

Initialize the database with empty sections

sonar.database.print_db()

Print the database to stdout

sonar.exceptions module

sonar uses custom exceptions to pass more useful error messages back. This module defines the exceptions.

class sonar.exceptions.ReturnValue

Bases: enum.IntEnum

Enumeration of return values

SONAR_INVALID_ARG = 1
SONAR_INVALID_NUMBER_OF_ARGS = 2
SONAR_INVALID_OP = 5
SONAR_INVALID_PATH = 4
SONAR_NONEXISTENT_PATH = 3
SONAR_OK = 0
SONAR_UNKNOWN = -1
exception sonar.exceptions.SonarException(message='')

Bases: Exception

Base sonar exception defines an initial error string and code

exception sonar.exceptions.SonarInvalidArgError(message='')

Bases: sonar.exceptions.SonarException

Indicates an invalid argument error

exception sonar.exceptions.SonarInvalidOpError(message='')

Bases: sonar.exceptions.SonarException

Indicates an error due to an invalid operation attempt

sonar.include module

Broadly used functions and classes across sonar

class sonar.include.DotDict(*args, **kwargs)

Bases: dict

A dictionary that allows its members to be accessed through the dot operator as attributes.

sonar.include.replace_in_file(src_file, str_to_replace, replacement_str)

Replace a string in a file and save the file back in place

Parameters:
  • src_file (filepath) – Str or Path to a file to open
  • str_to_replace (str) – The string to replace
  • replacement_str (str) – The replacement string

sonar.main module

The main entry point for the sonar CLI. Here, we check the status of the local user database and pass in the command-line arguments to their parsers.

sonar.main.main()

Main CLI usage. Parses the command-line arguments, checks the local database and calls the appropriate CLI function.

sonar.main.parse_args()

Defines the command-line argument parser. All the parsing functions are in the CLI module

Returns:The parsed args
Return type:args

sonar.make module

A Python wrapper around Make

class sonar.make.CFlags

Bases: object

Object holding the flags used for compilation.

class sonar.make.MakeFile

Bases: object

Represents a complete Makefile. For now, many aspects are hard coded

ip(ip_dir)

Add the IP-related variables and targets to the Makefile

Parameters:ip_dir (str) – Path to the IP directory
Returns:Text to be added to the Makefile
Return type:str

sonar.protocols module

sonar.testbench module

Main module to define a testbench in sonar

class sonar.testbench.Module

Bases: sonar.base_types.SonarObject

Defines a module in a testbench

add_clock_port(name, period)

Adds an input clock port to this module (only for TB generated clocks)

Parameters:
  • name (str) – Name of the clock signal
  • period (str) – Period of the clock (e.g. 20ns, 10ps etc.)
add_endpoint(port, endpoint)

Add an endpoint to a port on the module

Parameters:
  • port (str) – Name of the port
  • endpoint (Endpoint) – Endpoint to add
add_interface(interface)

Adds an interface port to this module

Parameters:interface (BaseInterface) – Represents the interface port and must be a child class of BaseInterface.
add_parameter(name, value)

Add a named parameter to this module’s instantiation

Parameters:
  • name (str) – Name of parameter
  • value (str) – Value to assign to parameter
add_port(name, direction, size=1)

Adds a port to this module for a generic signal

Parameters:
  • name (str) – Name of the signal
  • direction (str) – Must be one of (input|output)
  • size (int, optional) – Defaults to 1. Width of the port in bits
add_reset_port(name)

Adds an input reset port to this module

Parameters:name (str) – Name of the reset signal
asdict()

Converts the object to a dictionary

Returns:Dictionary representing the object
Return type:dict
classmethod cpp(name, lang, hls, hls_version)

Creates a default cpp module with the given name, language and HLS tool

Parameters:
  • name (str) – Name of the module to create
  • lang (str) – Language used for the module
  • hls (str) – HLS tool used to synthesize
  • hls_version (str) – HLS tool version
Returns:

Object representing a module
Return type:

Module
classmethod cpp_vivado(name, clk_period='20ns', reset_low=True, version='2018.1')

Creates a default cpp module with the given name, language and HLS tool

Parameters:
  • name (str) – Name of the module to create
  • clk_period (str, optional) – Defaults to 20ns. Clock period to use
  • reset_low (bool, optional) – Defaults to True. Enable active low reset Set False to use active high reset
  • version (str, optional) – Defaults to 2018.1. Vivado tool version
Returns:

Object representing a module
Return type:

Module
classmethod default(name)

Creates a default module with the given name

Parameters:name (str) – Name of the module to create
Returns:Object representing a module
Return type:Module
class sonar.testbench.TestVector(thread=None, threads=None)

Bases: sonar.base_types.SonarObject

Defines a test vector in a testbench

add_thread(thread=None)

Adds a thread to the TestVector. If a thread is provided as an argument, it’s added to the TestVector. Otherwise, an empty one is created, added and returned.

Parameters:thread (Thread, optional) – Defaults to None. The thread to add
Returns:The added thread is returned
Return type:Thread
asdict()

Converts the object to a dictionary

Returns:Dictionary representing the object
Return type:dict
class sonar.testbench.Testbench

Bases: sonar.base_types.SonarObject

Holds the complete testbench with global attributes, the modules, and the test vectors

add_dut(module)

Add the device-under-test to the testbench

Parameters:module (Module) – Module to add to this testbench
add_metadata(key, value)

Adds metadata to the Sonar object

Parameters:
  • key (str) – Key to store the value against
  • value (str) – Metadata to store
Raises:

KeyError – Raised if the requested key already exists
add_test_vector(vector)

Add a test vector to the testbench

Parameters:vector (TestVector) – Vector containing one or more non-empty threads
asdict()

Converts the object to a dictionary

Returns:Dictionary representing the object
Return type:dict
asjson()

Converts the testbench into JSON format for further processing or printing

Returns:Testbench object dumped as JSON string
Return type:str
classmethod default(module_name)

Initializes a Testbench with default metadata values

Parameters:module_name (str) – Name of the DUT module
Returns:the Testbench object represents the whole testbench
Return type:Testbench
generate_tb(tb_filepath, languages, force=False)

After the Testbench object is complete, this will invoke the Sonar Core to generate the testbench(es) based on the information

Parameters:
  • tb_filepath (str) – path to the sonar testbench script
  • languages (str) – sv or all to choose which languages
  • force (bool, optional) – Force testbench generation. Defaults to False
get_from_dut(key)

Get certain parts of the DUT from the testbench

Parameters:key (str) – Key used to access different parts
Returns:Return type depends on the key
Return type:various
set_metadata(key, value)

Sets the metadata value of the specified key to the provided value

Parameters:
  • key (str) – Key to update
  • value (str) – Metadata value to store
Raises:

KeyError – raised if the requested key doesn’t exist
set_prologue_thread(thread)

Set a thread to act as a prologue prior to every test vector. Typically, this thread should set resets and configure the initial state of the system. All other threads in all test vectors will start after this one.

Parameters:thread (Thread) – A Thread object
class sonar.testbench.Thread

Bases: sonar.base_types.SonarObject

Defines a one serial thread of execution in a parallel test vector

add_delay(delay)

Add a timed delay to the thread

Parameters:delay (str) – String representing delay length e.g. ‘40ns’
asdict()

Converts the object to a dictionary

Returns:Dictionary representing the object
Return type:dict
assert_value(condition, *args)

Add an assertion condition (assert the signal value matches) to the thread.

Parameters:
  • condition (str) – SV-compatible statement (e.g. ‘signal == 1’)
  • args (int) – Conditions can use ‘args[x]’ as variables and their values can be passed in as args
call_dut(num)

Call the DUT function some number of times (only for C++ TBs)

Parameters:num (int) – Number of times to call the DUT function
disable_timestamps()

Disables timestamping

display(string)

Print the string to the console (note, must not contain spaces)

Parameters:string (str) – String to print
enable_timestamps(prefix, index)

Each subsequent command (until disabled) will print the time after it finishes with the given prefix and an index which starts at the provided one.

Parameters:
  • prefix (str) – String to prefix the timestamp with
  • index (int) – Integer to start indexing the timestamps at
end_vector()

Ends the TestVector. This command must be the last chronological event in the vector. If using C++ (or any other sequential simulation), the thread containing this command must also be the last thread in the vector

init_signals()

Initialize all signals to zero

init_timer()

Set the timer to zero to begin timestamping

print_elapsed_time(time_id)

Prints the elapsed time since the last init_timer command

Parameters:id (str) – String to print out with the timestamp for identification
print_time()

Prints the absolute time

set_flag(flag_id)

Set the flag with the given ID to 1. The number of flags available is set in the metadata of the testbench. Flags can be used to synchronize between threads. e.g. one thread can set a flag that another will wait for.

Parameters:flag_id (number) – ID of the flag to set (ranges from 0 to Flags-1)
set_signal(name, value)

Set the value of a signal to be the specified value

Parameters:
  • name (str) – Name of the signal
  • value (number) – May be an int, or a hex or binary number string (preceded by 0x or 0b respectively)
wait_flag(flag_id)

Wait for the flag with the given ID to become 1. The number of flags available is set in the metadata of the testbench. Flags can be used to synchronize between threads. e.g. one thread can set a flag that another will wait for.

Parameters:flag_id (number) – ID of the flag to wait on (ranges from 0 to Flags-1)
wait_level(condition, *args)

Add a level-wait condition (wait until the signal value matches) to the thread.

Parameters:
  • condition (str) – SV-compatible statement (e.g. ‘signal == 1’)
  • args (int) – Conditions can use ‘args[x]’ as variables and their values can be passed in as args
wait_negedge(signal)

Add a negative-edge sensitive wait condition on a signal.

Parameters:signal (str) – Name of the signal to wait on
wait_posedge(signal)

Add a positive-edge sensitive wait condition on a signal.

Parameters:signal (str) – Name of the signal to wait on

Module contents

Global package information