Z01X Related

The zoix.py module contains utilities to perform calls to VC-Z01X It is based on the subprocess package and depends heavily on user-defined parameters.

ZoixInvoker

This class is the responsible for issuing calls to VC-Z01X. It offers utilities to compile HDL sources in VCS, logic simulate these sources, and finally, fault simulate the sources in Z01X. It assumes a pre-existing tested and working VC-Z01X environment for a DUT and all function arguments are passed as variadic args and keyword arguments. The reason for this design choice is to abstract as much as possible from any version-specific niece that VC-Z01X might have. Hence, we offer this layer of abstraction and leave it to the user to specify compilation and simulation isntructions to be executed in the methods of the ZoixInvoker e.g., by the TOML configuration file.

class zoix.ZoixInvoker

Bases: object

A wrapper class to be used in handling calls to VCS-Z01X.

compile_sources(*instructions: str) → Compilation

Performs compilation of HDL files

Parameters:

instructions (str) – A variadic number of bash shell instructions

Returns:

A status Enum to signify the success or failure of the compilation.

• ERROR: if any text was found in the stderr stream during the execution of an instruction.

• SUCCESS: otherwise.

Return type:

Compilation

static execute(instruction: str, timeout: float | None = None) → tuple[str, str]

Executes a bash instruction and returns the stdout and stderr responses as a tuple.

Parameters:

instruction (str) – The bash instruction to be executed.

Returns:

The stdout (index 0) and the stderr (index 1) as strings.

Return type:

tuple(str, str)

fault_simulate(*instructions: str, **kwargs) → FaultSimulation

Performs fault simulation of a user-defined firmware.

Parameters:

• instructions (str) – A variadic number of shell instructions to invoke Z01X.

• kwargs –

  User-defined options for fault simulation control.

  • timeout (float): A timeout in seconds for each fsim instruction.

  • allow_regexs (list[re.Pattern]): Series of regexps to look for in stderr and allow continuation without raising any error messages.

Returns:

A status Enum which is:

• TIMEOUT: if the timeout kwarg was provided and some instruction exceeded it.

• FSIM_ERROR: if the stderr stream contains text during the execution of an instruction.

• SUCCESS: if none of the above.

Return type:

FaultSimulation

logic_simulate(*instructions: str, **kwargs) → LogicSimulation

Performs logic simulation of user-defined firmware and captures the test application time.

A timeout value must be specified in order to avoid endless loops that will hang the program. There are two important kwargs that the user must specify. The success regexp and the tat regexp. During a logic simulation, the simulator typically stops when a $finish call is met. However, in a non-trivial DUT case like e.g., a processor, there are many things that may go wrong like for instance an out-of-bounds read or write from/to a memory. In that case, it is up to the designer to handle accordingly the situation e.g., issue a $fatal call. Which means, that in order to be accurate and know whether the logic simulation terminates gracefully, some sort of $display must be specified -or- at least the $finish statement must be invoked from the correct place. For this reason, the success regexp is required in order to know that not only the logic simulation ended but that it also ended without causing any kind of violation in the DUT.

When it comes to the tat regexp, this can be either a custom message again issued by the testbench or the time of the simulation that the correct $finish statement was issued. It is up to the user to specify it. However in order for the logic simulation to be considerred successful the success regexp AND the tat regexp must match something.

Parameters:

• instructions (str) – A variadic number of bash instructions

• kwargs –

  User-defined options needed for the evaluation of the result of the logic simulation.

  These options are:

  • timeout (float): A timeout in seconds to be used for each of the executed logic simulation instructions.

  • simulation_ok_regex (re.Pattern): A regular expression used for matching in every line of the stdout stream to mark the successful completion of the logic simulation.

  • test_application_time_regex (re.Pattern): A regular expression used to match the line that reports the test application time from the simulator.

  • test_application_time_regex_group_no (int): The index of the capture group in the custom regular expression for the TaT value. Default is 1, corresponding to the success_regexp group.

  • tat_value (list): An empty list to store the TaT value after being successfully matched with success_regexp. The list is used to mimic a pass-by-reference.

Returns:

