atom_id_t — predefined atom ids
#include <simics/device-api.h> // in C
// always available in DML
typedef enum {
Sim_Atom_Id_illegal = 0,
Sim_Atom_Id_list_end,
Sim_Atom_Id_flags,
Sim_Atom_Id_data,
Sim_Atom_Id_size,
Sim_Atom_Id_fill_value,
Sim_Atom_Id_initiator,
Sim_Atom_Id_user_data,
Sim_Atom_Id_completion,
Sim_Atom_Id_owner,
Sim_Atom_Id_memop,
Sim_Atom_Id_bytemap,
Sim_Atom_Id_trace_atom_access,
Sim_Atom_Id_target_type,
Sim_Atom_Id_pcie_type = 0x100,
Sim_Atom_Id_pcie_requester_id,
Sim_Atom_Id_pcie_msg_type,
Sim_Atom_Id_pcie_ecs,
Sim_Atom_Id_pcie_msg_route,
Sim_Atom_Id_pcie_pasid,
Sim_Atom_Id_pcie_at,
Sim_Atom_Id_pcie_error_ret,
Sim_Atom_Id_pcie_byte_count_ret,
Sim_Atom_Id_pcie_device_id,
Sim_Atom_Id_pcie_destination_segment,
Sim_Atom_Id_pcie_link_negotiation,
Sim_Atom_Id_pcie_link_flit_mode,
Sim_Atom_Id_pcie_ats_translation_request_cxl_src,
Sim_Atom_Id_pcie_ats_translation_request_no_write,
Sim_Atom_Id_pcie_ats_invalidate_request_itag,
Sim_Atom_Id_pcie_ats_invalidate_completion_itag_vector,
Sim_Atom_Id_pcie_ats_invalidate_completion_count,
Sim_Atom_Id_pcie_prs_page_request,
Sim_Atom_Id_pcie_prs_page_group_response,
Sim_Atom_Id_pcie_prs_stop_marker,
Sim_Atom_Id_pcie_requester_segment,
Sim_Atom_Id_pcie_ide_secured,
Sim_Atom_Id_pcie_msg_vdm_subtype,
Sim_Atom_Id_pcie_msg_vdm_vendor_id,
Sim_Atom_Id_pcie_link_l0p_support,
Sim_Atom_Id_pcie_msg_vdm_frs_reason,
Sim_Atom_Id_arm_privileged = 0x200,
Sim_Atom_Id_arm_nonsecure,
Sim_Atom_Id_arm_memory_attributes,
Sim_Atom_Id_arm_smmu_attributes,
Sim_Atom_Id_arm_nsaid,
Sim_Atom_Id_arm_device_id,
Sim_Atom_Id_arm_smmu_qtw_access_type,
Sim_Atom_Id_arm_axi_id,
Sim_Atom_Id_riscv_wg_wid = 0x300,
Sim_Atom_Id_riscv_device_id,
Sim_Atom_Id_riscv_process_id,
Sim_Atom_Id_riscv_io_error_ret,
Sim_Atom_Id_cxl_type = 0x400,
} atom_id_t;
import simics
simics.Sim_Atom_Id_pcie_prs_stop_marker
simics.Sim_Atom_Id_pcie_msg_vdm_vendor_id
simics.Sim_Atom_Id_trace_atom_access
simics.Sim_Atom_Id_initiator
simics.Sim_Atom_Id_riscv_process_id
simics.Sim_Atom_Id_data
simics.Sim_Atom_Id_arm_device_id
simics.Sim_Atom_Id_owner
simics.Sim_Atom_Id_pcie_device_id
simics.Sim_Atom_Id_user_data
simics.Sim_Atom_Id_pcie_link_negotiation
simics.Sim_Atom_Id_pcie_ecs
simics.Sim_Atom_Id_pcie_ats_translation_request_cxl_src
simics.Sim_Atom_Id_pcie_prs_page_group_response
simics.Sim_Atom_Id_pcie_link_flit_mode
simics.Sim_Atom_Id_fill_value
simics.Sim_Atom_Id_arm_memory_attributes
simics.Sim_Atom_Id_pcie_requester_segment
simics.Sim_Atom_Id_riscv_io_error_ret
simics.Sim_Atom_Id_pcie_pasid
simics.Sim_Atom_Id_pcie_ats_translation_request_no_write
simics.Sim_Atom_Id_arm_smmu_attributes
simics.Sim_Atom_Id_riscv_wg_wid
simics.Sim_Atom_Id_size
simics.Sim_Atom_Id_pcie_msg_vdm_subtype
simics.Sim_Atom_Id_bytemap
simics.Sim_Atom_Id_riscv_device_id
simics.Sim_Atom_Id_memop
simics.Sim_Atom_Id_pcie_requester_id
simics.Sim_Atom_Id_illegal
simics.Sim_Atom_Id_pcie_byte_count_ret
simics.Sim_Atom_Id_pcie_ide_secured
simics.Sim_Atom_Id_completion
simics.Sim_Atom_Id_list_end
simics.Sim_Atom_Id_cxl_type
simics.Sim_Atom_Id_pcie_ats_invalidate_completion_count
simics.Sim_Atom_Id_pcie_msg_vdm_frs_reason
simics.Sim_Atom_Id_pcie_prs_page_request
simics.Sim_Atom_Id_flags
simics.Sim_Atom_Id_pcie_link_l0p_support
simics.Sim_Atom_Id_pcie_type
simics.Sim_Atom_Id_arm_nonsecure
simics.Sim_Atom_Id_pcie_ats_invalidate_completion_itag_vector
simics.Sim_Atom_Id_arm_axi_id
simics.Sim_Atom_Id_pcie_msg_route
simics.Sim_Atom_Id_target_type
simics.Sim_Atom_Id_arm_nsaid
simics.Sim_Atom_Id_pcie_msg_type
simics.Sim_Atom_Id_pcie_error_ret
simics.Sim_Atom_Id_pcie_destination_segment
simics.Sim_Atom_Id_arm_smmu_qtw_access_type
simics.Sim_Atom_Id_pcie_ats_invalidate_request_itag
simics.Sim_Atom_Id_pcie_at
simics.Sim_Atom_Id_arm_privileged
Each atom type is associated with a unique id, the atom_id_t. Most atoms types are pre-defined by Simics Core and have static ids, but there are also dynamically assigned ids which are used for custom atom types.
Atom ids are internal to Simics Core and should never be used explicitly by a Simics models. Instead, there are API functions like e.g. ATOM_size or ATOM_initiator which should be used instead.
atom_t — basic type used inside transactions
#include <simics/device-api.h> // in C
// always available in DML
typedef struct {
atom_id_t id;
#ifndef PYWRAP
void *ptr;
#endif
} atom_t;
import simics
class simics.atom_t
The atom_t type is a container type for tagged data associated with a transaction. The kind of data stored in the atom is determined by the id field, and a pointer to the data or the data itself is stored in the ptr field.
Atoms should always be initialized using provided constructor functions like ATOM_flags or ATOM_size. Usage of the constructors ensures that the data payload is of the correct type and that the id is set to the correct value.
Atom lists must be terminated with the special ATOM_LIST_END marker.
transaction_completion_t — callback type for transaction completion
#include <simics/device-api.h> // in C
// always available in DML
typedef exception_type_t (*transaction_completion_t)(conf_object_t *obj,
transaction_t *t,
exception_type_t ex);
Callback invoked when an asynchronous transaction is completed. The callback is stored in a completion atom belonging to the transaction t. Similarly, obj is an object stored in either an owner atom or an initiator atom. The former takes precedence if both are present.
Completion callbacks are only invoked for transactions monitored with either SIM_monitor_transaction or SIM_monitor_chained_transaction, or for transactions deferred with SIM_defer_owned_transaction.
The completion status for the operation is given in the ex argument, and is usually equal to Sim_PE_No_Exception.
The return value of the callback is the completion status for the transaction t. This status is used to complete the parent transaction if the transaction is being monitored with SIM_monitor_chained_transaction. The return value is also returned by SIM_monitor_transaction or SIM_monitor_chained_transaction when a transaction is completed synchronously.
If the callback returns Sim_PE_Deferred, then the transaction t is left uncompleted. It must then be completed later on by an explicit call to SIM_complete_transaction.
transaction_flags_t — flags used with transaction_t
#include <simics/device-api.h> // in C
// always available in DML
typedef enum {
Sim_Transaction_Fetch = 1 << 0,
Sim_Transaction_Write = 1 << 1,
Sim_Transaction_Control = 1 << 2,
Sim_Transaction_Inquiry = 1 << 8,
Sim_Transaction_Incoherent = 1 << 9,
Sim_Transaction_Atomic = 1 << 10,
} transaction_flags_t;
import simics
simics.Sim_Transaction_Write
simics.Sim_Transaction_Fetch
simics.Sim_Transaction_Incoherent
simics.Sim_Transaction_Control
simics.Sim_Transaction_Atomic
simics.Sim_Transaction_Inquiry
The transaction_flags_t type is bitmask used to specify the transaction type. It is a combination of the following bits:
Sim_Transaction_Fetch indicates that the transaction is an instruction fetch.
Sim_Transaction_Write is set if the transaction is a write.
Sim_Transaction_Control is set if the transaction does not actually transfer any data. One example of such transactions is cache control operations.
The Sim_Transaction_Inquiry bit signifies that side effects normally triggered by the transaction should be suppressed. Examples of side effects include triggering breakpoints and clearing “read-to-clear” device registers.
When neither Sim_Transaction_Fetch nor Sim_Transaction_Write is set the transaction is a read transaction.
transaction_t — type of transactions
#include <simics/device-api.h> // in C
// always available in DML
typedef struct transaction {
#ifndef PYWRAP
atom_t *atoms;
#endif
struct transaction *prev;
#ifndef PYWRAP
struct transaction_cache *_cache;
uint64 _status;
#endif
} transaction_t;
import simics
class simics.transaction_t(read = True, write = False, fetch = False, inquiry = False
prev = None, <atoms...>)
A transaction_t represents a memory transaction. The properties of the transaction is stored in the form of an atom list, where each atom describes a particular aspect of the transaction, like the size of the transaction.
The field atoms points to the atoms list, which must be terminated with the constant ATOM_LIST_END.
The prev field points to an optional parent transaction. If a particular atom is not found in the atoms list, then the parent’s list of atoms is consulted instead. The prev pointer is also used when a chained transaction is monitored with SIM_monitor_chained_transaction.
Besides the fields above, the transaction contains some internal fields that should be initialized to 0. The internal fields should not be referenced explicitly since they are likely to change in future Simics releases.
For details, please refer to Transactions chapter in the Model Builder’s User Guide.
translation_flags_t, translation_t — structure used with translator_interface_t
#include <simics/device-api.h> // in C
// always available in DML
typedef enum {
Sim_Translation_Dynamic = 1,
Sim_Translation_Ambiguous = 2
} translation_flags_t;
typedef struct translation {
const map_target_t *target; /* target of translation */
physical_address_t base; /* base address of translated range */
physical_address_t start; /* start address in mapped object */
physical_address_t size; /* size of translated range */
translation_flags_t flags;
} translation_t;
import simics
simics.Sim_Translation_Ambiguous
simics.Sim_Translation_Dynamic
class simics.translation_t(target=None, base=0, start=0, size=0, flags=0)
The translation_t type is used for the implementation of the translator and transaction_translator interfaces. It describes the range for which the translation is valid, its target as well as translation properties.
The range for which the translation is valid is specified by the fields base and size. As a special case, if size and base are both 0, then the translation is valid for the entire address space. To allow optimizations (e.g., caching of translations) translators should return as wide ranges as possible.
The target field specifies the object and interface port which is mapped into the address range in the form of a map target. Map targets can be created using the function SIM_new_map_target.
Please note that the ownership over the returned map target is not transferred to the interface caller. This means that to avoid memory leaks the reference to the map target must be kept by the implementing object, and SIM_free_map_target function should be later used to deallocate the map target. Possible map targets include IO banks, RAM, ROM, memory spaces, port spaces, bridges, and translators. The base address in the source address space is mapped to the target address returned in the start field.
A null value returned in the target field signifies that the translation cannot be done. This can happen if there is nothing mapped in the range defined by base and size (transactions directed to this region will be terminated with the pseudo exception Sim_PE_IO_Not_Taken) or if a translation valid for all requested accesses cannot be performed. In the latter 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.
If the returned translation is not static but instead depends on e.g. a device register, then the translator can set the flags field to Sim_Translation_Dynamic. This flag indicates that the translation must not be cached. If this flag is not used, then it is the responsibility of the translator to call either SIM_map_target_flush (preferably) or SIM_translation_changed function when a previously performed translation is no longer valid.
The Sim_Translation_Ambiguous flag should not generally be used by models. It is used by Simics objects of the memory-space class to indicate an error in the memory mapping when several destinations are specified for the address.