This section captures major incremental changes, and what motivated the changes.
| Motivation/Intent | What changed |
|---|---|
Version 1.5 |
|
EventRecord Size Increase |
Increased size of EventRecord to 64-bits. |
Version 1.4 |
|
Vector Support |
Added support for vector register data. Numerous bug-fixes and QoL improvements. |
Version 1.3 |
|
Open Sourcing Prep |
Cosmetic changes, rewrite of the introductory paragraph, and rewrite of introduction to STF file format section. |
Version 1.2 |
|
InstExceptionPCTarget record covers a subset of what EventRecord and the associated EventPCTargetRecord cover per STF Exception Table definitions. |
Removed InstExceptionPCTargetRecord Breaks backward compatibility |
Provide a mechanism to record transitions between execution privilege modes (User, Supervisor, Hypervisor, Machine) |
Added STF_EVENT_MODE_CHANGE as a meta-event for capturing transitions into a new execution mode. Modified EventPCTargetRecord to be optional, because this meta-event does not have a PC change associated with it. |
Reduce specification complexity and improve processing efficiency by combining two Event records which always go together. |
Merged event meta-data fields from EventContentRecord into the EventRecord, and removed EventContentRecord. Breaks backward compatibility |
Version 1.1 |
|
Provide a summary of changes to make it easier for developers to update tools and comply with the new spec. |
Added ChangeLog section |
There is a benefit, purely from implementation standpoint, to have Records which precede other Records have lower numerical values. This allows for ordered traversal through related records, ending with the highest number record, concluding a group of records. This is most frequently done with Instruction Encoding (a.k.a. opcode) Records. Recognising that we can easily get into a bind with numbering, we moved the Instruction Encoding records to a much higher enum, and moved PTE ahead of the memory accesses. |
Records which have “precede” in their semantic definition are set to have lower numbers than the records which follow them, and conversely records which have “follow” in their semantic definition are set to have higher numbers than the records which come before them. Breaks backward compatibility |
PTE records provide translation, so they should come before the memory accesses records. |
PTE records shall precede memory accesses Records. Breaks backward compatibility |
Shuffled ID’s for ordering which seems to be more logical. |
Moved change of flow records to be at the top as we want them to appear first, followed by register changes, and then address translation (table walks), memory accesses, external events, microops, and finally instruction encodings (opcodes) Breaks backward compatibility |
Events can have varying amounts of data that need to be expressed. |
EventContentRecord now allows for an extensible number of fields. Definitions of the fields are provided in the STF Exception Event and Event Meta-Data table. It is placed after the EventRecord, to allow potentially adding another related record in the future if need arises. Breaks backward compatibility |
Support capturing vector register contents |
Added vector type for registers, so that contents can be captured. This is the first step in vector instructions support. |
Version 1.0 |
|
Initial Spec |
Initial Spec |
Simulation Trace Format (STF) is a binary file format for storing instruction traces, agnostic of instruction set architecture. The format defines a standard for capturing information related to instructions, associated register values, memory access addresses and data associated with them, as well as additional context information such as page table walk, interrupts, bus/fabric transaction addresses/data, etc. This document also specifies how tools generating and/or modifying traces can express information which can aid the tools consuming the traces to interpret them appropriately.
STF is generated by producer tools, such as functional models or hardware, and consumed by tools such as trace-driven performance models, trace analysis tools, and hardware (if the trace contains the relevant functional information).
The specification covers the following aspects:
-
Header that provides enough context to allow proper interpretation of the remainder of the trace
-
Entities that describe the execution environment for the program (instruction encoding mode, privilege level, process ID, etc.)
-
Entities that describe the per-instruction attributes and changes to (non-memory) program state (instruction encoding, source register values, destination register values, side-effect changes, synchronous exceptions)
-
Entities that describe the per-instruction attributes and changes to memory program state
-
Entities that capture non-instruction-based changes to program state (exceptions, external interrupts, non-traced TLB changes, etc.)
-
Data syntax of each entity including their bit-field encoding
-
Data semantics of each entity
-
Relationships among entities
The specification does NOT cover the following aspects:
-
Instruction Set Disassembly - external binutils helper packages are used to disassemble instructions at run-time
-
Compression format - file compression format is chosen independently of this specification from a plethora of existing compression formats and accompanying tools. The standard, however, requires that the API be extensible to allow developers to use his/her own compression formats.
-
"SHALL" clause - mandatory
-
"MUST" clause - mandatory
-
"MAY" clause - optional
-
"width" - refers to size of data in bits
-
Instruction encoding vs Opcode:
-
Instruction encoding refers to the entire instruction encoding (e.g. 32 bits)
-
Opcode refers to the 7 least significant bits [6:0] of the Instruction Encoding (per RV32I)
-
-
Instruction record is synonymous to instruction encoding record (instruction is identified by its instruction encoding record)
STF specification has 2 domains:
-
Syntactic – This part of the specification addresses syntax of entities in an STF file - types of data and associated data structures. It does NOT address the correctness of the relationships among data entities
-
Semantic – This part of the specification addresses two main areas:
-
Understanding of each data entity and clarify any ambiguity in interpretation. This area often has to do with the state or pre-condition of the data entities being injected
-
The inter-relationships among various entities of data
-
STF record is an atomic container which holds a fixed width descriptor and a variable width data associated with the record. Though the data has variable width, it’s structure is well defined by the specification.
An STF file is composed of STF records. Basic anatomy of an STF file is shown in this figure:
Record is always a complete atomic entity.
An STF file shall have a minimum of one record.
Multiple records can be attributed to an instruction. Attributing a set of records to an instruction follows general principles:
-
All records, except an instruction encoding record (STF_INST_16 or STF_INST_32), that precede an instruction encoding record are attributed to the instruction
-
There are exceptions to the above rule when it comes to event related records (STF_EVENT, STF_EVENT_CONTENT). Events due to various (mostly asynchronous) exceptions may not be triggered by the instruction they are attributed to according to the STF file.
Header Record Group (HRG) - Group of record providing information at a trace level. EndHeaderRecord completes and HRG. There shall be only one HRG at the start of a file. If an STF file is modified by a tool, this tool shall update all relevant fields of the HRG (e.g. stitching).
Instruction Record Group (IRG) - Group of records attributed to an instruction (i.e. all of the records after previous and before the instruction encoding record which completes it’s IRG)
Memory Access Record Group (MARG) - Group of records associated with a memory access, at minimum including Memory Address and Content.
Relationship between IRG, MARG, various Records, and Instruction Encoding Record is shown in the following figure:
The following table specifies the encoding and semantics of valid STF records.
Example on how to read the table for the CommentRecord:
-
Record Data Structure: type name is CommentRecord, included in the API header stf.h
-
Record Descriptor: STF_COMMENT descriptor string from the API header stf.h. The number in parenthesis () is the enumerated sequence number of the descriptor.
-
Mandatory: The field is used for specifying if the record is mandatory. If a record is not mandatory in all cases, this field describes which condition triggers the record. It is mandatory to have a CommentRecord.
-
Record Data Encoding: Data fields are in series, where the first number within brackets [] is the data field size in bytes. CommentRecord encodes the number of bytes of comment data = n bytes into the first 32-bit field, followed by the n-byte long actual string data field.
-
Semantics & Additional Comments: Semantics of the specification, as well as free form comments providing details, use cases, and clarification for the record specification.
The following shows definitions of various STF exception event identifiers and associated meta-data for the events captured by an EventRecord (STF_EVENT).
| STF Exception ID | Exception Related Data/Content shall Include |
Sync/Async Exception | Description |
|---|---|---|---|
INT_USER_SOFTWARE |
Field 0: Source of the interrupt |
Async |
User software interrupt |
INT_SUPERVISOR_SOFTWARE |
Async |
Supervisor software interrupt |
|
INT_HYPERVISOR_SOFTWARE |
Async |
Hypervisor software interrupt |
|
INT_MACHINE_SOFTWARE |
Async |
Machine software interrupt |
|
INT_USER_TIMER |
Async |
User timer interrupt |
|
INT_SUPERVISOR_TIMER |
Async |
Supervisor timer interrupt |
|
INT_HYPERVISOR_TIMER |
Async |
Hypervisor timer interrupt |
|
INT_MACHINE_TIMER |
Async |
Machine timer interrupt |
|
INT_USER_EXT |
Async |
User external interrupt |
|
INT_SUPERVISOR_EXT |
Async |
Supervisor external interrupt |
|
INT_HYPERVISOR_EXT |
Async |
Hypervisor external interrupt |
|
INT_MACHINE_EXT |
Async |
Machine external interrupt |
|
INT_COPROCESSOR |
Async |
Supervisor guest external interrupt |
|
INT_HOST |
Async |
Host interrupt |
|
INST_ADDR_MISALIGN |
Field 0: Virtual address of the instruction |
Sync |
Instruction Address Misaligned |
INST_ADDR_FAULT |
Field 0: Virtual address of the instruction |
Sync |
Instruction access fault |
ILLEGAL_INST |
Field 0: Virtual address of the instruction Field 1: Instruction opcode Field 2: Instruction encoding mode |
Sync |
Illegal instruction |
VIRTUAL_INST |
Sync |
Virtual instruction |
|
BREAKPOINT |
Field 0: Virtual address of the instruction |
Sync |
Breakpoint |
LOAD_ADDR_MISALIGN |
Field 0: Virtual address of the instruction Field 1: Instruction encoding Field 2: Target address that caused the exception |
Sync |
Load address misaligned |
LOAD_ACCESS_FAULT |
Sync |
Load access fault |
|
STORE_ADDR_MISALIGN |
Sync |
Store address misaligned |
|
STORE_ACCESS_FAULT |
Sync |
Store access fault |
|
USER_ECALL |
Field 0: System call number |
Sync |
Environment call from User mode |
SUPERVISOR_ECALL |
Sync |
Environment call from Supervisor mode |
|
HYPERVISOR_ECALL |
Sync |
Environment call from Hypervisor mode |
|
MACHINE_ECALL |
Sync |
Environment call from Machine mode |
|
INST_PAGE_FAULT |
Field 0: Virtual address of the instruction Field 1: Instruction encoding |
Sync |
Instruction page fault |
GUEST_INST_PAGE_FAULT |
Sync |
Guest instruction page fault |
|
LOAD_PAGE_FAULT |
Field 0: Virtual address of the instruction Field 1: Instruction encoding Field 2: Target address that caused the exception |
Sync |
Load page fault |
GUEST_LOAD_PAGE_FAULT |
Sync |
Guest load page fault |
|
STORE_PAGE_FAULT |
Sync |
Store page fault |
|
GUEST_STORE_PAGE_FAULT |
Sync |
Guest store page fault |
|
MODE_CHANGE |
Field 0: Mode in which subsequent instructions execute Field 0 Encoding: 00 - User Mode 01 - Supervisor Mode 10 - Hypervisor Mode 11 - Machine Mode |
Sync/Async |
Meta-event for capturing transition into a new execution mode |
The protocol data field in the [TransactionRecord] is generic, enabling STF to support multiple bus protocols without having to allocate a new record type every time a new protocol is added. The protocol type is specified by the [ProtocolIdRecord] in the header, and only one protocol type is allowed per trace.
Change of Flow (COF) - Change of instruction execution flow for reasons that are deterministic as well as non-deterministic. COF is logged in the trace using the STF_INST_PC_TARGET record for deterministic and with STF_FORCE_PC or STF_EVENT_PC_TARGET for non-deterministic cases.
STF_FORCE_PC applies COF to the current instruction, while all other cases apply it to the subsequent instruction.
-
Deterministic COF cases: These COF cases happen within the scope of a thread context and without having any exceptions being raised within that context.
-
Function returns through "ret" like instruction
-
Direct branches through branch instructions where target address of where the execution flow will jump to an address which is either a PC relative(relative to current address) or absolute address
-
Indirect branches through branch instructions where the target address of where the execution flow will jump to is an address stored in a register. The address was placed in that register by calculation by earlier instruction/s. Typical use case of this is jump to a function called by a function pointer.
-
-
Non-deterministic COF cases: These COF cases happen due to interruptions in a program thread due to exceptions being raised either by the program thread context itself or due to external interruptions. This category of COF is indicated by
-
Program flow changes, due to actions of current instruction, to exception handler within the same exception level. Example can be kernel code accessing data from address whose entry is missing in PTE, thus triggering page fault exception within the same exception level.
-
Program flow changes, due to actions of current instruction, to exception handler to a higher exception level. Example: user-space program trying to access memory causing page fault causing exception level changes to supervisor mode or user-space syscall.
-
Program flow changes due to return from exception handler
-
Program flow changes, due to context switches. Example: thread switch, process switch, Address Space Identifier (ASID) switch.
-
Program flow changes, due to external interrupts to the same or higher exception level.
-
Program flow changes due to instruction mode change from this set (not applicable to RISC-V)
-
Program flow changes due to manipulation of a trace file.
-