Updating revision history for Issue 154

branchTrace.adoc

@@ -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.

fragmentCodeAndTransport.adoc

@@ -1,3 +1,4 @@
+[[fragments]]
 == Code fragment and transport
 
 This section shows fragments of code, and associated data from one of

header.adoc

@@ -47,14 +47,22 @@ endif::[]
 |===
 |2.0|Baseline
 |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/tg-nexus-trace/blob/master/docs/RISC-V-Trace-Control-Interface.adoc[RISC-V Trace Control Interface Specification] +
+- 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.
 |05-Mar-2024 |First version in AsciiDoc format.
 |19-Apr-2024 |Formatting and typo fixes.
-|TBD |Details to follow.
+|TBD |
+- 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>>)
+
 |===
 
 [preface]

ingressPort.adoc

@@ -13,8 +13,8 @@ The following information is mandatory:
 
 * The number of instructions that are being retired;
 * Whether there has been an exception or interrupt, and if so the cause
-(from the *_ucause/scause/vscause/mcause_* CSR) and trap value (from the
-*_utval/stval/vstval/mtval_* CSR).
+(from the *_scause/vscause/mcause_* CSR) and trap value (from the
+*_stval/vstval/mtval_* CSR).
 +
 The register set to output should be the set that is updated as a result
 of the exception (i.e. the set associated with the privilege level
@@ -43,14 +43,14 @@ The following information is optional:
 * The _instruction_type_ of instructions for:
 ** Calls with a target that _cannot_ be inferred from the source code;
 ** Calls with a target that _can_ be inferred from the source code;
-** Jumps with a target that _cannot_ be inferred from the source code;
-** Jumps with a target that _can_ be inferred from the source code;
+** Other jumps without linkage with a target that _cannot_ be inferred from the source code;
+** Other jumps without linkage with a target that _can_ be inferred from the source code;
 ** Returns with a target that _cannot_ be inferred from the source code;
 ** Returns with a target that _can_ be inferred from the source code;
 ** Co-routine swap;
-** Other jumps which don't fit any of the above classifications with a
+** Other jumps with linkage which don't fit any of the above classifications with a
 target that _cannot_ be inferred from the source code;
-** Other jumps which don't fit any of the above classifications with a
+** Other jumps with linkage which don't fit any of the above classifications with a
 target that _can_ be inferred from the source code.
 * If context or time is supported then the _instruction_address_ for:
 ** The last instruction retired before a context or a time change;
@@ -119,7 +119,7 @@ calling convention:
 ** *_jalr_* x5, rs where rs != x1;
 ** *_c.jalr_* rs1 where rs1 != x5;
 ** *_c.jal_*.
-* _Jumps_:
+* _Other jumps without linkage_:
 ** *_jal_* x0;
 ** *_c.j_*;
 ** *_jalr_* x0, rs where rs != x1 and rs != x5;
@@ -132,7 +132,7 @@ x5;
 ** *_jalr_* x1, x5;
 ** *_jalr_* x5, x1;
 ** *_c.jalr_* x5.
-* _Other_:
+* _Other jumps with linkage_:
 ** *_jal_* rd where rd != x0 and rd != x1 and rd != x5;
 ** *_jalr_* rd, rs where rs != x1 and rs != x5 and rd != x0 and rd != x1
 and rd != x5.
@@ -194,10 +194,10 @@ BR group signals instead.
 |*itype*[_itype_width_p_-1:0] | MR | Termination type of the instruction
 block. Encoding given in <<tab:itype>> (see <<JumpClasses>> for definitions of codes 6 - 15).
 |*cause*[_ecause_width_p_-1:0] | M | Exception or interrupt cause
-(*_ucause/scause/ vscause/mcause_*). Ignored unless **itype**=1 or 2.
+(*_scause/ vscause/mcause_*). Ignored unless **itype**=1 or 2.
 |*tval*[_iaddress_width_p_-1:0] | M | The associated trap value, e.g. the
 faulting virtual address for address exceptions, as would be written to
-the *utval/stval/vstval/mtval* CSR. Future optional extensions may
+the *stval/vstval/mtval* CSR. Future optional extensions may
 define *tval* to provide ancillary information in cases where it
 currently supplies zero. Ignored unless **itype**=1.
 |*priv*[_privilege_width_p_-1:0] | M | Privilege level for all
@@ -244,20 +244,20 @@ instruction is 2^*ilastsize*^ half-words.
 | *Signal* | *Group* | *Function*
 |*iretire*[0:0] | SR | Number of instructions retired in this block (0 or
 1).
-|*ilastsize*[_ilastsize_width_p-1_:0] | SR | The size of the retired
-instruction is 2^*ilastsize*^ half-words.
+|*ilastsize*[_ilastsize_width_p-1_:0] | SR | The size of the last retired
+instruction in this block is 2^*ilastsize*^ half-words.
 |===
 
 [[tab:itype]]
 .Instruction Type (*itype*) encoding
 [%autowidth,align="center",float="center",cols="<,<",options="header"]
 |===
 | *Value* | *Description*
-| 0 |Final instruction in the block is none of the other named *itype*
+| 0 |Last instruction in the block is none of the other named *itype*
 codes
-|1 | Exception. An exception that traps occurred following the final
+|1 | Exception. An exception that traps occurred following the last
 retired instruction in the block
-|2 | Interrupt. An interrupt that traps occurred following the final
+|2 | Interrupt. An interrupt that traps occurred following the last
 retired instruction in the block
 |3 | Exception or interrupt return
 |4 | Nontaken branch
@@ -289,7 +289,7 @@ retired instruction in the block
 |7 | reserved
 |===
 
-The information presented in a block represents a contiguous block of
+The information presented in a block represents a contiguous sequence of
 instructions starting at *iaddr*, all of which retired in the same
 cycle. Note if *itype* is 1 or 2 (indicating an exception or an
 interrupt), the number of instructions retired may be zero. *cause* and
@@ -306,7 +306,7 @@ block.
 *itype* can be 3 or 4 bits wide. If _itype_width_p_ is 3, a single code
 (6) is used to indicate all uninferable jumps. This is simpler to
 implement, but precludes use of the implicit return mode (see
-<<sec:implicit-return>>), which requires jump types to be fully classified.
+<<sec:implicit-return>>), which requires jump types to be fully classified.    
 
 Whilst *iaddr* is typically a virtual address, it does not affect the
 encoder's behavior if it is a physical address.
