Updates 2.0.4

branchTrace.adoc

@@ -86,7 +86,7 @@ result of a specific instruction or event. Exceptions can be thought of
 in the same way, even though they can be typically linked back to a
 specific instruction address.
 
-The decoder generally does not know where an interrupt occured in the
+The decoder generally does not know where an interrupt occurred in the
 instruction sequence, so the trace must report the address where normal
 program flow ceased, as well as give an indication of the asynchronous
 destination which may be as simple as reporting the exception type. When
@@ -119,6 +119,7 @@ The instruction trace encoder needs to synchronise fully:
 was not traced;
 * If the instruction is the first of an interrupt service routine or
 exception handler;
+* If the privilege level changes; 
 * After a prolonged period of time.
 
 [[sec:endoftrace]]
@@ -198,9 +199,9 @@ decoder developers.
 Related parameters: None
 
 The RISC-V Privileged ISA specification stores exception handler base
-addresses in the *_utvec/stvec/vstvec/mtvec_* CSR registers. In some
+addresses in the *_stvec/vstvec/mtvec_* CSR registers. In some
 RISC-V implementations, the lower address bits are stored in the
-*_ucause/scause/vscause/mcause_* CSR registers.
+*_scause/vscause/mcause_* CSR registers.
 
 By default, both the *_*tvec_* and *_*cause_* values are reported when
 an exception or interrupt occurs.
@@ -330,12 +331,12 @@ cache with identical behavior will need to be implemented in the decoder
 software. Even a small cache can provide significant improvement.
 
 The cache shall comprise 2^_cache_size_p_^ entries, each of which can
-contain an instruction address. It will be direct mapped, with each
+contain an instruction address.  The addresses stored in the cache are 
+the targets of uninferable jumps.  It will be direct mapped, with each
 entry indexed by bits _cache_size_p_:1 of the instruction address (or
 __cache_size_p__+1:2 if compressed instructions aren't supported).
 
-Each uninferable jump target is first compared with the entry at its
-index in the cache. If it is found in the cache, the index number is
+Each uninferable jump target is first compared with the entry in the cache at the index derived from the jump target address. If it is found in the cache, the index number is
 traced rather than the target address. If it is not found in the cache,
 the entry at that index is replaced with the current instruction
 address.

control.adoc

@@ -2,14 +2,12 @@
 == Encoder Control
 
 The fields required to control a Trace Encoder are defined in the
-https://github.com/riscv-non-isa/tg-nexus-trace/blob/master/docs/RISC-V-Trace-Control-Interface.adoc[RISC-V Trace Control Interface Specification], which is intended to apply to any and all RISC-V trace encoders, regardless of encoding protocol. This chapter details which of those fields apply to E-Trace. To avoid replication, descriptions are not provided here; additional E-Trace specific context or clarification is provided only where required.
+https://github.com/riscv-non-isa/e-trace-encap/releases/latest/[RISC-V Trace Control Interface Specification], which is intended to apply to any and all RISC-V trace encoders, regardless of encoding protocol. This chapter details which of those fields apply to E-Trace. To avoid replication, descriptions are not provided here; additional E-Trace specific context or clarification is provided only where required.
 
 How fields are organized and accessed (e.g packet based or memory
 mapped) is outside the scope of this document. If a memory mapped
-approach is adopted,
-https://github.com/riscv-non-isa/tg-nexus-trace/blob/master/docs/RISC-V-Trace-Control-Interface.adoc#register-map[this
-register map] from the RISC-V Trace Control Interface Specification
-should be used.
+approach is adopted, the 'Trace Component Register Map' from the 
+https://github.com/riscv-non-isa/e-trace-encap/releases/latest/[RISC-V Trace Control Interface Specification] should be used.
 
 Note: Upto and including the E-Trace v2.0.0 specification, which
 predated the creation of the RISC-V Trace Control Interface

decoder.adoc

@@ -223,8 +223,7 @@ function is_inferable_jump (instr)
 
   if ((instr.opcode == JAL)   or
       (instr.opcode == C.JAL) or
-      (instr.opcode == C.J)   or
-      (instr.opcode == JALR and instr.rs1 == 0))
+      (instr.opcode == C.J))
     return TRUE
 
   return FALSE

exampleAlgorithm.adoc

@@ -9,7 +9,7 @@ A reference algorithm for compressed branch trace is given in
 * _te_inst._ The name of the packet type emitted by the encoder (see
 <<packets>>);
 * _inst._ Abbreviation for 'instruction';
