sonar.interfaces package

Submodules

sonar.interfaces.axi4_lite_slave module

Defines an AXI4-Lite Slave interface

class sonar.interfaces.axi4_lite_slave.AXI4LiteSlave(name, clock, reset)

Bases: sonar.interfaces.base_interface.BaseInterface

Defines the AXI-Lite slave interface

add_endpoint(endpoint, **kwargs)

Add an endpoint to this AXI4-Lite interface

Parameters:

• endpoint (str) – Identifier for the endpoint
• kwargs – Keyworded arguments for the endpoint

add_register(name, address)

Add a register to this interface

Parameters:

• name (str) – Name of the register to add
• address (number) – Address of the register

addrWidth

This is used by regex for variable substitution so cannot have underscores

Returns:Size of the address signal Return type:int

asdict()

Returns this object as a dictionary

Returns:The fields of this object as a dictionary Return type:dict

dataWidth

This is used by regex for variable substitution so cannot have underscores

Returns:Size of the data signal Return type:int

del_register(name)

Delete a register from this interface

Parameters:name (str) – Name of the register to delete

init_signals(mode, data_width=None, addr_width=None, upper_case=True)

Initialize the signals associated with this AXILite interface. Initialize means to specify the names, types and widths of all the signals.

Parameters:

• mode (str) – Name of a signal preset to use. Options are: ‘default’: standard AXI-Lite without cache or prot
• data_width (number) – Width of the data signal (r/w)
• addr_width (number) – Width of the addr signal (r/w)
• upper_case (bool, optional) – Defaults to True. Assume that the signal names are the uppercase versions of their type, which is the default for an HLS module. Setting it to False sets the name identical to the type (i.e. lowercase)

Raises:

• NotImplementedError – Unhandled exception if bad mode entered
• ValueError – Error in mode/argument association

read(thread, register, expected_value)

Read data from a register to verify its value

Parameters:

• thread (Thread) – Thread in which to read from
• register (str) – Name of the register to read
• expected_value (number) – Expected value that the register should have

set_address(addr_range, addr_offset)

Sets the address range and offset for this AXI-Lite interface

Parameters:

• addr_range (str) – Address size e.g. ‘4K’
• addr_offset (number) – Offset address

write(thread, register, data)

Write data to a register

Parameters:

• thread (Thread) – Thread in which to write from
• register (str) – Name of the register to write to
• data (number) – Value that should be written

class sonar.interfaces.axi4_lite_slave.AXI4LiteSlaveCore

Bases: sonar.interfaces.base_interface.InterfaceCore

Defines the core properties of the AXI4-Lite Slave interface used internally

args = {'cpp': {'addr': 0, 'data': 1}, 'sv': {'addr': 1, 'data': 2, 'endpoint_mode': 0}}

static import_packages_global()

Specifies any packages that must be imported once per testbench

Returns:Packages to be imported Return type:str

signals = {'input': {'arready': {'required': True, 'size': 1}, 'awready': {'required': True, 'size': 1}, 'bresp': {'required': True, 'size': 2}, 'bvalid': {'required': True, 'size': 1}, 'rdata': {'required': True, 'size': 0}, 'rresp': {'required': True, 'size': 2}, 'rvalid': {'required': True, 'size': 1}, 'wready': {'required': True, 'size': 1}}, 'output': {'araddr': {'required': True, 'size': 0}, 'arvalid': {'required': True, 'size': 1}, 'awaddr': {'required': True, 'size': 0}, 'awvalid': {'required': True, 'size': 1}, 'bready': {'required': True, 'size': 1}, 'rready': {'required': True, 'size': 1}, 'wdata': {'required': True, 'size': 0}, 'wstrb': {'required': True, 'size': 0}, 'wvalid': {'required': True, 'size': 1}}}

class sonar.interfaces.axi4_lite_slave.EndpointManual

Bases: sonar.endpoints.InterfaceEndpoint

Manual endpoint

actions = {'cpp': {'master': [{'foreach': 'registers', 'commands': ['if(args[0] == $$addresses){', ' $$registers = args[1];', '}']}], 'slave': []}, 'sv': {'read': ['$$agent.AXI4LITE_READ_BURST(args[1],0,$$readData,$$readResp); //addr, prot, read_data, resp', 'assert($$readData == args[2]) begin', 'end else begin', ' $error("S-AXILITE Assert failed at %t on $$readData. Expected: %h, Received: %h", $time, args[2], $$readData);', ' retval = 1;', 'end'], 'write': ['$$agent.AXI4LITE_WRITE_BURST(args[1],0,args[2],$$writeResp);']}}

static import_packages_local(interface)

Specifies any packages that must be imported once per interface

Parameters:interface (AXI4LiteSlave) – AXI4LiteSlave instance Returns:Packages to be imported Return type:str

static initial_blocks(indent)

Any text that should be inside an initial block

Parameters:indent (str) – Indentation to add to each line Returns:List of strings that go into separate initial blocks Return type:list[str]

static instantiate(indent)