A status Enum which is:

• TIMEOUT: if user defined timeout has been triggered.

• SIM_ERROR: if any text was found in the stderr stream during the execution of an instruction.

• SUCCESS: if the halting regexp matched text from the stdout stream.

Return type:

LogicSimulation

TxtFaultReport

It provides a parsing utility based on bracket-counting to extract sections from the textual fault report of Z01X (rpt file). Furthermore, it utilizes the supported grammars to extract and transform sections of the fault report to manageable objects and data structures. Also, it computes coverage formulas.

class zoix.TxtFaultReport(fault_report: Path)

Bases: object

Manages the VC-Z01X text report.

compute_coverage(requested_formula: str | None = None, precision: int = 4) → dict[str, float] | float

Manually computes the coverage based on the current fault report.

Parameters:

• requested_formula (str, optional) – The name of the coverage formula from the Coverage {} section of the fault report. Defaults to None.

• precision (int, optional) – The requested float precision. Defaults to 4.

Returns:

If no formula name is provided, returns a dictionary mapping formula names to their corresponding evaluated coverage values as floats. If a formula name is specified, returns only the evaluated value for that formula.

Return type:

dict[str, float] | float

extract(section: str) → str

Extracts a section of the fault report.

Parameters:

section (str) – The case-sensitive section name. E.g., Coverage, FaultList

Returns:

A newline-joined string of the extracted section (section name included).

Return type:

str

Raises:

ValueError – If section does not exist in the fault report.

update()

Update and parse all sections once the fault report file is available.

Fault

This class is used to represent a prime fault. Once again, in order to abstract as musch as possible, all attributes of the Fault class are passed as keyword arguments. Hence, they can be arbitrarily set.

With that said, each fault has two default, static attributes set by the constructor. These two attributes are the equivalent_to which expects another Fault type and by default is set to None and equivalent_faults which is an integer set to 1 counting the number of equivalent faults mapped to the current fault. These attributes can be accessed and modified in an ad-hoc manner.

class zoix.Fault(**fault_attributes: dict[str, Any])

Bases: object

Generic representation of a prime fault

Each prime fault has two static attributes which are: -equivalent_faults (int): Corresponds to the total number of faults equivalent to this fault. Defaults to 1 i.e. itself. -equivalent_to (Fault): A reference to the primary fault with which the current fault is equivalent. If the current fault is prime. Defaults to None.

When a fault is constructed it corresponds to a prime fault. It is up to the user to resolve any fault equivalence by modifying the aforementioned attributes.

cast_attribute(attribute: str, func: callable) → None

Casts the type of the internal attribute

Parameters:

• attribute (str) – The requested attribute of the fault to be casted.

• func (callable) – A function to cast the fault attribute.

Returns:

None

Raises:

• KeyError – If the requested attribute does not exist.

• ValueError – If the cast cannot be performed e.g., when int('a').

get(attribute: str, default: str | None = None) → str | Any

Generic getter method for arbitrary attribute.

Parameters:

• attribute (str) – The requested attribute of the fault.

• default (str | None) – A default value to be used as a guard.

Returns:

The fault attribute. If no cast has been performed on the attribute then the default type is str.

Return type:

str | Any

is_prime() → bool

Checks whether the fault is a prime fault, i.e., is not equivalent to any other fault.

Returns:

True if fault is prime. False otherwise.

Return type:

bool

set(attribute: str, value: Any) → None

VC-Z01X Status Enumerators

class zoix.Compilation(value)

Bases: Enum

Statuses for the VCS compilation of HDL sources.

ERROR = 'ERROR'

SUCCESS = 'SUCCESS'

class zoix.LogicSimulation(value)

Bases: Enum

Statuses for the simv logic simulation of a given program.

SIM_ERROR = 'ERROR'

SUCCESS = 'SUCCESS'

TIMEOUT = 'TIMEOUT'

class zoix.FaultSimulation(value)

Bases: Enum

Statuses for the Z01X fault simulation.

FSIM_ERROR = 'ERROR'

SUCCESS = 'SUCCESS'

TIMEOUT = 'TIMEOUT'