KnowHow
Free Technical Resources

Introductory Video

In this brief video, John Aynsley, Doulos CTO, gives an introduction to the TLM-2.0 protocol checker.

Introduction

Class tlm2_base_protocol_checker is a SystemC module that can be instantiated in-line between a pair of existing TLM-2.0 initiator and target sockets. It performs a comprehensive set of checks to help achieve compliance with the TLM-2.0 Base Protocol. The Base Protocol represents the highest level of interoperability provided by the TLM-2.0 standard. Two models that are functionally compatible and that fully support the TLM-2.0 Base Protocol should be interoperable off-the-shelf without modification; at least, that has been the goal of the OSCI TLM Working Group. This checker is intended to help reach that goal.

This checker is specific to the Base Protocol. Any model that includes non-ignorable extensions to the Generic Payload or Base Protocol may cause the checker to fail. Any socket that uses some other protocol will fail to bind to the Base Protocol Checker.

This Base Protocol Checker is a dynamic checker, not a static checker or linting tool. Whether or not it uncovers errors in your model will depend on the transactions passed through it; there is no guarantee that errors in the source code of the model will actually be detected. Also, although this Base Protocol Checker performs a comprehensive set of checks, there are many errors that it will be unable to detect. For example, it cannot detect that a target correctly implements a read or write operation, or that an ignorable extension can indeed be ignored.

Class Definition

The public part of the class definition is shown here. The primary interface is a pair of initiator and target sockets that should be bound in-line between an existing pair of sockets:

template <unsigned int  BUSWIDTH = 32>
class tlm2_base_protocol_checker
: public sc_core::sc_module
, public tlm::tlm_fw_transport_if<tlm::tlm_base_protocol_types>
, public tlm::tlm_bw_transport_if<tlm::tlm_base_protocol_types>
{
public:

  // Instantiate and bind checker inline between an existing pair
  // of initiator and target sockets
  tlm::tlm_target_socket   <BUSWIDTH, tlm::tlm_base_protocol_types, 1>
    target_socket;
  tlm::tlm_initiator_socket<BUSWIDTH, tlm::tlm_base_protocol_types, 1>
    initiator_socket;

  SC_CTOR(tlm2_base_protocol_checker);

  // Access methods for num_checks count
  static void set_num_checks(sc_dt::uint64 n);
  static sc_dt::uint64 get_num_checks();
  ...
};

Instantiating Multiple Checkers

Isolated checkers can be bound anywhere along a transaction path, or multiple checkers can be bound at various points along a given transaction path. Instantiating multiple checkers in this way will increase the run-time overhead, but enables certain kinds of check that cannot be performed by isolated checkers. For example, multiple checkers can check that the response path is the reverse of the request path, or that an interconnect component does not modify the data array.

Given the following arrangement of an initiator, an interconnect, and a target:

Initiator *initiator;
Bus       *bus;
Memory    *memory;
...
initiator->socket.bind(bus->target_socket);
bus->initiator_socket.bind(memory->socket);

a pair of checkers might be instantiated and bound as follows:

tlm_utils::tlm2_base_protocol_checker<32> *checker1;
tlm_utils::tlm2_base_protocol_checker<32> *checker2;
...
initiator->socket.bind(checker1->target_socket);
checker1->initiator_socket.bind(bus->target_socket);
bus->initiator_socket.bind(checker2->target_socket);
checker2->initiator_socket.bind(memory->socket);

Turning Off the Checkers

The checks are relatively expensive, so that the run-time overhead will be noticable in a fast (loosely-timed) model. For this reason, the more time-consuming checks are switched off by default after the checkers have performed a given number of checks. The default number is 100,000 checks, but can be set by calling the method set_num_checks. This method may be called at any time the checkers are still running, but cannot be called once the checkers have stopped.

Checking can be turned off at any time by calling set_num_checks(0). This only deactivates the more time-consuming checks. There are still a few checks that will remain active anyway. Even when the checkers are deactivated they will still incur some CPU overhead because they intercept every passing method call. It is not possible to selectively deactivate certain checkers while leaving others active.

Checking can be turned on for the entire duration of simulation by calling set_num_checks( (sc_dt::uint64)(-1) ). (Well, assuming that less than 2^64 checks are required.)

The checkers are not particularly frugal with memory (you might even say they leak like a sieve), creating a copy of each transaction object they receive, together with copies of the data and byte enable arrays. The checkers have been designed for use with a transaction pool, where the total number of unique transaction objects is limited. Any negative effects from this memory consumption are mitigated by the fact that the number of checks is limited (unless the user deliberately removes the limit).

Error Reports

All errors are reported with the message type "tlm2_protocol_checker", and most are reported with a severity of SC_ERROR, a small minority being SC_WARNING. The behavior of the report handler can be overridden using standard features of IEEE 1666 SystemC:

sc_report_handler::set_actions("tlm2_protocol_checker", ...);

Each report includes a reference to the corresponding clause in the TLM-2.0 User Manual.

IEEE Std 1666-2011 / SystemC 2.3.x

The archive contains two versions of the protocol checker, one for SystemC 2.2.x / TLM-2.0.1, and a new, updated version for IEEE Std 1666-2011 as implemented in SystemC 2.3.x / TLM-2.0.2. The former version refers to paragraph numbers in the old OSCI TLM-2.0 LRM. The latter version checks the gp_option attribute and refers to paragraph numbers in IEEE Std 1666-2011.

Click here to download the source code. In exchange, we will ask you to enter some personal details. To read about how we use your details, click here. On the registration form, you will be asked whether you want us to send you further information concerning other Doulos products and services in the subject area concerned.

See also:   Complete AT Example

Back to the full list of TLM-2.0 Tutorials