@@ -492,6 +492,11 @@ from the oldest instruction retired in the cycle that Trace-on is
 asserted, and stops following the newest instruction retired in the
 cycle that Trace-off is asserted (subject to any optional filtering).
 
+It follows from this that:
+
+*  if tracing is enabled and trace-off occurs on the cycle before trace-on, then tracing will continue unimpeded (i.e. it stays on);
+* if tracing is disabled and trace-on and trace-off triggers occur simultaneously then only the instructions retired in that cycle will be traced. 
+
 Trace-notify provides means to ensure that a specified instruction is
 explicitly reported (subject to any optional filtering). This capability
 is sometimes known as a watchpoint.
@@ -574,7 +579,7 @@ comprises 4 elements, and shows the instruction information reported for
 each load and store. As detailed in section
 #sec:InstructionTraceInterface[1.2], this takes the form of the address
 of an instruction, the length of the block (1 for a single instruction)
-and the type of the final instruction in the block. In each element,
+and the type of the last instruction in the block. In each element,
 ’Block’ indicates a block of 1 or more instructions (i.e. could also be
 a single instruction), whereas ’Single’ indicates a single instruction
 (i.e. a block with a length of 1).
@@ -654,8 +659,11 @@ access instruction is retired. Required if there are replicated
 instruction block signals
 |*lrid*[_lrid_width_p_-1:0] | S | Load request ID. Valid when *dretire*
 is high
-|*lresp*[_lresp_width_p_-1:0] | S | Load response:: None: reserved: Okay.
-Load successful; *ldata* valid: Error. Load failed; *ldata* not valid
+|*lresp*[_lresp_width_p_-1:0] | S | Load response: +
+0: None +
+1: reserved +
+2: Okay. Load successful; *ldata* valid +
+3: Error. Load failed; *ldata* not valid
 |*lid*[_lrid_width_p_-1:0] | S | Split Load ID. Valid when *lresp* is
 non-zero
 |*sdata*[_sdata_width_p_-1:0] | S | Store data. Valid when *dretire* is
@@ -719,7 +727,7 @@ encoder at the block level, and the block boundaries are invisible to
 the decoder. For instruction trace, all instructions in a block are
 traced if any of the instructions in that block match the filtering
 criteria. That is fine for instruction trace - the address of the 1st
-and last traced instruction are output explicitly. There will be some
+and final traced instruction are output explicitly. There will be some
 fuzziness about precisely what those addresses will be depending on
 where the block boundaries fall, but this is not a concern as everything
 is always self-consistent.

introduction.adoc

@@ -81,13 +81,16 @@ the RISC-V hart
 * *delta*: a change in the program counter that is other than the
 difference between two instructions placed consecutively in memory
 * *discontinuity*: another name for ’delta’ (see above)
+* *E-Trace*: Abbreviation of _Efficient Trace for RISC-V_.
 * *ELF*: executable and linkable format
 * *encoder*: a piece of hardware that takes in instruction execution
 information from a RISC-V hart and transforms it into trace packets
 * *EPC*: exception program counter
 * *exception*: an unusual condition occurring at run time associated
 with an instruction in a RISC-V hart
 * *hart*: a RISC-V hardware thread
+* *final instruction*: the instruction retired immediately before tracing stops.
+* *last instruction*: in a block of sequentially retired instructions, the instruction at the end of the sequence
 * *interrupt*: an external asynchronous event that may cause a RISC-V
 hart to experience an unexpected transfer of control
 * *ISA*: instruction set architecture