Aggregates (Structs and Unions)
temu_Class
Type
struct temu_Class {
temu_Object Super;
void * Impl;
void * VTable;
temu_ObjectCreateFunc Create;
temu_ObjectDisposeFunc Dispose;
}Description
Class object
The TEMU object system is a dynamic object system. Classes are themselves represented as objects (instanciated by meta-classes).
The TEMU class contains among other things the constructor/destructor.
Internally, the hidden implementation provides more capabilities than is
exposed by the temu_Class type.
Fields
| Field | Type | Description |
|---|---|---|
Super |
temu_Object |
Super class of the class instance. |
Impl |
void * |
Internal pointer, do not touch. |
VTable |
void * |
Internal pointer, do not touch. |
Create |
temu_ObjectCreateFunc |
Constructor / create function for creating instances of the class. |
Dispose |
temu_ObjectDisposeFunc |
Destructor / dispose function for disposing instances of the class. |
temu_CodePattern
Type
struct temu_CodePattern {
uint64_t PhysicalAddress;
uint64_t PhysicalAddressMask;
temu_PatternAction Action;
void (*)(void *, void *) Callback;
void * CallbackData;
int SkipLength;
unsigned int PatternLength;
}Description
Code pattern structure
The code pattern structure exists to make it possible to define a static list of code patterns. The patterns should be installed on a processor using the code pattern interface.
The code pattern can be used to attach custom actions, either at a specific physical address or when a sequence of instructions have been matched.
TEMU uses this mechanism internally to detect idle-loops.
A pattern is matched if the physical address of the start matches, and all instructions in the pattern match. Zero length patterns are legal if the physical address mask is non-zero. Normally, skip length and pattern length should be the same.
It is possible to skip backwards. It is also possible to skip more or less than the matched instructions.
When the pattern is installed, it is injected into a trie. The injected structure is after that no longer used and can be disposed.
Patterns are matched at decode time, for both interpreter and binary translator.
For the interpreter, a pseudo instruction will be inserted to carry out the action.
In the case of processors with branch delay slots (e.g. SPARC), the pattern is only triggered if the nPC follows the PC.
Pattern entries match individual instruction chunks, i.e. for Thumb2 an entry matches a 16-bit part, meaning two entries will be needed for a 32-bit instruction.
Note that processors are expected to implement one pattern interface per instruction set.
Patterns are not matched if they cross page boundaries.
Fields
| Field | Type | Description |
|---|---|---|
PhysicalAddress |
uint64_t |
Physical address matched in the decoder (currently ignored) |
PhysicalAddressMask |
uint64_t |
Physical address mask matched in the decoder, set to 0 to ignore address (currently ignored) |
Action |
temu_PatternAction |
Action to take on this match |
Callback |
void (*)(void *, void *) |
Function to call for actions tePA_Call and tePA_CallAndSkip, first argument is the processor pointer (currently ignored) |
CallbackData |
void * |
Data passed in second parameter to callback (currently ignored) |
SkipLength |
int |
Number of instructions to skip (in case of tePA_Skip and tePA_CallAndSkip) |
PatternLength |
unsigned int |
Number of pattern entries |
temu_CpuInfo
Type
struct temu_CpuInfo {
const char * ArchName;
const char * ModelName;
unsigned int VASize;
unsigned int PASize;
unsigned int VATypeSize;
unsigned int PATypeSize;
unsigned int GPRCount;
unsigned int FPRCount;
temu_Endian InstructionEndianess;
temu_Endian DataEndianess;
unsigned int NumInstructionSets;
}Fields
| Field | Type | Description |
|---|---|---|
ArchName |
const char * |
Architecture name |
ModelName |
const char * |
Processor model name |
VASize |
unsigned int |
Virtual address size in bits |
PASize |
unsigned int |
Physical address size in bits |
VATypeSize |
unsigned int |
Virtual address type size in bytes |
PATypeSize |
unsigned int |
Physical address type size in bytes (i.e. 8 for 36 bit PA) |
GPRCount |
unsigned int |
GPR register count |
FPRCount |
unsigned int |
FPR register count |
InstructionEndianess |
temu_Endian |
Instruction endianness |
DataEndianess |
temu_Endian |
Data endianness |
NumInstructionSets |
unsigned int |
Number of instruction sets |
temu_CpuVTable
Type
struct temu_CpuVTable {
temu_CpuIface * Cpu;
temu_IrqCtrlIface * Irq;
temu_MemAccessIface * InvalidAccess;
temu_ClockIface * Clock;
temu_BinaryTranslationControlIface * Translation;
}temu_CreateArg
Description
Generic constructor argument
The object constructors takes an array of key/value pairs as parameters. The values are passed using either:
-
Registered argument in the
Class.newcommand method. -
Explicitly to
temu_createObject(). -
Args parameter to
object-createglobal command.
The object create function would typically scan through the array, finding relevant matching keys.
temu_Event
Type
struct temu_Event {
int64_t Steps;
int64_t Time;
int64_t EventId;
uint32_t Flags;
int QueueIdx;
temu_TimeSource * Queue;
temu_Object * Obj;
void (*)(struct temu_Event *) Func;
int64_t Period;
int64_t RTTime;
int64_t RTPeriod;
int64_t TriggerCount;
}Fields
| Field | Type | Description |
|---|---|---|
Steps |
int64_t |
Managed internally, do not touch |
Time |
int64_t |
Managed internally, do not touch |
EventId |
int64_t |
Managed internally, do not touch |
Flags |
uint32_t |
Internal use, do not touch |
QueueIdx |
int |
Managed internally, do not touch |
Queue |
Managed internally, do not touch |
|
Obj |
Managed internally, only for reading |
|
Func |
void (*)(struct temu_Event *) |
Event callback |
Period |
int64_t |
Managed: Period (cycles) for cyclic events |
RTTime |
int64_t |
Managed: Time (monotonic ns) for RT exec |
RTPeriod |
int64_t |
Managed: Period (ns) for RT events |
TriggerCount |
int64_t |
Managed: Number of time event has been triggered |
temu_IfaceRef
Description
Generic interface
In TEMU interfaces are referred to using an object / interface pointer pair. The object is in general passed as the first parameter to functions in the interface. This type provides a generic interface reference where the interface pointer itself is type erased.
While the type is rarely used by itself, it is commonly returned by the TEMU API. To convert to / from this type from / to typed interface references, it is possible to either memcopy or cast field by field.
temu_IfaceRefArray
Description
Dynamic interface reference array
In some cases, the number of objects we know about is unknown. To solve that TEMU provides a vector like type.
It is not the intention that the fields in the array are manipulated
directly. Instead, use the temu_ifaceRefArray* functions.
|
temu_List
temu_MachineVTable
temu_MemAccessCapabilities
temu_MemTransaction
Type
struct temu_MemTransaction {
uint64_t Va;
uint64_t Pa;
uint64_t Value;
uint64_t Size;
uint64_t Offset;
temu_InitiatorType InitiatorType;
temu_Object * Initiator;
void * Page;
uint64_t Cycles;
uint32_t Flags;
void * IR;
}Description
Generic memory transaction.
This type is kept in sync with the emulator core. The layout is guaranteed. and will remain as is, although more fields may be added (at the bottom).
When the emulator core issues a memory transaction (assuming no ATC hit), the core allocates this structure on the stack and fills in some of the fields with default values. The memory transaction is passed by pointer or reference. By filling in the different fields you can adapt the result of the memory transaction.
Fields
| Field | Type | Description |
|---|---|---|
Va |
uint64_t |
64 bit virtual for unified 32/64 bit interface. |
Pa |
uint64_t |
64 bit physical address |
Value |
uint64_t |
Resulting value (or written value). On MMIO Reads the model fills in this value, and on writes the written value will be stored here. |
Size |
uint64_t |
Two-logarithm of the size of the transaction in bytes it is at most the size of the CPUs max bus size. In case of SPARCv8, this is 4 bytes (double words are issued as two accesses). As this is the 2-log of the size in bytes, a single byte access will have a size of 0, a 2 byte transaction will have size 1, a 4 byte transaction will have size 2 and an 8 byte transaction will have size 3. In TEMU3 this field was changed to an uint64_t from uint8_t. This as it does not add any additional space. And we can repurpose value and size as follows: - The lower 2 bits define the base unit of the transaction (same as before), 0 ⇒ 1 byte, 1 ⇒ 2 bytes, 2 ⇒ 4 bytes, 3 ⇒ 8 bytes. - The upper bits define the number of transferred units 0 implies one unit. If the transferred units is more than 0, we are dealing with a large transaction. These can be used by e.g. RAM models for block transfers etc. In that case the Value field is to be reinterpreted as a pointer to the location of the data. This means that we can use the memory access interface to e.g. read out send lists and similar items. The memory space must thus have a way of determining which type of transaction is legal. The MemoryAccessIface has been extended with a capability query, which if implemented has the ability to query for supported features. |
Offset |
uint64_t |
Used for device models, this will be filled in with the offset from the start address of the device (note it is in practice possible to add a device at multiple locations (which happens in some rare cases)). |
InitiatorType |
temu_InitiatorType |
InitiatorType identifies the type of object starting the transaction. this is only relevant when Initiator is set to non-null, and allows for the specification of device pointers in the initator. This field is new in TEMU 2.2. The field was introduced to support the implementation of I/O MMUs. |
Initiator |
Initiator of the transaction (a CPU object). It can be null, which indicate that the transaction was not initiated by normal CPU activity (e.g. fetch, read or write). When the initiator is null, models should not attempt to stop the processor core, go to idle mode or raise traps (posting events is fine). An example when the initiator is null is when an MMU does a table walk. The MMU will normally special case handle table walks which access un-mapped memory. |
|
Page |
void * |
Page pointer (for caching), this can be filled in by a memory model to have the emulator core inject the page translation in the ATC. If a model sets this, the page pointer will automatically be cleared if the page has attributes (breakpoints, etc). Models that implement normal memory mapped registers should NOT populate the page pointer. |
Cycles |
uint64_t |
Cycle cost for memory access (initialised to 0). |
Flags |
uint32_t |
Flags for use in the memory hierarchy. |
IR |
void * |
Intermediate code for interpreter (internally managed do not modify) |
temu_MemVTable
temu_Object
Type
struct temu_Object {
temu_Class * Class;
char * Name;
temu_TimeSource * TimeSource;
temu_Component * Component;
uint64_t LoggingFlags;
int64_t WillDisposeNotification;
int64_t DisposedNotification;
void * UserData;
uint64_t IsClassObject;
uint64_t IsCheckpointable;
uint64_t IsTimeSource;
uint64_t TraceMemoryReads;
uint64_t TraceMemoryWrites;
uint64_t BreakOnMemoryRead;
uint64_t BreakOnMemoryWrite;
}Description
Root object type for all TEMU objects.
The TEMU object system is used for defining models in TEMU.
All models must derive from temu_Object.
Inheritance in C is done by placing a temu_Object field
as the first field in the derived struct.
TEMU by convention use the name Super for the parent field name.
The type contains a UserData void pointer that can be used by for example
simulator integrators.
The UserData field can be written by the user.
The field is guaranteed to not be modified by the TEMU runtime.
| While the convention in C is safe, in C++ it is the responsibility of the user to ensure that the derived type is a standard layout type. |
Fields
| Field | Type | Description |
|---|---|---|
Class |
Class pointer |
|
Name |
char * |
Object name |
TimeSource |
Timesource object |
|
Component |
Parent component (null for root comp) |
|
LoggingFlags |
uint64_t |
Log category enabled/disabled |
WillDisposeNotification |
int64_t |
Notification emitted before object is deleted |
DisposedNotification |
int64_t |
Notification emitted after object has been deleted |
UserData |
void * |
User data pointer. This is not saved in snapshots. |
IsClassObject |
uint64_t |
The object is a class object |
IsCheckpointable |
uint64_t |
The object is snapshottable |
IsTimeSource |
uint64_t |
The object is a time source (can be safely casted to temu_TimeSource) |
TraceMemoryReads |
uint64_t |
Memory read accesses to this object will be traced by memory space |
TraceMemoryWrites |
uint64_t |
Memory write accesses to this object will be traced by memory space |
BreakOnMemoryRead |
uint64_t |
Memory read accesses to this object will trigger break |
BreakOnMemoryWrite |
uint64_t |
Memory write accesses to this object will trigger break |
temu_PropAccessor
Type
struct temu_PropAccessor {
temu_Type Typ;
temu_Object * Obj;
int Index;
void * Data;
temu_PropWriter Writer;
temu_PropReader Reader;
temu_PropWriter Setter;
temu_PropReader Getter;
}Description
Generic property accessor
This struct serves as a generic accessor for properties. The intention for this is to be able to cache property accessors, without having to disambiguate between properties and pseudo properties.
The accessor is queried by the temu_getPropAccessor function, and is then used by calling the functions:
-
readProp -
writeProp -
getProp -
setProp
Depending on whether read, write, get or set semantics is needed.
Fields
| Field | Type | Description |
|---|---|---|
Typ |
temu_Type |
Type of property |
Obj |
Pointer to object containing property |
|
Index |
int |
Index used in access, can be modified by user |
Data |
void * |
Pointer to value if applicable |
Writer |
temu_PropWriter |
Writer function if applicable |
Reader |
Reader function if applicable |
|
Setter |
temu_PropWriter |
Setter function if applicable |
Getter |
Getter function if applicable |
temu_Propref
temu_Propval
temu_SpwRmapDecodedPacket
Type
struct temu_SpwRmapDecodedPacket {
uint32_t TotalSize;
temu_SpwRmapPacketType PacketType;
temu_SpwRmapDecodedCmdField CmdField;
temu_SpwRmapRawHeader RawHeader;
}Fields
| Field | Type | Description |
|---|---|---|
TotalSize |
uint32_t |
Total size of the packet received. |
PacketType |
temu_SpwRmapPacketType |
The packet type as identified by bits [7,6] in instruction. |
CmdField |
temu_SpwRmapDecodedCmdField |
The command field, bits [5,4,3,2] in instruction. |
RawHeader |
temu_SpwRmapRawHeader |
Raw header data access. |
temu_SpwRmapDecodedReadReply
temu_SpwRmapDecodedRmwReply
temu_SpwRmapRmwCmdPacket
Type
struct temu_SpwRmapRmwCmdPacket {
uint8_t AccessSize;
const uint8_t * Data;
const uint8_t * Mask;
uint32_t AvailableDataLength;
uint8_t DataCrc;
}Fields
| Field | Type | Description |
|---|---|---|
AccessSize |
uint8_t |
Size of the access. |
Data |
const uint8_t * |
Pointer to the first data char. |
Mask |
const uint8_t * |
Pointer to the first mask char. |
AvailableDataLength |
uint32_t |
The amount of data available. |
DataCrc |
uint8_t |
Data crc. Valid only if AvailableDataLength > Header.DataLength. |