Any modules that this interface instantiates in SV.

Parameters:

• interface (AXI4LiteSlave) – AXI4LiteSlave
• indent (str) – Indentation to add to each line

Returns:

Updated ip_inst

Return type:

str

static prologue(indent)

Any text that should be part of the testbench as a prologue outside any blocks such as variable declarations.

Parameters:indent (str) – Indentation to add to each line Returns:Updated prologue Return type:str

static source_tcl(interface, path)

Any TCL files that should be sourced as part of initializing the interface

Parameters:

• interface (AXI4LiteSlave) – AXI4LiteSlave object
• path (str) – Path where to place the TCL source files

sonar.interfaces.axi4_stream module

Defines an AXI4-Stream interface

class sonar.interfaces.axi4_stream.AXI4Stream(name, direction, clock, reset)

Bases: sonar.interfaces.base_interface.BaseInterface

Defines the AXI-Stream interface for master and slave

add_endpoint(endpoint, **kwargs)

Add an endpoint to the AXI4-Stream interface

Parameters:

• endpoint (str) – Identifier for the endpoint
• kwargs – Keyworded arguments for the endpoint

asdict()

Returns this object as a dictionary

Returns:The fields of this object as a dictionary Return type:dict

data_to_stream(thread, data, parsing_func=None, endian='little')

Sends the data as a series of AXI4Stream transactions.

Parameters:

• thread (Thread) – Thread to stream the data in
• data (Any) – Data to stream
• parsing_func (Func, optional) – Defaults to None. Function that determines how the data is parsed. Must return a list of dicts representing valid AXI4Stream transactions. The default function assumes a binary string containing only tdata
• endian (str, optional) – Defaults to ‘little’. Must be little|big

file_to_stream(thread, filepath, parsing_func=None, endian='little')

Converts the provided file into a series of AXI4Stream transactions.

Parameters:

• thread (Thread) – Thread to stream the file in
• filepath (str) – Path to the file to stream
• parsing_func (Func, optional) – Defaults to None. Function that determines how the file is parsed. Must return a list of dicts representing valid AXI4Stream transactions. The default function assumes a binary file containing only tdata
• endian (str, optional) – Defaults to ‘little’. Must be little|big

Returns:

Dictionary representing the data transaction

Return type:

dict

init_signals(mode, data_width, upper_case=True)

Initialize the signals associated with this AXI4Stream interface. Initialize means to specify the names, types and widths of all the signals.

Parameters:

• mode (str) – Name of a signal preset to use. Options are: ‘default’: tdata, tvalid, tready, tlast ‘tkeep’: tdata, tvalid, tready, tlast, tkeep ‘min’: tdata, tvalid
• data_width (number) – Width of the tdata field
• upper_case (bool, optional) – Defaults to True. Assume that the signal names are the uppercase versions of their type, which is the default for an HLS module. Setting it to False sets the name identical to the type (i.e. lowercase)

read(thread, data, **kwargs)

Reads the given keyworded args from an AXI4Stream stream to verify output.

Returns:Dictionary representing the data transaction Return type:dict

reads(thread, data)

Reads the list of keyworded args from an AXI stream to verify output. This command results in a smaller file size than repeated ‘read’ commands.

Parameters:

• thread (Thread) – Thread to read the data in
• data (iterable) – This should be an iterable of kwargs where the keywords are AXI4Stream compliant.

wait(thread, data, bit_range=None)

Adds a wait statement to the provided thread for a specific tdata value

Parameters:

• thread (Thread) – The thread to add the wait to
• data (number) – The value of tdata to wait for
• bit_range (string, optional) – Defaults to all bits. Range of bits to check in tdata, separated by a colon. e.g. “63:40”

write(thread, data, **kwargs)

Writes the given command to the AXI stream.

Parameters:

• data (str) – Data to write
• kwargs (str) – keyworded arguments where the keyword is the AXI4Stream signal or special keyword and is assigned to the given value

writes(thread, data)

Writes an array of commands to the AXI stream. This command results in a smaller final file size than using the write command in a loop

Parameters:

• thread (Thread) – The thread to write the commands to
• data (Iterable) – This should be an iterable of kwargs where the keywords are AXI4Stream compliant.

class sonar.interfaces.axi4_stream.AXI4StreamCore

Bases: sonar.interfaces.base_interface.InterfaceCore

Defines the core properties of the AXI4-Stream interface used internally

args = {'cpp': {'tdata': 0, 'tdest': 3, 'tkeep': 2, 'tlast': 1}, 'sv': {'endpoint_mode': 0, 'tdata': 1, 'tdest': 4, 'tkeep': 3, 'tlast': 2}}

signals = {'input': {'tready': {'required': False, 'size': 1}}, 'output': {'tdata': {'required': True, 'size': 0}, 'tdest': {'required': False, 'size': 0}, 'tid': {'required': False, 'size': 0}, 'tkeep': {'required': False, 'size': 0}, 'tlast': {'required': False, 'size': 1}, 'tuser': {'required': False, 'size': 0}, 'tvalid': {'required': True, 'size': 1}}}

