SIM_free_map_target — free a map target
#include <simics/device-api.h> // in C
// always available in DML
void
SIM_free_map_target(map_target_t *mt);
import simics
simics.SIM_free_map_target(...)
Releases a map target and all associated resources. Safely does nothing if the argument is NULL.
Cell Context
SIM_map_target_flush — ensure that old translations are not used
#include <simics/device-api.h> // in C
// always available in DML
bool
SIM_map_target_flush(const map_target_t *NOTNULL mt,
uint64 base, uint64 size, access_t access);
import simics
simics.SIM_map_target_flush(...)
This API function is intended to be used for the implementation the translation_flush interface. The documentation for the translation_flush interface describes how to use this function for the interface implementation.
Additionally, this function can be used as a replacement for the SIM_translation_changed function to do a more fine-grain invalidation in the case when a previously returned translation becomes invalid.
When a previously returned translation becomes invalid the translator object should notify Simics which can have translations cached. To notify Simics the translator object can either do the call to the SIM_translation_changed function or, as a potential performance optimization, do a more fine-grain invalidation by using the SIM_map_target_flush function.
The translator object is expected to call the SIM_map_target_flush function for all targets of all previously returned translations which became invalid. If there are too many translations which are to be invalidated, then, performance-wise, it may be better just to do a single call to the SIM_translation_changed function. Also, if, during invalidation, any of the calls to the SIM_map_target_flush fails (i.e. the false value is returned by the function) then the translator is expected to call the SIM_translation_changed function which always succeeds.
Please note that there is no need to call the SIM_map_target_flush function for the translations which were tagged with the Sim_Translation_Dynamic flag. Either, no invalidation is needed for the destinations where nothing is mapped.
Cell Context
SIM_map_target_object, SIM_map_target_port, SIM_map_target_target — inspect a map target
#include <simics/device-api.h> // in C
// always available in DML
conf_object_t *
SIM_map_target_object(const map_target_t *NOTNULL mt);
const char *
SIM_map_target_port(const map_target_t *NOTNULL mt);
const map_target_t *
SIM_map_target_target(const map_target_t *NOTNULL mt);
import simics
simics.SIM_map_target_object(...)
simics.SIM_map_target_port(...)
simics.SIM_map_target_target(...)
Helper functions allowing inspection of the map_target_t objects.
Returns a Simics object, port, or chained target which was used for the creation of the mt map target, i.e., the respective argument passed to SIM_new_map_target when the map target was created.
Cell Context
SIM_new_map_target — create a map target
#include <simics/device-api.h> // in C
// always available in DML
map_target_t *
SIM_new_map_target(conf_object_t *NOTNULL obj, const char *port,
const map_target_t *chained_target);
import simics
simics.SIM_new_map_target(...)
Create and return a new map target. A map target can be viewed as an opaque representation of an object/interface pair which can function either as an endpoint for a memory transaction or as an address space where a memory transaction can be performed.
Map targets are usually used in conjunction with the translator interface and can represent anything which is mappable in a memory space, e.g., IO banks, RAM, ROM, memory spaces, port spaces, bridges, or translators. In order to get better performance, we recommend to allocate a map target once and reuse it rather than to allocate and delete it every time.
If the chained_target parameter is null, obj is searched for one of the following interfaces: ram, rom, translator, transaction_translator, transaction, io_memory, port_space, or memory_space. The interfaces are tried in the listed order, and the first interface found determines the “type” of the map target. For example, if obj implements both the io_memory and the translator interface, then the created map target will direct memory transactions to the translator interface.
If a map target argument is passed in the chained_target parameter, then obj must implement one of the following interfaces: translator, bridge, or translate. The chained target contains information about a secondary map target used either directly or indirectly by the interface. For objects implementing the translator interface, the chained target is passed as an argument to the translate method. For bridges, the chained target is the target which is accessed through the bridge. For objects implementing translate, the chained target is used as the target of the translation if the translate method returns null.
Information about the chained target is encoded in the created map target, but no direct references are kept to the argument. In other words, ownership is not transferred by this call and the caller is responsible for releasing
chained_targetas appropriate.
If a string is passed in the port parameter, then Simics looks for port interfaces instead of regular interfaces.
Returns a map target, encoding information about the object, the interface, and the chained target, if any. nullptr is returned if an exception was thrown.
SimExc_Lookup Thrown if no usable port interface was found.
Cell Context
SIM_free_map_target, map_target_t, SIM_map_target_object, translator
SIM_translation_changed — ensure that old translations are not used
#include <simics/device-api.h> // in C
// always available in DML
void
SIM_translation_changed(conf_object_t *NOTNULL obj);
import simics
simics.SIM_translation_changed(...)
Devices implementing the translator interface need to call this function whenever a previously returned translation becomes invalid; the only exception is if all invalid translations were tagged with Sim_Translation_Dynamic, in which case this is not necessary.
Failure to call this function will likely result in Simics continuing to use old translations, since those may have been cached internally.
The object implementing the translator should be passed in the obj parameter.
Cell Context