VVC_BROADCAST

The VVC_BROADCAST command parameter can be used when a command is to target all VVCs within the test environment, reducing the number of command instructions needed in the testbench.

-- Examples:
enable_log_msg(VVC_BROADCAST, ALL_MESSAGES); -- enable logging for all VVCs
await_completion(VVC_BROADCAST, 10 us); -- wait for all VVCs to complete

ALL_INSTANCES

The ALL_INSTANCES command parameter can be used when a command is targeting all instances of a VVC within the test environment, reducing the number of command instructions needed in the testbench.

-- Examples:
enable_log_msg(SBI_VVCT, ALL_INSTANCES, ALL_MESSAGES); -- enable logging for all instances of SBI_VVCT
await_completion(SBI_VVCT, ALL_INSTANCES, 100 ns); -- wait for all instances of SBI_VVCT to complete

ALL_CHANNELS

The ALL_CHANNELS command parameter can be used when a command is targeting all channels of a VVC within the test environment, reducing the number of command instructions needed in the testbench.

-- Examples:
enable_log_msg(UART_VVCT, 1, ALL_CHANNELS, ALL_MESSAGES); -- enable logging for all channels of UART_VVCT instance 1
await_completion(UART_VVCT, ALL_INSTANCES, ALL_CHANNELS, 100 ns); -- wait for all instances and channels of UART_VVCT to complete

C_VVCT_ALL_INSTANCES

See description above. C_VVCT_ALL_INSTANCES = ALL_INSTANCES.

t_vvc_result

The common type t_vvc_result is always defined with the max length of fetched data that the VVC supports (see the definition of t_vvc_result in its corresponding vvc_cmd_pkg.vhd). Therefore it is recommended to define the range of the desired data output after the fetch_result method has been completed.

--Example:
variable v_data     : t_vvc_result;
variable v_data_out : std_logic_vector(7 downto 0);

And then:

fetch_result(SPI_VVCT, 1, v_cmd_idx, v_data, "Fetching result of SPI receive operation");
v_data_out := v_data(7 downto 0);

shared_<vvc_name>_vvc_config

From the VVC configuration shared variable, one is given the ability to tailor each VVC to one’s needs, in addition to access the BFM configuration record via the bfm_config identifier. In addition to BFM configuration possibility, the configuration settings consist of command and result queue settings, BFM access separation delay and a VVC dedicated message ID panel. Note that some BFMs require user configuration, e.g. the bit_time setting in serial interface BFMs.

shared_sbi_vvc_config(1).inter_bfm_delay.delay_type := TIME_START2START;
shared_uart_vvc_config(RX,1).bfm_config.bit_time := C_BIT_TIME;

shared_<vvc_name>_vvc_status

The VVC status shared variable provides access to the command status parameters for each of the VVCs, such as the current and previous command index, and the number of pending commands in the VVCs command queue. This provides a helpful tool, e.g. when synchronizing VVCs in the test sequencer using the await_completion() method.

v_num_pending_cmds := shared_sbi_vvc_status(1).pending_cmd_cnt;
v_current_cmd_idx  := shared_uart_vvc_status(TX,2).current_cmd_idx;
v_previous_cmd_idx := shared_uart_vvc_status(TX,2).previous_cmd_idx;

shared_<vvc_name>_transaction_info

global_<vvc_name>_vvc_transaction_trigger

Global trigger signal for when a VVC has updated its shared variable with VVC transaction info. See Distribution of Transaction Info - From VVCs and/or Monitors for more details.

shared_<vvc_name>_vvc_transaction_info

Shared variable providing access to Transaction Info VVC instances. See Distribution of Transaction Info - From VVCs and/or Monitors for more details. Available information is dependent on VVC type and typical information is:

operation          : t_operation;                                            -- default NO_OPERATION
data               : std_logic_vector(C_VVC_CMD_DATA_MAX_LENGTH-1 downto 0); -- default 0x0
vvc_meta           : t_vvc_meta;                                             -- default C_VVC_META_DEFAFULT
transaction_status : t_transaction_status;                                   -- default INACTIVE

Local sequencer requirements

The following requirements should be followed when making local sequencers (basically any VVC command resulting in more than one base transaction):

1. If Transaction Info is supported, then both the leaf transaction and the compound transaction info should be updated (the latter is not required).

2. The sequence should be handled directly inside the VVC executor - and not inside the BFM (otherwise updating the leaf transactions for Transaction Info could be difficult).

3. It should be possible to terminate the sequence immediately after each leaf (or base) transaction - on request from the central sequencer issuing a terminate_current_command() or terminate_all_commands().

Property check configuration

In UVVM, turning checkers on and off is controlled by the VVC configuration (see shared_<vvc_name>_vvc_config), and often additional control of the checker behavior is also required. Thus, it is recommended to include the checker control for each individual check in a dedicated sub-record. An example on this (for the UART VVC) is shown below. See UART VVC for implementation.

.bit_rate_checker              -- Sub-record containing all control of the property checker behavior
    .enable      boolean       -- Enables or disables the complete bit rate checker
    .min_period  time
    .alert_level t_alert_level

For this example, the bit rate checker inside the UART_VVC RX will trigger on changes on the DUT TX and execute the check if enable is TRUE.

Setting up the configuration

The bit rate checker configuration may be changed directly from the sequencer via the shared variable VVC configuration.

UVVM VIP randomization principles