-* _exception. Exception or interrupt signalled;_
+* _trap. Exception or interrupt signalled;_
 * _updiscon._ Uninferable PC discontinuity. This identifies an
 instruction that causes the program counter to be changed by an amount
 that cannot be predicted from the source code alone (*itype* values 8,
@@ -24,35 +24,28 @@ not;
 reported precisely or treated as an uninferable PC discontinuity (see
 <<tab:context-type>>);
 * _ppccd_br._ As above, but branch map not empty;
-* _er_n._ Instruction retirement and exception signalled on the same
-cycle, or Trace notify trigger (see
-<<tab:debugModuleTriggerSupport>>);
-* _exc_only._ Exception or interrupt signalled without simultaneous
-retirement;
+* _ntf._ Trace notify trigger (see <<tab:debugModuleTriggerSupport>>);
 * _cci._ context change that can be reported imprecisely (see
 <<tab:context-type>>);
 * _rpt_br._ Report branches due to full branch map or misprediction;
 * _branches._ The number of branches encountered but not yet reported to
 the decoder;
 * _pbc._ Correctly predicted branches count (always zero if branch
 predictor disabled or not present);
-* _Reported?_ "Exception previous" reported with *thaddr* = 0 on the
-cycle it occured because it was preceded by an updiscon or immediately
-followed by another exception;
+* _trep_ Previous trap already reported with *thaddr* = 0 because it was preceded by an updiscon or immediately followed by another exception;
 * _resync count._ A counter used to keep track of when it is necessary
 to send a synchronization packet (see <<sec:resync>>);
-* _max_resync._ The resync counter value that schedules a
-synchronization packet (see <<sec:resync>>);
-* _resync_br._ The resync counter has reached the maximum value and
+* _resync2_br._ The resync FSM is in state 2 and
 there are entries in the branch map that have not yet been output (see
 <<sec:resync>>).
+* _resync3._ The resync FSM is in state 3  (see <<sec:resync>>);
 
 <<fig:algo>> shows instruction by instruction behavior, as
 would be seen in a single-retirement system only. Whilst the core to
 encoder interface allows the RISC-V hart to provide information on
 multiple retiring instructions simultaneously, the resultant packet
 sequence generated by the encoder must be the same as if retiring one
-instruction at a time.
+instruction at a time.  Note that even with a single-retirement system it is possible to retire an instruction and report a trap simultaneously (*itype* = 1 or 2 and *iretire* = 1).  In this case the flow diagram must be traversed twice, first for the retired instruction, and then for the trap.
 
 A 3-stage pipeline within the encoder is assumed, such that the encoder
 has visibility of the current, previous and next instructions. All
@@ -137,9 +130,15 @@ When the resync is required, the primary objective is to output a format
 needing any of the history. However, if the decoder is already synced,
 then it is also required that it can continue to follow the execution
 path up to and through the format 3 packet seamlessly. As such, before
-outputting a format 3 packet, it is necessary to output a format 1
+outputting a format 3 packet, it is necessary to output a format 0/1
 packet for the preceding instruction if there are any unreported
-branches (because format 3 does not contain a branch map). The format 3
+branches (because format 3 does not contain a branch map). There are several supported options for incrementing the resync timer (packets, cycle or instruction half-words), and as such updates to the timer do not necessarily coincide with instrucitn retirements.  A small, independent FSM can be used to ensure the required packets are output in the required order, as follows: 
+
+ * *State 1*: resync_count < max_resync.  Transition to *State 2* when resync_count >= max_resync
+ * *State 2*: output packet of unreported branches if required, transition to *state 3*
+ * *State 3*: output sync packet, reset resync_count and transition to *State 1*.
+
+The format 3
 will be sent if the resync timer has been exceeded. On the cycle before
 this (when the resync timer value has been exactly reached), a format 1
 will be generated if the branch map is not empty.

fragmentCodeAndTransport.adoc

@@ -1,3 +1,4 @@
+[[fragments]]
 == Code fragment and transport
 
 This section shows fragments of code, and associated data from one of
@@ -98,24 +99,29 @@ line 56. The least significant byte is output first, this means 32 is
 byte 0, 04 is byte 1 and and the final value 02 is byte 4.
 
 ==== Siemens transport
-
-The packet format is given in
-<<fig:packet-format>>. So this means the packet
-will be packed as follows:
+The packet is encapsulated according to the https://github.com/riscv-non-isa/e-trace-encap/releases/latest/[Unformatted Trace & Diagnostic Data Packet Encapsulation for RISC-V Specification], with the following attributes: 
 
 * Header - 1 byte
-* Index - N bits. As an example use 6 bits and the value of 1.
-* Optional Siemens timestamp - 2 bytes. This example has no timestamp
-* A type field for the packet of 2 bits ’01’ meaning instruction trace
-* Payload - [32 04 00 00 02]
+* SrcID - N bits. As an example use 6 bits and the value of 1.
+* This example has no timestamp
+* A 2-bit type field with ’10’ meaning instruction trace
+* trace_payload - [0x32 0x04 0x00 0x00 0x02]
 
 Since the Siemens transport is byte stream based the data seen will be:
 
-`[0x05][0x41][0x32 0x04 0x00 0x00 0x02]`
+`[0x06][0x81][0x32 0x04 0x00 0x00 0x02]`
 
 ==== ATB transport
 
-Assuming at 32 bit ATB transport results in the following ATB transfers
+The packet is encapsulated according to the https://github.com/riscv-non-isa/e-trace-encap/releases/latest/[Unformatted Trace & Diagnostic Data Packet Encapsulation for RISC-V Specification], with the following attributes:
+
+* Header - 1 byte carried via ATDATA bus.
+* SrcID - 0 bits as the SrcID is carried via the ATID bus.
+* This example has no timestamp
+* No type field (encoder has no data trace support)
+* trace_payload - [0x32 0x04 0x00 0x00 0x02] carried via ATDATA bus.
+
+Assuming a 32 bit ATB transport results in the following ATB transfers
 
 `[ATID=1] [ATBYTES = 3] [ATDATA = 0x00043205]` +
 `[ATID=1] [ATBYTES = 1] [ATDATA = 0x00000200]`
@@ -207,20 +213,26 @@ byte 0, 00 is byte 1 and and the final value 20 is byte 9.
 
 ==== Siemens transport
 
-The packet format is given in
-<<fig:packet-format>>. So this means the packet
-will be packed as follows:
+The packet is encapsulated according to the https://github.com/riscv-non-isa/e-trace-encap/releases/latest/Unformatted Trace & Diagnostic Data Packet Encapsulation for RISC-V Specification], with the following attributes: 
 
 * Header - 1 byte
-* Index - N bits. As an example use 6 bits and the value of 0xA
-* Optional Siemens timestamp - 2 bytes. This example has no timestamp
-* A type field for the packet of 2 bits '01' meaning instruction trace
-* Payload - [0xBD 0xAA 0xAA 0x68 0x00 0x00 0x20]
+* SrcID - N bits. As an example use 6 bits and the value of A.
+* This example has no timestamp
+* A 2-bit type field with ’10’ meaning instruction trace
+* trace_payload - [0xBD 0xAA 0xAA 0x68 0x00 0x00 0x20]
 
-`[0x7][0x29][0xBD 0xAA 0xAA 0x68 0x00 0x00 0x20]`
+`[0x8][0x8A][0xBD 0xAA 0xAA 0x68 0x00 0x00 0x20]`
 
 ==== ATB transport
 
+The packet is encapsulated according to the https://github.com/riscv-non-isa/e-trace-encap/releases/latest/[Unformatted Trace & Diagnostic Data Packet Encapsulation for RISC-V Specification], with the following attributes:
+
+* Header - 1 byte carried via the ATDATA bus.
+* SrcID - 0 bits as the SrcID is carried via the ATID bus.
+* This example has no timestamp
+* No type field (encoder has no data trace support)
+* trace_payload - [0xBD 0xAA 0xAA 0x68 0x00 0x00 0x20] carried via the ATDATA bus
+
 Assuming at 32 bit ATB transport results in the following ATB transfers
 
 `[ATID=0xA] [ATBYTES = 3] [ATDATA = 0xAAAABD07]` +
@@ -295,19 +307,26 @@ byte 0, 00 is byte 1 and and the final value 10 is byte 8.
 
 ==== Siemens transport
 
-The packet format is given in <<fig:packet-format>>. So this means the packet
-will be packed as follows:
+The packet is encapsulated according to the https://github.com/riscv-non-isa/e-trace-encap/releases/latest/[Unformatted Trace & Diagnostic Data Packet Encapsulation for RISC-V Specification], with the following attributes: 
 
 * Header - 1 byte
-* Index - N bits. As an example use 6 bits and the value of 0x5
-* Optional timestamp - 2 bytes. This example has no timestamp
-* A type field for the packet of 2 bits '01' meaning instruction trace
-* Payload - [0x73 0x00 0x00 0x00 0x00 0x91 0x82 0x00 0x10]
+* SrcID - N bits. As an example use 6 bits and the value of 5.
+* This example has no timestamp
+* A 2-bit type field with ’10’ meaning instruction trace
+* trace_payload - [0x73 0x00 0x00 0x00 0x00 0x91 0x82 0x00 0x10]
 
-`[0x9][0x15][0x73 0x00 0x00 0x00 0x00 0x91 0x82 0x00 0x10]`
+`[0xA][0x85][0x73 0x00 0x00 0x00 0x00 0x91 0x82 0x00 0x10]`
 
 ==== ATB transport
 
+The packet is encapsulated according to the https://github.com/riscv-non-isa/e-trace-encap/releases/latest/[Unformatted Trace & Diagnostic Data Packet Encapsulation for RISC-V Specification], with the following attributes:
+
+* Header - 1 byte carried via the ATDATA bus.
+* SrcID - 0 bits as the SrcID is carried via the ATID bus.
+* This example has no timestamp
+* No type field (encoder has no data trace support)
+* trace_payload - [0x73 0x00 0x00 0x00 0x00 0x91 0x82 0x00 0x10] carried via the ATDATA bus.
+
 Assuming at 32 bit ATB transport results in the following ATB transfers
 
 `[ATID=0x5] [ATBYTES = 3] [ATDATA = 0x00007309]` +

header.adoc

@@ -2,8 +2,8 @@
 Gajinder Panesar <[email protected]>, Iain Robertson <[email protected]>
 :description: Efficient Trace for RISC-V
 :company: RISC-V.org
-:revdate: April 19, 2024
-:revnumber: 2.0.3
+:revdate: TBD, 2024
+:revnumber: 2.0
 :url-riscv: http://riscv.org
 :doctype: book
 :pdf-theme: docs-resources/themes/riscv-pdf.yml
@@ -46,14 +46,24 @@ endif::[]
 [%autowidth,align="center",float="center",cols="<,<",options="header"]
 |===
 |2.0|Baseline
-|2.0.1 |Clarifications only - no changes to normative behaviour. +
-- Control field definitions removed from section 2, which now references the xref:https://github.com/riscv-non-isa/tg-nexus-trace/blob/master/docs/RISC-V-Trace-Control-Interface.adoc[RISC-V Trace Control Interface Specification] +
+|15-Dec-2023 |Clarifications only - no changes to normative behaviour. +
+- Control field definitions removed from section 2, which now references the xref:https://github.com/riscv-non-isa/e-trace-encap/releases/latest/[RISC-V Trace Control Interface Specification] +
 - Added detail on handling of multi-load/store instructions for data trace to <<sec:DataInterfaceRequirements>>. +
 - Removed references to tail-calls in jump classifications in <<sec:InstructionInterfaceRequirements>>. +
 - Corrected typos where `lrid` was inadvertently refered to by an earlier name (`index`) in <<sec:data-loadstore>>. +
 - Corrected reference decoder in <<Decoder>> to cover a corner-case related to trap returns.
-|2.0.2 |First version in AsciiDoc format.
-|2.0.3 |Formatting and typo fixes.
+|05-Mar-2024 |First version in AsciiDoc format.
+|19-Apr-2024 |Formatting and typo fixes.
+|This edition |
+- Minor clarifications, formatting and typo fixes;  +
+- Updated <<packets>> and <<fragments>> to reference the https://github.com/riscv-non-isa/e-trace-encap/releases/latest/[Unformatted Trace & Diagnostic Data Packet Encapsulation for RISC-V Specification]; +
+- Removed ambiguity between 'last' and 'final'.  Last was previously used to mean both the instruction before the current one, and the final instruction traced; +
+- Clarified behaviour when trace-on and trace-off triggers occur both occur in the same cycle (see <<sec:trigger>>); +
+- Clarified that full synchronization also takes place on a privilege change (see <<sec:synchronization>> and <<sec:thaddr>>); +
+- Reworded jump classifications in jump classifications in <<sec:InstructionInterfaceRequirements>> to align with terminology used in other specifications; +
+- Clarified when to issue sync-support packet when trace is enabled (see <<sec:format33>>); +
+- Updated reference encoding algorithm to generalize resync behaviour and add missing trap conditions (see <<Algorithm>>).
+
 |===
 
 [preface]