En este proyecto Iván crea un modelo de simulación genérico para un SoC (System on Chip) que permita realizar un análisis de prestaciones de distintas arquitecturas. Para esto usa, cómo no, TLM como se puede ver en la figura

The most elegant and easy way to do that is to create a special class for that task, that the other modules in the simulation can use to send their information and to be stores in disk. This can be achieved designing a singleton type class. This design pattern restricts the instantiation of a class to one single object. In our case, it will cause that all modules use the same object and log file.

To design a singleton class, we may take into account:

• The class itself creates the unique instantiation
• Declare the constructor as private so the class cannot be directly instantiated
• Allow to access to the object only through a class method

This can be done creating a class with a private constructor and a method that creates the object if it is not created yet and returns the reference to the object:


Log.h file

class Log
{

private:
Log(const char*);
static Log* m_pInstance;
std::ofstream m_stream;
...
}



Log.cpp file

Log* Log::m_pInstance = NULL;

Every module willing to use this class, may call it in the following way:

Log *my_log = Log::Instance();

To finish, we add some methods to store into a file the information we want to the Log class:

// Method to be called this way: my_log->SC_log("My log message");
void
Log::SC_log(std::ostringstream msg)
{
m_stream << "time " << sc_core::sc_time_stamp() << ": "
<< msg << std::endl; } // Method to be used inside C++ streams // we can write: my_log->SC_log() << name() << ". My log message" << std::endl;
std::ofstream&
Log::SC_log()
{
m_stream << "time " << sc_core::sc_time_stamp() << ": ";
return m_stream;
}

In the second case, the log file is in plain text with in each line the simulation time, the module name and the desired text. We can use some other library to generate a XML file or something more structured, but that is another post

And that’s all to have a common log file for all your simulations in a easy and elegant way.

First step is to download eclipse for C/C++ development from here.

Let’s begin: create a new C++ project

Next screen ask what type of eclipse project to use, we choose Executable and Empty Project

In the next screen, click on Advanced Settings, where we can add PATHs to SystemC library and header and TLM-2 header

Choose GCC C++ Compiler-> Preprocessor and we add SC_INCLUDE_DYNAMIC_PROCESSES in Defined symbols.

Then we choose Directories from  the same menu and we add the PATHs to the SystemC directory and TLM-2 directory (note the ending of each PATH)

Lastly, in GCC C++ Linker-> Libraries we add the PATH to the SystemC library (note that this path ends with /lib-linux/)

If all were fine, we will have the project created and ready to be used in the eclipse main screen:

Now, we can add new files to the project, just right click on the project name and pick new->source file o new-> header file

Fill the name of the new file (with extension), and we can start typing our code!

Thus, the only thing that varies in this way about the untimed mode is that in this case the function b_transport calls wait (), and thus allow the simulation time increases. This wait will be called by the target (inside the function b_transport) and models the time the device takes to respond to the transaction, for example the access time to a memory, or the time an I2C controller spent getting a data from a  external FLASH …

Retrieve the untimed example that we have nearly all we need.

Notice that the second parameter of the  b_transport function (type sc_time) remains zero. This parameter will help us if we use temporal decoupling, and that is where we indicate the time ahead of the simulation that takes the current transaction. That’s discussed in the next example of the series.

Note that this mode is mainly used because it is simple to use because we use the blocking method, and allows us to write down times, and therefore have a simulation that will give us information of how long it takes to run a process, how long implementation is needed even complete a task, etc..

And so far this “example”, you see there’s not much difference in code with  untimed, although there is in difference in concept and results to be obtained. The code you have it available here.

Target

In the target side we need to do two things: to register the function that publishes the pointer and fill the structure to publish the pointer.
To register the function:

target_socket.register_get_direct_mem_ptr(this, &Target::my_get_direct_mem_ptr);

and then write the function:

bool Target::my_get_direct_mem_ptr(tlm::tlm_generic_payload&, tlm::tlm_dmi& dmi_data)
{
dmi_data.allow_read_write();
dmi_data.set_start_address( 0 );
dmi_data.set_end_address( 10 );
dmi_data.set_read_latency( sc_time(10, SC_NS) );
dmi_data.set_write_latency( sc_time(10, SC_NS) );

dmi_data.set_dmi_ptr( reinterpret_cast ( &data[0]) );
return true;
}