classmethod write_cpp(packet, _identifier='NULL')

Write one line of the C++ data file

Parameters:packet (dict) – The command to write Returns:The command as a line for the data file Return type:str

class sonar.interfaces.axi4_stream.EndpointManualMaster

Bases: sonar.endpoints.InterfaceEndpoint

EndpointManualMaster class

actions = {'cpp': {'master': [{'signals': {'tdata', 'tdest', 'tlast', 'tkeep'}, 'commands': ['$$name_flit.$$signal = args[$$i];']}, '$$name.write($$name_flit);']}, 'sv': {'write': ['wait($$clock == 0);', {'signals': {'tdata', 'tdest', 'tlast', 'tkeep'}, 'commands': ['$$name_$$signal_endpoint[$$endpointIndex] = args[$$i];']}, "$$name_tvalid_endpoint[$$endpointIndex] = 1'b1;", "@(posedge $$clock iff $$name_tready === 1'b1);", '@(negedge $$clock);', "$$name_tvalid_endpoint[$$endpointIndex] = 1'b0;"]}}

class sonar.interfaces.axi4_stream.EndpointManualSlave

Bases: sonar.endpoints.InterfaceEndpoint

EndpointManualSlave class

actions = {'cpp': {'slave': ['$$name.read($$name_flit);', {'signals': {'tdata', 'tdest', 'tlast', 'tkeep'}, 'commands': ['assert($$name_flit.$$signal == args[$$i] && "Assert failed on $$name_flit.$$signal");']}]}, 'sv': {'read': ['@(posedge $$clock iff $$name_tready && $$name_tvalid);', {'signals': {'tdata', 'tdest', 'tlast', 'tkeep'}, 'commands': ['assert($$name_$$signal == args[$$i]) begin\nend else begin\n $error("AXI-S Assert failed at %t on $$name_$$signal. Expected: %h, Received: %h", $time, args[$$i], $$name_$$signal);\n retval = 1;\nend']}]}}

classmethod asdict()

Placeholder function that’s overridden in the child classes

Raises:NotImplementedError – This function should not be called

static instantiate(_indent)

Any modules that this interface instantiates in SV.

Parameters:indent (str) – Indentation to add to each line Returns:Updated ip_inst Return type:str

class sonar.interfaces.axi4_stream.EndpointVariableTready

Bases: sonar.interfaces.axi4_stream.EndpointManualSlave

EndpointVariableTready class

classmethod asdict()

Placeholder function that’s overridden in the child classes

Raises:NotImplementedError – This function should not be called

static instantiate(_indent)

Any modules that this interface instantiates in SV.

Parameters:_indent (str) – Indentation to add to each line Returns:Updated ip_inst Return type:str

sonar.interfaces.base_interface module

Defines the base interfaces classes that interfaces and interface cores inherit from

class sonar.interfaces.base_interface.BaseInterface(name, direction, core)

Bases: sonar.base_types.SonarObject

Defines an interface in sonar

add_endpoint(endpoint, **kwargs)

Add an endpoint to the interface

Parameters:

• endpoint (Endpoint) – The endpoint to add
• kwargs – Keyworded arguments for the endpoint

add_signal(signal_type, signal)

Adds a signal to this interface

Parameters:

• signal_type (str) – Type of signal to add (interface-dependent)
• signal (Signal) – Signal object

add_signals(signals)

Adds a set of signals to this interface port

Parameters:signals (dict) – signals to add to the interface

asdict()

Placeholder function that’s overridden in the child classes

Raises:NotImplementedError – This function should not be called

get_signal(signal_type)

Returns information about the named signal on this interface

Parameters:signal_type (str) – The signal type to fetch Raises:KeyError – Raised if signal_type isn’t found Returns:Information about the requested signal Return type:Signal

has_signal(signal_type)

Returns a boolean if the interface has a specific signal

Parameters:signal_type (str) – The signal type to search Returns:True if the interface has the signal Return type:bool

interfaceType

This is used by regex for variable substitution so cannot have underscores

Returns:type of this interface Return type:str

class sonar.interfaces.base_interface.InterfaceCore

Bases: sonar.base_types.SonarObject

Defines the core properties of the interface that are used internally

args = {}

classmethod asdict()

Placeholder function that’s overridden in the child classes

Raises:NotImplementedError – This function should not be called

static import_packages_global()

Specifies any packages that must be imported once per testbench

Returns:Packages to be imported Return type:str

signals = {}

classmethod write_cpp(packet, identifier='NULL')

Write one line of the C++ data file

Parameters:packet (dict) – The command to write Returns:The command as a line for the data file Return type:str

classmethod write_sv(packet)

Write one line of the SV data file

Parameters:packet (dict) – The command to write Returns:The command as a line for the data file Return type:str

sonar.interfaces.base_interface.to_upper_case(signals)

For a dictionary of signals, change all the names to upper case

Parameters:signals (dict) – Dictionary of Signals Returns:Updated dictionary Return type:dict

Module contents