transaction_translator interface is implemented by
objects which would like to inspect and/or modify transactions
before forwarding them to devices or address spaces. In Simics documentation,
such objects are usually called translator objects or, simply, translators.
In comparison with the simpler translator interface,
the transaction_translator interface provides
an opportunity to inspect/modify transactions. We recommend
using the translator interface when the additional
functionality is not needed.
The interface has one method called translate. The arguments
passed to this method describe the access and thus allow
a translator to perform a proper translation. Here is a short description of
the translate method's parameters:
- addr is an address of the access;
- access is a bitmask specifying all requested
access types;
- t is a transaction;
- callback is a callback that should be called by
the object implementing the interface;
- data should be passed to callback
as it is when the callback is invoked by the translator object.
All these arguments are described in detail below.
The transactions done by the translators may be cached by Simics.
To ensure efficient flushing of Simics internal caches we recommend
that the objects implementing the transaction_translator
interface implement also the translation_flush interface.
The absence of the translation_flush interface may lead to
a substantial decrease of simulation speed.
Whenever a previously returned translation becomes invalid the translator objects are expected to use either SIM_map_target_flush (preferably) or SIM_translation_changed function to ensure that Simics will flush any cached translations. Please refer to the documentation of these functions for the information about how they should be used.
An object implementing the transaction_translator interface
should invoke callback passing to it tree arguments:
translation, transaction
and data. The translation argument
describes the translation that was done, i.e. the transaction destination.
Please refer to the translation_t documentation
for the complete description.
The transaction argument is either the original
transaction passed to the transaction_translator interface
or, if a translator object wants to append atoms to the t
transaction, a new transaction created via transaction chaining.
The transaction chaining is described in detail in the "Transaction Chaining"
chapter of the Model Builder's User Guide. Finally, the
data argument is a parameter which should be passed as it is
when callback is invoked by the translator object.
Simics will report an error if a translator object doesn't invoke
callback from the translate method
of the transaction_translator.
If it is needed, a translator may route transactions based on the value of
certain transaction's atoms. The initiator atom
is a good example of such an atom. Please note that not all atoms are suited
for routing transactions based on their value. This should be checked
in the documentation for the specific atom.
The callback function returns transaction completion status.
This status should be usually returned as it is by the translate
method. The status value is also needed in the case when a translator object
appends atoms via transaction chaining with a non-zero
completion atom. In that case the returned status should be used
when the SIM_monitor_chained_transaction function is called.
Please note that memory accesses in Simics are not always issued with
the transactions of the transaction_t type.
For example, memory access can be done with the use of
the legacy generic_transaction_t type.
One more such example is lookup accesses which are done
via the direct_memory_lookup interface. All such accesses
are converted, if it is needed, and presented to the translator object via
the t parameter.
The access parameter specifies access
types in the form of a bitmask. Its value may be of interest
if a translation is done differently based on whether it is
a read, write or instruction fetch transaction. It can be noted
that a transaction itself already contains information
whether it is a read, write or an instruction fetch.
Usually, the access parameter just reflects that value.
However, for lookup accesses done via
the direct_memory_lookup interface
the access argument may have more bits set. If a translation
which are valid for all requested accesses cannot be performed, then
a null value should be set in the target of
the translation
argument passed to callback. In this case, the requestor is
expected to repeat the interface call with just a single bit set
in the access mask, e.g. Sim_Access_Read.
SIM_INTERFACE(transaction_translator) {
exception_type_t (*translate)(
conf_object_t *NOTNULL obj,
uint64 addr,
access_t access,
transaction_t *t,
exception_type_t (*NOTNULL callback)(
translation_t translation,
transaction_t *transaction,
cbdata_call_t data),
cbdata_register_t data);
};
#define TRANSACTION_TRANSLATOR_INTERFACE "transaction_translator"