Randomization may of course be applied with no limitations in a UVVM based testbench. For UVVM VIP however, we recommend the same general approach as for error injection randomization:

1. No randomization of data inside BFMs as this would affect the DUT behavior or output (and a monitor would be required to check the actual DUT stimuli). Hence BFM procedures should only be called with explicit data.

2. It is recommended that more advanced VVCs include functionality for randomization of data - in order to distribute this away from the test sequencer and increase the re-use value of a VVC. Thus, a VVC may be told to apply random data, in which case the VVC will randomly generate data according to a given profile (e.g. uniform) and provide that data to the interface via the BFM call. The profile and constraints will depend on the needs and the VVC implementation

Data randomization in BFMs

There is no data randomization inside a normal BFM, for the reason given above.

Data randomization in VVCs

A VVC may be commanded to generate constrained random data, where data in this sense could also be addresses, lengths, etc. Typically such commands would allow flexibility for the number of accesses and other important aspects - like scoreboards, common buffers, files, etc. A few randomization profiles have been predefined both as typical use cases and as examples for future extensions, when needed. The profile names are defined in the type t_randomisation, which is declared in the adaptations_pkg to allow users to add more profiles.

Note that the randomization seeds are initialized with a unique string assigned to each VVC. These seeds are automatically updated when random data is generated.

Managing randomization seeds in BFMs

Flow Control signals (e.g. valid and ready) can be configured to be randomly de-asserted in some BFMs (e.g. AXI-Stream and Avalon-ST). The randomization parameters in the BFM configuration determine the low duration and the probability of signal de-assertion. The random() methods described in Basic Randomization are used to generate random values for these parameters. To ensure that the tests are repeatable and produce consistent results, the randomization seeds must be controlled. A standard dictionary-like linked list is implemented for this purpose. The seeds are managed using the protected type t_seeds, declared in protected_types_pkg.vhd. This type consists of the t_seeds_item record type, which holds the seeds, and an access type that points to a dynamically allocated t_seeds_item. The seeds are stored in a record using a unique string (scope and instance_name) assigned to each BFM procedure as keys. To facilitate seed management, two subprograms are declared in the t_seeds protected type:

set_rand_seeds()- sets randomization seeds from a string.

update_and_get_seeds()- updates and get the seeds from the linked list.

A global shared variable shared_rand_seeds_register of type t_seeds is declared in global_signals_and_shared_variables_pkg.vhd to allow common access to the seeds from different BFM procedure calls, as shown below.

shared variable shared_rand_seeds_register : t_seeds;

The randomization steps used to control the seeds in BFMs are as follow:

1. When a BFM procedure (e.g. axistream_transmit() / axistream_receive()) is invoked for the first time, there is no entry for the BFM in the list. Generate seeds based on scope and instance_name using the set_rand_seeds() method. Store the generated seeds in the linked list, with scope and instance_name as keys.

2. Generate a random value using the random() procedure defined in the methods package.

3. When the same BFM procedure is invoked again, the previously stored seeds can be retrieved with scope and instance_name as keys. Update the seeds and generate a new random value.

The handling of randomization seeds is hidden from the user and performed automatically. Therefore, the user does not require to change or modify testbenches to control the randomization seeds. If a new BFM requires this functionality, it only needs to invoke the update_and_get_seeds() procedure from the global shared variable with suitable parameters and use the random() procedure with the generated seeds whenever a randomized method is used, as shown below. Note that the maximum length of the instance_name is defined by C_RAND_MAX_INSTANCE_NAME_LENGTH in adaptations_pkg.