Note that in this function we only fill the dmi_data structure, in this case telling that the memory region to use can be used to write and to read, what is its start and end address, and what read and write latency has. Those times can be used by the Initiator to simulate the access time if it like to. Lastly, we put the pointer to our memory region (in the example our data array), doing a C++ cast to unsiged char, that is the standard data type for all TLM-2.0

Later, to tell to Initiator that our module is DMI capable, we may mark a field in the transaction:

void Target::b_transport( tlm::tlm_generic_payload& transaction, sc_time& delay )
...
transaction.set_dmi_allowed( true );
...


This way, when a Initiator talks to our Target using a normal transaction (blocking or no-blocking) it can check that this Target is DMI capable.

Initiator

First step to use DMI in our Initiator is to write the function that the Target can use to tell to Initiator that the DMI pointer is not longer valid (for any reason)

So we add a new method to our Initiator class:


void Initiator::invalidate_direct_mem_ptr(sc_dt::uint64 start, sc_dt::uint64 end)
{
dmi_ptr_valid = false;
}


And we register it in the socket:

Initiator::Initiator(sc_module_name name_):
...
initiator_socket.register_invalidate_direct_mem_ptr(this, &Initiator::invalidate_direct_mem_ptr);
dmi_ptr_valid = false;
...
}


Later, the Initiator should first find if the Target device allows DMI (remember, it’s always optional). For that, Initiator may check a field of a transaction already responded by the Target. If Target allows DMI, would set to true that field.

...
if (transaction.is_dmi_allowed() ) {
dmi_ptr_valid = initiator_socket->get_direct_mem_ptr( transaction, dmi_data);
}
...


Note that in the previous two lines I made two different things: ask to the previous transactoin if Target allows DMI using is_dmi_allowed() method from transaction. Then, if Target allows it, we ask for the pointer, passing to Target the transaction with the address we want to access, and getting a true or false depending if DMI pointer is valid or not.

Following the example, if the Target allows DMI:

...
// El target acepta DMI, usamos el puntero directamente
unsigned char* dmi_ptr = dmi_data.get_dmi_ptr();
memcpy(dmi_ptr + (i*sizeof(data)), &data, sizeof(data) );
std::cout << "Initiator: " << sc_time_stamp() << "Escribiendo " << data << ". DMI OK" << std::endl;
...

It's time to get the pointer to the Target data using the method dmi_data.get_dmi_ptr() and later we can use that pointer usually.

Although I’ve left as is, it is not necessary to get the DMI pointer each time we are going to use it. We may ask for it once, and only check that it is still valid (in the example using the global variable dmi_ptr_valid) before we use it.

And that’s all for that example. It lacks the option to invalidate the pointer time to time in the Target. But it’s your homework . (If target wants to invalidate the DMI pointer, it only may call invalidate_direct_mem_ptr method of its socket).

Full example is in this link.

Time passed as parameter to the b_transport function marks start time of the transaction from the actual simulation time. In normal use, that time will be always 0 (unless we are using temporal decoupling). The target can use wait() inside the b_transport function to spend simulation time or can return
immediately and modify the time parameter to mark what time he spent. Later, the Initiator may call wait() for that time to increase simulation time.

That system allows the use of temporal decoupling. This mechanism allows parts of our design to run ahead the global simulation time until it needs to communicate with others system models, when it synchronizes again with the global simulation time.

When a temporal decoupled module in advanced time needs to communicate with other module we have two options:

• Assume a value for that communication
• Synchronize with whole system: wait for global simulation time arrives to its simulation time.

In this technique we use b_transport, filling the time parameter in the function call. In this parameter we annotate the time that our modules are ahead the simulation time, so the Target returns in the time parameter the offset time about simulation time. This means that adding that parameter time to actual simulation time give us the advanced simulation time for that Target.

And why is that for? Because with this technique we boost simulation speed, because SystemC simulator had less context switching and less overhead of guessing what module is next to simulate.

