Updated January 2013 for IEEE Std 1666-2011 / SystemC-2.3.x
"ST has used Doulos' TLM-2 checkers to validate our models and have found them to be very useful. Having been implemented by the writer of the TLM-2 user guide, we are confident that the checkers will become the TLM-2 Gold Standard and will contribute to improving the interoperability among models. This will have substantial benefit to the TLM ecosystem." Laurent Maillet-Contoz, STMicroelectronics, France.
"The protocol checker is extremely helpful to people, and because of John's deep understanding of the intention of the TLM-2.0 kit, I'm sure it will prove to be accurate. We will be including it in our code, as we think it will greatly assist people to debug their TLM-2.0 models." Mark Burton, GreenSocs.
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