-- Search the randomization seeds register with the scope and instance_name attribute as keys. The updated seeds are stored in v_seeds.
shared_rand_seeds_register.update_and_get_seeds(scope, v_seeds'instance_name, v_seeds);
random(1, config.valid_low_max_random_duration, v_seeds(0), v_seeds(1), v_valid_low_duration);

Purpose

By enabling the distribution of transaction info, models or any other parts of the testbench can see exactly what accesses have been made on the various interfaces of the DUT, so that the expected DUT behavior and outputs may be checked. Let us illustrate this with a really simple testbench scenario to verify a UART peripheral with an AXI-lite register/CPU interface on one side and the UART RX and TX ports on the other side. The test sequencer may command the AXI-lite BFM or VVC to write a data byte into the UART TX register, and then it must be checked that the data byte is transmitted out on the DUT TX output some time later.

1. A simple testbench approach could be to have the test sequencer also telling the receiving UART BFM or VVC exactly what to expect. This is a straightforward approach, but requires more action and data control inside the test sequencer. This could of course all be handled in a super-procedure, but for any undetermined behavior inside the BFM or VVC, like random data generation or error injection, that would not work. See Figure 3.

2. A more advanced approach is to have a model overlooking the DUT accesses, generate the expected data and tell the receiving BFM or VVC to check for that data. See Figure 4.

3. An even more advanced approach would be to use a Scoreboard to check received data (from DUT via VVC) against expected data from a model. See Figure 5.

However, for the two latter approaches the model needs information about exactly what happened (the transaction) on the various DUT interfaces, so that it can generate the correct expected data. For the model it doesn’t matter if the transaction info comes from a Monitor or from a VVC, as long as the information is correct.

The model could of course look at the interfaces and analyze the actual transactions, but distributing this task to the VVC or Monitor makes the testbench far more structured and significantly improves overview, maintenance, extensibility and reuse – at least for anything above medium simple verification challenges.

Another purpose of providing transaction information is for progress viewing and debugging – typically via the wave view or simulation transcripts.

Transaction definitions

By transactions we normally talk about a complete end to end transfer of data across an interface. This could be anything from a simple write, read or transfer of a single word - to a complete packet in a packet-oriented protocol like Ethernet. The word transaction is however also used for both sub-sets and super-sets of this – depending on the protocol and even on how we want to control our system or testbench. In order to communicate properly and to assure that transactions are properly understood, the following terms are defined:

• Base transaction (BT) is the lowest level of a complete transaction as allowed from the central sequencer. E.g. AXI-lite, UART, Ethernet and AXI-Stream transactions.

• Sub-transaction (ST) is the lowest level of an incomplete transaction as allowed from a BFM. The sub-transaction as such is complete seen from a handshake point of view, but the transfer of data is not complete. A split transaction protocol will typically have sub-transactions. E.g. Avalon Read Request and Avalon Read Response.

• Leaf transaction (LT) is not a transaction type in itself, but is the lowest level of complete or incomplete transaction defined for a given protocol. I.e. a sub-transaction when this is defined for a given protocol, otherwise a base transaction. This definition is needed in order simplify various explanations. E.g. for Avalon: LT = the sub transactions, and for UART, SBI or Ethernet: LT = the base transactions (as no sub-transaction exist for these protocols)

• Compound transaction (CT) is a set of transactions or other methods or statements that as a total is doing a more complex operation. A compound transaction involves calling multiple base transactions. E.g. sbi_poll_until() or a UART transmit of N consecutive bytes. No compound transaction needs to be defined.

Transaction information

Information about the above transactions is typically provided to a model in the test harness. Depending on whether the transaction info is provided from the VVC or Monitor, different types of information will be available. Common for both is that they always provide info about the operation (read, write, transmit, etc.) and often also any other protocol specific info. For a UART this could be data and parity, for an SBI it could be address and data, and for Ethernet, the packet fields.

This minimum is normally what the Monitor can provide from just analyzing the interface, and this is also normally enough for a model to generate expected DUT outputs. The VVC on the other hand, can provide more info, which could be useful for instance for progress viewing and debugging.

The transaction information is organized as a transaction record with some predefined fields as shown below. Table 1 shows the general transaction record, whereas table 2 shows a concrete example for the SBI.

Note that for a given interface/protocol, the VVC and the Monitor will use the same interface dedicated transaction record type - with some fields potentially unused.

Other interfaces will of course have different protocol dedicated fields, or even a complete protocol dedicated sub-record (e.g. for Ethernet packet fields).

Transaction Info transfer

In order to reduce the number of signals from a VVC or Monitor, all possible simultaneous transactions (and their transaction records) are collected into a single transaction group record. For an SBI interface, this will consist of a BT record and potentially a CT record. Whereas for an Avalon, it will in addition also consist of two ST records, because for instance a read request may be active at the same time as a read response. (And the sub-transactions are part of a base transaction and may also be part of a CT).

Table 3 shows the maximum transaction group record for an SBI, whereas Table 4 shows the maximum transaction group record for an Avalon MM. The bold CT is optional for both, and thus depends on whether CTs have been defined in the VVC. Multiple parallel STs may be written to the transaction group record simultaneously - as these are handled by different “threads” (concurrent statements like a process).

A Monitor cannot know about CTs, and thus a Monitor will never fill in that sub-record. A Monitor for a split transaction protocol (i.e. with multiple STs) may or may not provide BT info. If it does, this should normally be implemented in a higher level “wrapper”.

Transaction Info record signals

The Transaction Info record is provided out of the VVC and Monitor using sets of a global signal and a shared variable. These and all Transaction Info related VHDL types are defined in transaction_pkg.vhd, located in the VIP src folder (except for the t_transaction_status type, which is defined in types_pkg.vhd).

• Monitor trigger signal : global_<protocol-name>_monitor_transaction_trigger, e.g. global_uart_monitor_transaction_trigger

• Monitor shared variable : shared_<protocol-name>_monitor_transaction_info, e.g. shared_uart_monitor_transaction_info

• VVC trigger signal: global_<protocol-name>_vvc_transaction_trigger, e.g. global_uart_vvc_transaction_trigger.

• VVC shared variable : shared_<protocol-name>_vvc_transaction_info, e.g, shared_uart_vvc_transaction_info. The VVC is also responsible for filling out the vvc_meta record field.

Transaction Info signal and shared variable

A VVC or Monitor will trigger the global trigger signals listed in Transaction Info record signals when information of a new transaction info is made available. For a VVC, the transaction info can be available prior to the corresponding bus access, i.e. before calling the BFM method, or at the end of the access, i.e. when the BFM method has finished. The global trigger signal will be pulsed in both cases for a delta cycle. The VVC will set the transaction info back to default values immediately after the second trigger, but then without pulsing the global trigger signal.

For a Monitor, the transaction info will be made available immediately after a bus access is completed and then the global trigger signal will be pulsed for a delta cycle. The transaction info is valid when the global trigger signal is pulsed and it is set back to default values after a period of transaction_display_time, set in the Monitor configuration record, or when a new transaction is started.

Examples of Transaction Info Usage

All important information regarding a transfer is available in the transaction info and accessible in the test environment, and depending on one’s needs there are some recommended approaches for how to utilize the transaction info:

1. For complex protocols, where several combinations of data widths and others are possible, it can be complicated for a VVC to determine the structure and constraints of the scoreboard element. Examples of VVCs with such complex protocols are the AXI Stream and the Avalon ST VVCs. Setting up the Scoreboard and checking of received data against expected data for such complex protocols has to be done in the test harness, where the generic scoreboard is instantiated with a constrained scoreboard element and where a dedicated process monitors the VVC transaction info and checks received data with the scoreboard.

2. Transaction info can be used in a DUT Model process that monitors and decodes the actual transaction info data in the test harness. The DUT Model will use the decoded transaction info and add expected data to the VVC scoreboard on the DUT receiving side, e.g. to the sbi_vvc_sb while a SBI VVC is responsible for performing the DUT read access and check received data with sbi_vvc_sb. See Transaction Info Purpose, example C, for how a DUT Model will appear in the test harness.

p_vvc_sb_support : process
  -- transaction info handles
  alias sbi_transaction_trigger     : std_logic is global_sbi_vvc_transaction_trigger(C_SBI_VVC_1);
  alias sbi_transaction_info        : bitvis_vip_sbi.transaction_pkg.t_base_transaction is shared_sbi_vvc_transaction_info(C_SBI_VVC_1).bt;
  alias uart_rx_transaction_trigger : std_logic is global_uart_vvc_transaction_trigger(RX, C_UART_VVC_1);
  alias uart_rx_info                : bitvis_vip_uart.transaction_pkg.t_base_transaction is shared_uart_vvc_transaction_info(RX, C_UART_VVC_1).bt;
  -- helper variable
  variable v_sb_element             : std_logic_vector(C_DATA_WIDTH-1 downto 0);
begin
  while true loop:

    -- Wait for available transaction info
    wait until (sbi_transaction_trigger = '1') or (uart_rx_transaction_trigger = '1');

    if sbi_transaction_trigger'event then
      if sbi_transaction_info.operation = READ and sbi_transaction_info.transaction_status = COMPLETED then
        v_sb_element := sbi_transaction_info.data(C_DATA_WIDTH-1 downto 0);
        sbi_vvc_sb.check_received(C_SBI_VVC_1, v_sb_element);
      end if;
    end if;

    if uart_rx_transaction_trigger'event then
      if uart_rx_info.operation = RECEIVE and uart_rx_info.transaction_status = COMPLETED then
        v_sb_element := uart_rx_info.data(C_DATA_WIDTH-1 downto 0);
        uart_vvc_sb.check_received(C_UART_VVC_1, v_sb_element);
      end if;
    end if;

  end loop;
end process p_vvc_sb_support;

p_dut_model : process
begin
  while true loop:

    -- Wait for available transaction info
    wait until (global_sbi_vvc_transaction_trigger(C_SBI_VVC_1) = '1') or (global_uart_vvc_transaction_trigger(TX, C_UART_VVC_1) = '1');

    if global_sbi_vvc_transaction_trigger(C_SBI_VVC_1)'event then
      if shared_sbi_vvc_transaction_info(C_SBI_VVC_1).bt.operation = WRITE and shared_sbi_vvc_transaction_info(C_SBI_VVC_1).bt.transaction_status = IN_PROGRESS then
        uart_vvc_sb.add_expected(shared_sbi_vvc_transaction_info(C_SBI_VVC_1).bt.data(C_DATA_WIDTH-1 downto 0));
      end if;
    end if;

    if global_uart_vvc_transaction_trigger(TX, C_UART_VVC_1)'event then
      if shared_uart_vvc_transaction_info(TX, C_UART_VVC_1).bt.operation = TRANSMIT and shared_uart_vvc_transaction_info(TX, C_UART_VVC_1).bt.transaction_status = IN_PROGRESS then
        sbi_vvc_sb.add_expected(shared_uart_vvc_transaction(TX, C_UART_VVC_1).bt.data(C_DATA_WIDTH-1 downto 0));
      end if;
    end if;

  end loop;
end process p_dut_model;

-- define complex Avalon ST scoreboard type
type t_avalon_st_element is record
  channel_value : std_logic_vector(C_CH_WIDTH-1 downto 0);
  data_array    : t_slv_array(0 to C_ARRAY_LENGTH-1)(C_WORD_WIDTH-1 downto 0);
end record t_avalon_st_element;

-- create to_string() function for t_avalon_st_element
function avalon_st_element_to_string(
  constant rec_element : t_avalon_st_element
) return string is
begin
  return "channel value: " & to_string(rec_element.channel_value) & ", data: " & to_string(rec_element.data_array);
end function avalon_st_element_to_string;

-- define Avalon ST scoreboard
package avalon_st_sb_pkg is new bitvis_vip_scoreboard.generic_sb_package
generic map(t_element         => t_avalon_st_element,
            element_match     => "=",
            to_string_element => avalon_st_element_to_string);
use avalon_st_sb_pkg.all;

shared variable avalon_st_vvc_sb : avalon_st_sb_pkg.t_generic_sb;
...
p_vvc_sb_support : process
  -- transaction info handles
  alias avalon_st_transaction_trigger : std_logic is global_avalon_st_vvc_transaction_trigger(C_AVALON_ST_VVC_1);
  alias avalon_st_transaction_info    : bitvis_vip_avalon_st.transaction_pkg.t_base_transaction is
                                        shared_avalon_st_vvc_transaction_info(C_AVALON_ST_VVC_1).bt;
  -- helper variable
  variable v_sb_element : t_avalon_st_element;
begin
  while true loop:

    -- Wait for available transaction info
    wait until avalon_st_transaction_trigger = '1';

    if avalon_st_transaction_trigger'event then
      if avalon_st_transaction_info.operation = RECEIVE and avalon_st_transaction_info.transaction_status = COMPLETED then
        v_sb_element.channel_value := avalon_st_transaction_info.channel_value(C_CH_WIDTH-1 downto 0);
        v_sb_element.data_array    := avalon_st_transaction_info.data_array(0 to C_ARRAY_LENGTH-1)(C_WORD_WIDTH-1 downto 0);
        avalon_st_vvc_sb.check_received(C_AVALON_ST_VVC_1, v_sb_element);
      end if;
    end if;

  end loop;
end process p_vvc_sb_support;

UVVM error injection principles

Error injection may be applied randomly, with no limitations. For UVVM however, we recommend the following approach:

1. No randomization of behavior inside BFMs when this could affect the DUT behavior or output (and a monitor would be required to check the actual DUT stimuli). Hence BFM procedures should only be called with parameters explicitly defining the interface behavior (from the BFM side). Thus no parity error randomization inside. The only exception is for behavior that should not affect the DUT. Thus the position of a data bit error could be randomized inside the BFM.

2. It is recommended that more advanced VVCs include randomization - in order to distribute this away from the test sequencer and increase the re-use value of a VVC. Thus a VVC may be told to apply say 10% parity errors for a UART_VVC transmission into the DUT. In that case the VVC will randomly - with a 10% probability - inject a parity error into the DUT. As the VVC uses a BFM to handle the actual interface/protocol, this means that in 10% of the BFM transmit calls the VVC will request a parity error to be injected.

Error injection in BFMs

In order to simplify the specification of which errors to inject, the complete error injection specification is given as a sub-record inside the BFM configuration. E.g. inside the UART BFM configuration the following sub-record is defined - with fields specifying the error injection details (details given in UART BFM).

• error_injection (fixed name, but type will differ)

  • parity_bit_error (boolean)

  • stop_bit_error (boolean)

In order to initiate error injection, the BFM config record must be modified and included in the BFM procedure call.

Error injection in VVCs

In order to simplify the specification of which errors to inject, the complete error injection specification is given as a sub-record inside the VVC configuration (Note: not the BFM config). E.g. inside the UART VVC configuration the following sub-record is defined - with fields specifying the error injection details (Details given in UART VVC).

• error_injection

  • parity_bit_error_prob (real between 0.0 and 1.0)

  • stop_bit_error_prob (real between 0.0 and 1.0)

In order to initiate error injection, the VVC config record must be assigned the wanted values via the VVC configuration shared variable (see shared_<vvc_name>_vvc_config).

Naming and type usage

The error injection sub-record will be VVC and BFM dedicated, and thus any names and types may be used, and even sub-records under ‘error_injection’ is required. The VVC and BFM error injection records may differ or be the same. The only requirement is that readability is prioritized. Values should be checked against legal ranges or values.

To/from Buffer

UVVM has a global buffer that is divided into multiple smaller buffers that may be indexed and accessed from anywhere in the testbench. This functionality is described in UVVM Data FIFO. VVC commands requesting sourcing data from or sending data to these buffers use parameter TO_BUFFER or FROM_BUFFER, followed by the buffer index.

To Scoreboard

Scoreboards may be used anywhere inside the testbench, but for UVVM the following is recommended:

1. Use Scoreboards only on the destination side of the testbench, i.e. where data is received or fetched out of the DUT. E.g. for a UART on the DUT UART TX side (= UART_VVC RX side).

2. Every VVC may be connected to one single Scoreboard.

3. The Scoreboard instance number should be the same as the VVC instance number.

4. When using VVCs, make sure the VVC passes the received data to its Scoreboard, do not check the data in the VVC. E.g. for a UART_VVC, use the receive-command (and not the expect-command) to forward received data to the Scoreboard.

VVC commands requesting sending data to the Scoreboard use parameter TO_SB.

Data routing options

The profile names are defined in the type t_data_routing, which is defined in types_pkg.vhd

Entity

The interface to the DUT and any other needed I/O. The examples show DUT interfaces as single signals, records and records of records. This is optional.

Declarations

• Signals executor_is_busy and queue_is_increasing. Used as flags between the processes.

• Signal last_cmd_idx_executed. Stores the last command index executed by this VVC, necessary for the await_completion mechanism.

• Signal terminate_current_cmd. Command termination record (fields: set, reset, is_active). Where set and reset signal fields are used to toggle is_active. Used as inter process flags.

• Signal entry_num_in_vvc_activity_register. ID of the VVC after registering in the VVC activity register.

• Shared variable command_queue. Queue of commands to be executed in sequence towards the DUT.

• Shared variable result_queue. Queue of data received from the DUT which can be retrieved via the fetch_result command.

• The aliases are defined to allow common and simplified names.

• Signal entry_num_in_vvc_activity_register. ID of the VVC after registering in the VVC activity register.

Constructor

The constructor is run once only - immediately when starting the simulation. The procedure:

• Initializes VVC with BFM config and the queues with queue name.

• Allows constructor log for VVC info (using ID_CONSTRUCTOR), and VVC Queue info (using ID_CONSTRUCTOR_SUB).

The procedure will report alerts with severity TB_FAILURE if one of the following occurs:

• The instantiated VVC index is higher or equal to the maximum allowed number of VVC instances, given by C_MAX_VVC_INSTANCE_NUM in uvvm_util/src/adaptations_pkg.vhd

• UVVM has not been initialized.

Command Interpreter

Waits for commands from the central test sequencer distributed to this VVC, then puts the command on the queue for execution or immediately performs the required action - depending on command type. Afterwards, it acknowledges the command and waits for the next command from the sequencer.

Command Executor

Fetches commands from the command queue - if any. Then executes the command and fetches or waits for the next command in the command queue.

Command Terminator

The command terminator concurrent procedure sets the is_active flag based on the set and reset flags.

Clock period

Finds the clock period of the clk signal. This is only necessary when there is a ‘valid’ signal, such as tvalid in the AXI4-stream protocol, in order to ignore a false trigger of the unwanted transaction detection mechanism. (Only if the Unwanted transaction detection feature was selected).

Unwanted transaction

Monitors unwanted transaction from the DUT. For more information see Unwanted Transaction Detection. (Only if the Unwanted activity detection feature was selected).

Additional for multi-channel VVCs

Please note that we strongly recommend implementing the VVCs such that each leaf VVC handles one independent DUT communication thread (here: ‘channel’). No more; no less. This allows a single command queue and a single executor handling DUT communication. (Additional processes to handle other characteristics is fine. E.g., a parallel bit-rate check thread).

Note that SBI_VVC must handle both read and write accesses, but never simultaneously and always in the given order.

Multi-channel VVCs may be implemented in many different ways - depending on your preferences and priorities. Some examples are:

1. A unique VVC implementation per channel

   Unique VVCs may be used in order to omit the channel input, e.g. UART TX VVC and UART RX VVC. UART TX VVC would only contain TX specific BFM procedures, while UART RX VVC would only contain RX specific BFM procedures. With this approach the testbench sequencer calls would look like:

   a. uart_transmit(UART_TX_VVCT, 0, …)

   b. uart_receive(UART_RX_VVCT, 0, …)
2. A shared VVC implementation for all channels with usage restricted per instance

   A combined VVC with the implementation for all channels, but using separate instances for different channels, e.g. instance 0 for TX and instance 1 for RX. Using this approach the testbench sequencer calls would look like:

   a. uart_transmit(UART_VVCT, 0, …)

   b. uart_receive(UART_VVCT, 1, …)
3. A unique VVC implementation per channel with common VVC target parameter

   This approach uses unique VVC implementations for each channel, e.g. in uart_rx_vvc.vhd and uart_tx_vvc.vhd, but they both share the VVC target parameter, UART_VVCT. They both use the C_CHANNEL constant to specify their channel, i.e. TX or RX and are instantiated inside a wrapper uart_vvc.vhd. The VVCs have restrictions that ensure that e.g. the UART TX VVC can’t use the UART_RX BFM procedures, and vice-versa. Using this approach the calls would look like:

   a. uart_transmit(UART_VVCT, TX, 0, …)

   b. uart_receive(UART_VVCT, RX, 0, …)

When using multiple leaf VVCs it is recommended to use a wrapper architecture to encapsulate the channels. This way, it is possible to instantiate a single VVC rather than each VVC channel individually. For more information about the wrapper architecture, see the uart_vvc.vhd example in the bitvis_vip_uart/src/ directory.

t_operation

Contains all UVVM common operations, e.g. ENABLE_LOG_MSG and FETCH_RESULT, in addition to the VVC specific operations such as e.g. WRITE and READ. The VVC specific will have to be evaluated and potentially replaced when implementing a new VVC. The t_operation type is used when relaying commands from the sequencer to the VVC.

Constants

In this package we can define constants that need to be set for the entire VVC. In most VVCs this will include the C_VVC_CMD_STRING_MAX_LENGTH which determines the maximum size of msg variables in the VVC. It is also a good idea to declare constants for maximum VVC data/address bus sizes here. It will be possible to construct VVCs with bus sizes up to and including the sizes declared here.

t_vvc_cmd_record

Record type used for relaying a command from the testbench sequencer to the VVC. The record contains fields needed in the Common VVC Methods, and VVC specific fields needed to relay data to the VVC executor. There is a default constant for this type called C_VVC_CMD_DEFAULT in this package.

The VVC mandatory data fields are the following:

The VVC specific data fields should contain any data fields that the BFM procedures might need, e.g. data, address, timeouts etc.

Shared Variables

The shared variable shared_vvc_cmd of type t_vvc_cmd_record is used for relaying commands between sequencer methods and the VVC. It is default set to C_VVC_CMD_DEFAULT, which is also declared in this file.

The shared variable shared_vvc_response of type t_vvc_response is used for storing the result of a BFM procedure called by the VVC, so that the result can be transported from the VVC to for example a sequencer via fetch_result(). The record element result of type t_vvc_result contains the return value of the procedure in the BFM. It can also be defined as a record if multiple values shall be transported from the BFM.

The shared variable shared_vvc_last_received_cmd_idx is used to get last queued index from the VVC to the sequencer.

Functions

A custom to_string() function can be defined in this package if the t_vvc_result is a record type.

Constants and aliases

The vvc_methods_pkg contains a constant for the VVC name, e.g. “<NAME>_VVC”. There are also aliases created to make the code more readable.

<NAME>_VVCT

The <NAME>_VVCT signal (e.g. SBI_VVCT) is the VVC target record signal. The target type t_vvc_target_record is a record that contains the parameters needed to trigger a VVC, and to identify the correct target of a VVC command.

t_vvc_config

This type contains the needed configuration for setting up the VVC and BFM. In Bitvis VVCs the BFM configuration is encapsulated in a bfm_config record, of type t_<bfm_name>_bfm_config. This record is placed in this file and compiled into each VVC since the VVC/BFM configuration will differ for each VVC. The record contents are:

• inter_bfm_delay: A record containing the potential inter-bfm delay specifications, e.g. if BFM accesses shall be separated with a given time.

• cmd_queue_count_*: Command queue specifications. DEPRECATED, use instead entity generic constants.

• result_queue_count_*: Result queue specifications. DEPRECATED, use instead entity generic constants.

• bfm_config: A record containing all settings for the BFM, e.g. clock periods, message IDs etc.

• msg_id_panel: The message ID panel that the VVC shall use.

• unwanted_transaction_checking_enabled: Enable unwanted transaction checking. (Only if the Unwanted Transaction Detection feature was selected).

• unwanted_transaction_severity: Severity of alert to be initiated if unwanted transaction on the DUT outputs is detected. (Only if the Unwanted Transaction Detection feature was selected).

A constant C_<NAME>_VVC_CONFIG_DEFAULT is defined for this type to use as default value.

t_vvc_status

The optional status record is created in order for the testbench sequencer to have access to the status of the VVC. The status record can contain anything that is relevant for the outside, and it is recommended to have at least these three fields:

• current_cmd_idx: The current command index being processed in the executor.

• previous_cmd_idx: The previous command index being processed in the executor.

• pending_cmd_cnt: The number of pending commands to be processed by the executor.

A constant C_VVC_STATUS_DEFAULT is defined for this type to use as default value.

Shared Variables

A shared variable array shared_<name>_vvc_config of type t_vvc_config is declared and all elements are set to the default value.

A shared variable array shared_<name>_vvc_status of type t_vvc_status is declared and all elements are set to the default value.

The internal VVC Scoreboard <name>_vvc_sb is declared here as a shared variable. (only if the Scoreboard feature was selected).

VVC Dedicated Methods

The vvc_methods_pkg.vhd file also contains the VVC procedures that are called from the testbench sequencer. These procedures should reflect the procedures in the BFM, e.g. <name>_write or <name>_receive. The parameters of these procedures are mostly up to the user, but it is recommended that the BFM arguments that are rarely altered be placed into the bfm_config parameter, while the parameters that changes often are used as input arguments.

Since these VVC methods are reused for all instances of this VVC, it is necessary with some extra parameters in order to specify which VVC instance to forward the call to. This is done with the first two (or three) parameters:

signal   VVCT             : inout t_vvc_target_record;
constant vvc_instance_idx : in    integer;
constant channel          : in    t_channel;           -- Only if the VVC is multi-channel.

The method bodies are quite similar for all VVC commands:

1. First, the shared_vvc_cmd record is set to its default value, resetting the data from any potential previous command.

2. The general VVC fields (e.g. name and instance index) are set using the UVVM method set_general_target_and_command_fields().

3. The VVC specific fields are set in the shared variable shared_vvc_cmd. This means e.g. address and data fields.

4. The parent_msg_id_panel is used as the current msg_id_panel if the procedure was called from a hierarchical VVC.

5. The command is sent to all VVCs using the UVVM method send_command_to_vvc(VVCT).

All VVC instances and channels of this type receive the command, but only the VVC with the correct instance index, channel and name will accept it and acknowledge it.

Transaction info Methods

This package also contains two procedures, set_global_vvc_transaction_info() and reset_vvc_transaction_info(). These procedures are used to store the necessary information from the VVC command into the shared variable shared_<name>_vvc_transaction_info and trigger a pulse via the global signal global_<name>_vvc_transaction_trigger before a command is executed, and reset the information after it has finished executing. (Only if the VVC transaction info feature was selected).

t_operation

Contains all UVVM common operations, e.g. ENABLE_LOG_MSG and FETCH_RESULT, in addition to the VVC specific operations such as e.g. WRITE and READ. The VVC specific will have to be evaluated and potentially replaced when implementing a new VVC. The t_operation type is used when relaying commands from the sequencer to the VVC.

Constants

In this package we can define constants that need to be set for the entire VVC. In most VVCs this will include the C_VVC_CMD_STRING_MAX_LENGTH which determines the maximum size of msg variables in the VVC. It is also a good idea to declare constants for maximum VVC data/address bus sizes here. It will be possible to construct VVCs with bus sizes up to and including the sizes declared here.

Global signals and shared variables

The global signal global_<name>_vvc_transaction_trigger is used for indicating that a new VVC transaction info is available, meaning that a VVC command is about to be executed.

The shared variable shared_<name>_vvc_transaction_info is used to store the information of the VVC command being executed.

See Distribution of Transaction Info - From VVCs and/or Monitors for more details on the types used and basic concepts.

td_target_support_pkg.vhd

The UVVM VVC dedicated support package contains VVC support that is common for all VVCs, but needs to be compiled specifically into each of the VVC libraries.

td_vvc_entity_support_pkg.vhd

The VVC support package contains procedures that are compiled into and used in the VVC. This includes initializers for the executor and interpreter, and the interpreter procedures called interpreter_*, e.g. interpreter_fetch_result(). For more information about the interpreter_* procedures, please see Common VVC Methods. For more information about the other methods in this package, see <name>_vvc.vhd. In addition to the procedures, the td_vvc_entity_support_pkg.vhd also contains types for VVC labels.

Introduction

The VVC Generator is a Python 3 script that generates VVCs and accompanying support files, including the command package, methods package, a BFM skeleton and if necessary, a VVC wrapper for multi-channel VVCs.

Prerequisites

In order to run the script, it is necessary to have Python installed. To run the script from the command line, the python interpreter path needs to be added to the Path environmental variable. Only Python 3 is supported.

Running the script

The script can be run from the command line by running: python3 vvc_generator.py

The script will query the user for information about the VVC during the script:

1. First, it will ask for the VVC name. Please enter the VVC name without spaces. This name needs to be usable in the VHDL code, i.e. don’t use any other characters than “a-z”, “A-Z”, “0-9” or “_”. Any name must start with a letter.

2. Then, the script will ask if extended features should be added. If you type ‘y’ and Enter, it will ask whether you want to add the following features, which you can select by typing ‘y’ or ‘n’ and pressing Enter after each one:

   • Scoreboard

   • Transaction info

   • Unwanted transaction detection

3. Afterwards, the script will ask to select the number of concurrent channels to use in the VVC. Channels are a way of implementing more than one concurrent process which will use the BFM procedures. For example, when implementing a VVC for a bus which can only read OR write at the same time you would not need multiple channels. The SBI example VVC is an example of this. When implementing a full duplex VVC, e.g. UART, it would make sense to use multiple channels since TX and RX will operate concurrently. If you are implementing a VVC with concurrent channels, please type a number between 2 and 99 and press Enter. If not, press Enter to select the default ‘1’.

4. If you choose a number other than the default ‘1’, you will be asked to name each channel, one at a time. The channel names follow the same naming restrictions as the VVC name, stated in step 1. The script will generate new leaf VVCs for each channel name you enter, it will also generate a wrapper VVC that you can include in your test harness instead of including each leaf VVC individually. You must update the t_channel type in UVVM-Util adaptations_pkg if you use channel names other than RX and TX.

5. Finally, the script will ask:

   • If VVC has 1 concurrent channel: whether the VVC shall have multiple executors. If you type ‘n’ and Enter, the script will not need any further information. If you type ‘y’ and Enter, it will ask to type a number between 2 and 3 for the number of concurrent executors including the p_cmd_executor. Then, the script will ask to name each executor, one at a time. The executor names follow the same naming restrictions as the VVC name, stated in step 1.

   • If VVC has several concurrent channels: how many channels shall have multiple executors. If you want a single executor in each channel press Enter to select the default ‘0’, the script will not need any further information. Otherwise, type the number of channels which shall have multiple executors and press Enter. The script will then ask for each channel, whether it shall contain multiple executors for which you can answer ‘y’ or ‘n’. If you answer ‘y’ for a given channel, you will be then asked to type a number between 2 and 3 for the number of concurrent executors including the p_cmd_executor. Then, the script will ask to name each executor, one at a time. The executor names follow the same naming restrictions as the VVC name, stated in step 1.

When the script has gathered all the information it needs, it will generate the VHDL files in the ‘output’ directory. The naming of the files will be (<name> is the VVC name, and <channel> is a channel name):

• <name>_vvc.vhd

  • If this is a single channel VVC, this will be the main VVC file which includes all VVC logic (e.g. executor and interpreter)

  • If this is a multi-channel VVC, this file will be the wrapper for all the leaf VVCs.

• <name>_<channel>_vvc.vhd

  • These files will consist of the VVC implementation for each VVC channel (leaf VVC).

  • These files will only be generated if there are multiple channels for this VVC.

• <name>_bfm_pkg.vhd

  • This file is a suggested setup for the user BFM. It contains the necessary config records and types needed for UVVM to function properly. It does not contain any actual BFM procedures.

• vvc_cmd_pkg.vhd

  • This file contains the VVC operations and command records in which the VVC data is placed.

• vvc_methods_pkg.vhd

  • This file contains VVC configuration and status records, and examples of how to implement the VVC methods.

• vvc_context.vhd

  • This file contains the necessary packages that are used when simulating a VVC.

• vvc_sb_pkg.vhd

  • This file contains the Scoreboard package used for the internal VVC Scoreboard.

  • This file will only be generated if the Scoreboard feature was selected.

• transaction_pkg.vhd

  • This file contains the types used for the transaction info.

  • This file will only be generated if the Transaction info feature was selected.

Modifying the created VHDL files

After the script has completed, the files need some user interaction before they are ready to use. In all places marked with “--<USER_INPUT>” there will be instructions on how to properly modify the VVC for your BFM. Additionally, if you created a VVC with multiple channels, please make sure to add these channels to the t_channel type located in the UVVM-Util adaptations_pkg.vhd file. By default, this type only contains ‘TX’ and ‘RX’ channels but more can be added to fit any project.