If we allow one module to run ahead with no limit, others parts of the simulation would never be simulated. To avoid that, TLM-2.0 introduces global quantum, that’s the maximum time that a module can be ahead global simulation time. That quantum can be modified in the simulation, and is a trade off between simulation speed and simulation accuracy. If this quantum is small, our simulation will have lot of synchronization (and lost of performance), but if we chose a big value for this quantum, simulation can be wrong.

The typical example of using temporal decoupling is the simulation of a system with a CPU, memory, one timer and some slow peripheral (a UART). Software running on the simulated CPU basically fetches instructions from memory and executes them in the CPU, and only interact with the rest of the system when timer triggers and interrupt (i.e. every 1 millisecond). In this case, the CPU module can run ahead global simulation until 1 millisecond, accessing directly to memory (using DMI). In this way, it’s possible to have a very detailed model of the timer without slowing simulation performance.

This mechanism can be started and stopped dynamically in the simulation. Can be useful to have a first part of the simulation very fast and unaccurate, and then disable temporal decoupling to have better accuracy losing some simulation performance.

Initiator

We shall start with the include’s


#include

#include "tlm.h"
#include "tlm_utils/simple_initiator_socket.h"


Firstly we include systemc and then tlm.h
Then we include the easiest socket for that example.
Now it’s time to declare the Initiator class


class Initiator: sc_module
{
public:
tlm_utils::simple_initiator_socket initiator_socket;
SC_HAS_PROCESS(Initiator);
Initiator(sc_module_name name_);

private:
void initiator_thread();
};


Lot of interesting things there: Firstly we define the Initiator class as dereived from sc_module. Following we declare a simple_initiator socket, we name it initiator_socket (very original…). To this template (we use a lot of them), we pass as parameter the class that contains it.

Later we declare the constructor with the macro SC_HAS_PROCESS().
Finally we declare a method to be SC_THREAD called initiator_thread (another original name).


...
double data;
tlm::tlm_generic_payload transaction;

sc_time delay = SC_ZERO_TIME;
...


In the SC_THREAD we declare a transaction variable and a sc_time variable to annotate times (it will be 0, but we must declare it). We also declare the variable data of type double that it will be data to send between modules.


transaction.set_data_length( sizeof(data) );
transaction.set_streaming_width( sizeof(data) );
transaction.set_byte_enable_ptr(0);
transaction.set_dmi_allowed(false);
transaction.set_response_status( tlm::TLM_INCOMPLETE_RESPONSE );
transaction.set_data_ptr( reinterpret_cast(&data) );


We fill the transaction fields, names are self-explanatory. I comment last lines.
We declare the transaction as TLM_INCOMPLETE_RESPONSE (standard says that).
Then we prepare data, for that, we put the transaction pointer to point to our data and do a C++ cast.
Note that the transaction only moves the pointer to data, not the data.


transaction.set_command( tlm::TLM_WRITE_COMMAND );
transaction.set_address( i );
initiator_socket-&>b_transport( transaction, delay);


These three lines fill the transaction fields to be a write, the address to write to, and the transaction is done using b_transport function call. To that function we pass the transaction and the time for that transaction (will be 0 for this example).


if (transaction.get_response_status() == tlm::TLM_OK_RESPONSE)


Next we check if Target answers with a TLM_OK_RESPONSE saying that transaction is done.
Example follows performing reads instead of writes (changing TLM_READ in the proper field, of course).

Target

Let’s see the Target code:


#include "tlm_utils/simple_target_socket.h"
...
tlm_utils::simple_target_socket target_socket;


We include the header for the Target socket and we declare a variable with the socket (with the class itself as template parameter).

Constructor code:


Target::Target(sc_module_name name_):
sc_module(name_),
target_socket("target_socket")
{
target_socket.register_b_transport(this, &Target::b_transport);
}


All seems normal, but the last line is a little tricky: here we register what function implements the method b_transport

Following, the function:


void Target::b_transport( tlm::tlm_generic_payload& transaction, sc_time& delay )
{
tlm::tlm_command command = transaction.get_command();
sc_dt::uint64 address = transaction.get_address();
unsigned char* data_ptr = transaction.get_data_ptr();
unsigned int length = transaction.get_data_length();
unsigned char* byte_enable_ptr = transaction.get_byte_enable_ptr();
unsigned int width = transaction.get_streaming_width();
double *my_data_ptr;
if (command == tlm::TLM_WRITE_COMMAND) {
data[address] = *(reinterpret_cast( data_ptr ) );
std::cout << "Target Write: " << sc_time_stamp() << ". Data: " << data[address] << std::endl;
} else {
my_data_ptr = reinterpret_cast(data_ptr);
*my_data_ptr = data[address];
std::cout << "Target Read: " << sc_time_stamp() << ". Data " << data[address] << std::endl;
}

transaction.set_response_status(tlm::TLM_OK_RESPONSE );
return;
}


First we collect all transaction parameters, and then if the transaction is read or write, we do the right copy between data.
Look again: transaction only contains the pointer to data, no the data, so we need to access to data using that pointer casted.
Finally, we put the status of the transaction to an OK (TLM_OK_RESPONSE) and return from the function.

Here ends the untimed example, easy!

Download full code example from en este enlace

Cuando usamos el canal normal para comunicar un Initiator con un Target usamos los interfaces que se definen en TLM2.0. De hecho, un Initiator crea una transacción y la pasa como argumento al método del interface (ya sea bloqueante o no). Este método lo implementa el Target que recibe la transacción y hace con ella lo que deba (la ejecuta). Este camino se conoce como forward path. Una vez el Target ha ejecutado la transacción, debe retornar al Initiator, y puede hacerse de dos formas distintas: a través de llamadas a métodos desde el Target al Initiator (a este camino se le llama el backward path; o usando el retorno del método del interface (se conoce como return path).

DMI

Existe un interface especial, llamado Direct Memory Interface que proporciona acceso directo a áreas de memoria dentro de un Target permitiendo acceder directamente, sin tener que pasar por todos los posibles componentes del sistema (bridges, árbitros, etc) usando un puntero a esa zona de memoria en lugar de acceder mediante llamadas a b_transport o nb_transport. Este interface especial esta pensado para acelerar las simulaciones donde se use masivamente accesos a memoria.

Debug Interface

Este intterface proporciona acceso inmediato y no intrusivo a un Target, de manera que cualquier lectura o escritura a través del Debug interface usará la misma estructura que el forward path, pero sin ningún tipo de delay o wait o notificación de evento, etc. Digamos que el resto del Target “no se entera” de que ha sido accedido.

Sockets

Para simplificar la interconexión entre módulos, TLM-2.0 nos ofrece sockets, que agrupa y “gestiona” tanto el forward como el backward path (y DMI y Debug Interface), habiendo sockets para Initiator (Initiator socket) y sockets para Target (Target socket). Desde TLM-2.0 se recomienda el uso de sockets en lugar de los interfaces por facilidad de uso y portabilidad.

TLM-2.0 define una serie de distintos sockets (convenience sockets) que implementen distintas características. Aquí va una tabla resumen:

Socket: Nombre de la clase y del socket

Registra Callbacks:Indica si el socket proporciona una función para registrar una función cualquiera como función transport.

Multiport: Si el socket permite conectar múltiples Initiators a un Target o al revés.

Conversión b/nb: el Target socket convierte las llamadas a b_transport a nb_transport (pasa una llamada bloqueante a no-bloqueante)

Tagged: Cada interface son etiquetados (tagged) para saber por qué socket han llegado

Binding: Si el socket permite conexión jerárquica, de manera que un Modulo puede tener “dentro” un Initiator y su socket conectado a éste.

En otra entrada del blog explicaremos cada uno de los sockets disponibles en el estandard.

Untimed

This mode uses only the blocking interface. This interface carries no information on response times, simply initiator uses the b_transport function to send data to target.

Is the most simple basis to use and simulate, and we can use to verify that the system is well designed and partitioned.

Loosely-timed

This mode also uses the blocking interface. Thus we have two points of time: b_transport function call and return (when it begins and when ends the transaction).

This mode allows use temporary decoupling. We can talk about this in another post, but the idea is that we have parts of our model and run “in his own time” until they need to synchronize with the rest of the model.

Approximately timed

This mode uses non-blocking interface, so you can record times in all phases of a transaction (typically a protocol is 3 or 4 phases).

This mode is the most detailed and therefore also be the slowest simulated.

These are the 3 ways that provide for the TLM-2.0 Standard (anyone needs something more?) And we talk in detail about each in future posts.