From 9be60cacf95e0d0ba0a2dc96a42b39364c593643 Mon Sep 17 00:00:00 2001 From: Iain Robertson Date: Sun, 20 Oct 2024 18:43:45 +0100 Subject: [PATCH 1/6] Clarifications for issue-93 and fixes for a fwe LaTeX to adoc translation errors --- ingressPort.adoc | 22 ++++++++++++---------- introduction.adoc | 2 ++ payload.adoc | 41 +++++++++++++++++++++-------------------- timestamping.adoc | 2 +- 4 files changed, 36 insertions(+), 31 deletions(-) diff --git a/ingressPort.adoc b/ingressPort.adoc index fe245bf..4094507 100644 --- a/ingressPort.adoc +++ b/ingressPort.adoc @@ -244,8 +244,8 @@ 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]] @@ -253,11 +253,11 @@ instruction is 2^*ilastsize*^ half-words. [%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 @@ -574,7 +574,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 +654,10 @@ 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: + + - None: reserved + + - Okay. Load successful; *ldata* valid + + - 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 +721,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. diff --git a/introduction.adoc b/introduction.adoc index fad720f..3b4a7d2 100644 --- a/introduction.adoc +++ b/introduction.adoc @@ -88,6 +88,8 @@ information from a RISC-V hart and transforms it into trace packets * *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 diff --git a/payload.adoc b/payload.adoc index dab4a5e..afe9656 100644 --- a/payload.adoc +++ b/payload.adoc @@ -120,8 +120,8 @@ instruction |*context*| _context_width_p_, or 0 if _nocontext_p_ is 1| The instruction context. |*address*| _iaddress_width_p - iaddress_lsb_p_| Full instruction -address. Address alignment is determined by _iaddress_lsb_p_ Address -must be left shifted in order to recreate original byte address. +address. Address alignment is determined by _iaddress_lsb_p_: *address* +must be left shifted by _iaddress_lsb_p_ in order to recreate original byte address. |=== ==== Format 3 *branch* field @@ -178,8 +178,8 @@ address. When set to 0, *address* points to the EPC for an exception at the target of an updiscon, and is undefined for other exceptions and interrupts. |*address*| _iaddress_width_p - iaddress_lsb_p_| Full instruction -address. Address alignment is determined by _iaddress_lsb_p_ Address -must be left shifted in order to recreate original byte address. +address. Address alignment is determined by _iaddress_lsb_p_: *address* +must be left shifted by_iaddress-lsb_p_ in order to recreate original byte address. |*tval*| _iaddress_width_p_| Value from appropriate *utval/stval/vstval/mtval* CSR. Field omitted for interrupts |=== @@ -255,14 +255,14 @@ optional modes supported by the encoder. |*subformat*| 2| 11 (support): Supporting information for the decoder |*ienable*| 1| Indicates if the instruction trace encoder is enabled |*encoder_mode*| N| Identifies trace algorithm Details and number of -bits implementation dependent. Currently Branch trace is the only mode +bits implementation dependent. Currently, Branch Trace is the only mode defined, indicated by the value 0. |*qual_status*| 2| 00 (no_change): No change to filter qualification + -01 (ended_rep): Qualification ended, preceding *te_inst* sent explicitly to indicate last qualification +01 (ended_rep): Qualification ended, preceding *te_inst* sent explicitly to indicate final qualification instruction + 10 (trace_lost): One or more instruction trace packets lost. + 11 (ended_ntr): Qualification ended, preceding *te_inst* would have been -sent anyway due to an updiscon, even if it wasn't the last qualified +sent anyway due to an updiscon, even if it wasn't the final qualified instruction |*ioptions*| N| Values of all instruction trace run-time configuration bits + @@ -289,13 +289,13 @@ be + [[sec:qual-status]] ==== Format 3 subformat 3 *qual_status* field -When tracing ends, the encoder reports the address of the last traced +When tracing ends, the encoder reports the address of the final traced instruction, and follows this with a format 3, subformat 3 (supporting information) packet. Two codes are provided for indicating that tracing has ended: *ended_rep* and *ended_ntr*. This relates to exactly the same ambiguous case described in detail in <>, and in principle, the mechanism described in that section can be used to -disambiguate when the last traced instruction is at looplabel. However, +disambiguate when the final traced instruction is at looplabel. However, that mechanism relies on knowing when creating the format 1/2 packet, that a format 3 packet will be generated from the next instruction. This is possible because the encoding algorithm uses a 3-stage pipe with @@ -427,11 +427,11 @@ anyway as a result of the *_JALR_*). Looking at this from the perspective of the decoder, the decoder receives a format 1/2 reporting the address of the 1st instruction in -the loop (looplabel). It follows the execution path from the last +the loop (looplabel). It follows the execution path from the previous reported address, until it reaches looplabel. Because looplabel is not preceded by an uninferable discontinuity, it must take the value of *notify* and *updiscon* into consideration, and may need to wait for the -next packet in order to determine whether it has reached the final +next packet in order to determine whether it has reached the most recently retired instruction: * If *updiscon* == !*notify*, this indicates case 2. The decoder must @@ -448,7 +448,7 @@ The decoder has reached the correct instruction. This example uses an exception at looplabel + 4, but anything that could cause a format 3 for looplabel + 4 would result in the same behavior: a privilege change, or the expiry of the resync timer. It could also occur -if looplabel was the last traced instruction (because tracing was +if looplabel was the final traced instruction (because tracing was disabled for some reason). See <> for further discussion of this point. @@ -481,7 +481,7 @@ addresses, and a _te_inst_ packet will be generated with *irreport* set to the opposite value to *updiscon* if a misprediction occurs. In some cases it is also necessary to report the current stack depth or -call count if the packet is reporting the last instruction before an +call count if the packet is reporting the nstruction innediately before an exception, interrupt, privilege change or resync. There are two cases of concern: @@ -492,9 +492,9 @@ follow the execution path until it encountered the reported address from the outermost nested call; * If the reported address is not the instruction following a return, the encoder must report the current stack depth or call count unless: -** There have been no returns since the last call (in which case the +** There have been no returns since the previous call (in which case the decoder will correctly stop in the innermost call), or -** There has been at least one branch since the last return (in which +** There has been at least one branch since the previous return (in which case the decoder will correctly stop in the call where there are no unprocessed branches). + @@ -641,8 +641,8 @@ branches) |*branch_count*| 32| Count of the number of correctly predicted branches, minus 31. |*branch_fmt*| 2| 00 (no-addr): Packet does not contain an *address*, -and the branch following the last correct prediction failed. -11: -(cannot occur for this format) +and the branch following the previous correct prediction failed. + +01 - 11: (cannot occur for this format) |=== .Packet format 0, subformat 0 - address, branch count @@ -656,9 +656,10 @@ branches) |*branch_count*| 32| Count of the number of correctly predicted branches, minus 31. |*branch_fmt*| 2| 10 (addr): Packet contains an *address*. If this -points to a branch instruction, then the branch was predicted correctly. -(addr-fail): Packet contains an *address* that points to a branch which -failed the prediction. ,01: (cannot occur for this format) +points to a branch instruction, then the branch was predicted correctly. + +10 (addr-fail): Packet contains an *address* that points to a branch which +failed the prediction. + +00, 01: (cannot occur for this format) |*address*| _iaddress_width_p - iaddress_lsb_p_| Differential instruction address. |*notify*| 1| If the value of this bit is different from the MSB of diff --git a/timestamping.adoc b/timestamping.adoc index 44b2eaa..6b15694 100644 --- a/timestamping.adoc +++ b/timestamping.adoc @@ -8,7 +8,7 @@ In many systems it is desirable to periodically insert a timestamp packet into the trace stream, effectively marking that point in the stream with a time value. -This can be used to judge "time" between various point in the trace +This can be used to judge "time" between various points in the trace stream and, more notably, to be able to correlate trace streams from different harts (i.e. this point in hart A's stream occurred at roughly the same time as that point in hart B's trace stream). The former helps From 0031689bb0c4dae75b185d7030994779bfd4137d Mon Sep 17 00:00:00 2001 From: Iain Robertson Date: Mon, 21 Oct 2024 00:00:34 +0100 Subject: [PATCH 2/6] revert change related to Issue 146 --- ingressPort.adoc | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/ingressPort.adoc b/ingressPort.adoc index 4094507..ca8e300 100644 --- a/ingressPort.adoc +++ b/ingressPort.adoc @@ -654,10 +654,8 @@ 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:: None: reserved: Okay. +Load successful; *ldata* valid: 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 From 4dcf50fa0b2a99167811386bfdd183dd0e395ac4 Mon Sep 17 00:00:00 2001 From: Iain Robertson Date: Fri, 25 Oct 2024 15:00:28 -0700 Subject: [PATCH 3/6] Fix more adoc mis-translations --- payload.adoc | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/payload.adoc b/payload.adoc index afe9656..4fb3eec 100644 --- a/payload.adoc +++ b/payload.adoc @@ -521,8 +521,15 @@ is enabled (see <>). |*format*| 2| 01 (diff-delta): includes branch information and may include differential address |*branches*| 5| Number of valid bits *branch_map*. The number of bits -of *branch_map* is determined as follows: : (cannot occur for this -format) : 1 bit -3: 3 bits -7: 7 bits -15: 15 bits -31: 31 bits For +of *branch_map* is determined as follows: + +0: (cannot occur for this +format) + +1: 1 bit + +2-3: 3 bits + +4-7: 7 bits + +8-15: 15 bits + +16-31: 31 bits + +For example if branches = 12, *branch_map* is 15 bits long, and the 12 LSBs are valid. |*branch_map*| Determined by *branches* field.| An array of bits @@ -562,8 +569,9 @@ bits in this field will also be the same value as *updiscon*. |*format*| 2| 01 (diff-delta): includes branch information and may include differential address |*branches*| 5| Number of valid bits in *branch_map*. The length of -*branch_map* is determined as follows: : 31 bits, no *address* in packet --31: (cannot occur for this format) +*branch_map* is determined as follows: + +0: 31 bits, no *address* in packet + +1-31: (cannot occur for this format) |*branch_map*| 31| An array of bits indicating whether branches are taken or not. Bit 0 represents the oldest branch instruction executed. For each bit: : branch taken : branch not taken @@ -697,8 +705,14 @@ extensions |*index*| __cache_size_p__| Jump target cache index of entry containing target address. |*branches*| 5| Number of valid bits in *branch_map*. The length of -*branch_map* is determined as follows: : (cannot occur for this format) -: 1 bit -3: 3 bits -7: 7 bits -15: 15 bits -31: 31 bits For example if +*branch_map* is determined as follows:+ +0: (cannot occur for this format) + +1: 1 bit + +2-3: 3 bits + +4-7: 7 bits + +8-15: 15 bits + +16-31: 31 bits + +For example if branches = 12, *branch_map* is 15 bits long, and the 12 LSBs are valid. |*branch_map*| Determined by *branches* field.| An array of bits From 348fe50fe89dc8886744fdd82879e79501061785 Mon Sep 17 00:00:00 2001 From: IainCRobertson <48293834+IainCRobertson@users.noreply.github.com> Date: Tue, 12 Nov 2024 17:27:16 +0000 Subject: [PATCH 4/6] Update payload.adoc Co-authored-by: Paul Donahue <48959409+pdonahue-ventana@users.noreply.github.com> Signed-off-by: IainCRobertson <48293834+IainCRobertson@users.noreply.github.com> --- payload.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/payload.adoc b/payload.adoc index 4fb3eec..9683c2a 100644 --- a/payload.adoc +++ b/payload.adoc @@ -481,7 +481,7 @@ addresses, and a _te_inst_ packet will be generated with *irreport* set to the opposite value to *updiscon* if a misprediction occurs. In some cases it is also necessary to report the current stack depth or -call count if the packet is reporting the nstruction innediately before an +call count if the packet is reporting the instruction immediately before an exception, interrupt, privilege change or resync. There are two cases of concern: From fe78bb81351e3a940c8481979ea0a9c40734952c Mon Sep 17 00:00:00 2001 From: IainCRobertson <48293834+IainCRobertson@users.noreply.github.com> Date: Tue, 12 Nov 2024 17:30:11 +0000 Subject: [PATCH 5/6] Update payload.adoc Co-authored-by: Paul Donahue <48959409+pdonahue-ventana@users.noreply.github.com> Signed-off-by: IainCRobertson <48293834+IainCRobertson@users.noreply.github.com> --- payload.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/payload.adoc b/payload.adoc index 9683c2a..f4cb6c6 100644 --- a/payload.adoc +++ b/payload.adoc @@ -665,7 +665,7 @@ branches) branches, minus 31. |*branch_fmt*| 2| 10 (addr): Packet contains an *address*. If this points to a branch instruction, then the branch was predicted correctly. + -10 (addr-fail): Packet contains an *address* that points to a branch which +11 (addr-fail): Packet contains an *address* that points to a branch which failed the prediction. + 00, 01: (cannot occur for this format) |*address*| _iaddress_width_p - iaddress_lsb_p_| Differential From 687eff9a55f9cf2d58dac8d5fcdd6641b946cb09 Mon Sep 17 00:00:00 2001 From: Iain Robertson Date: Mon, 17 Feb 2025 17:18:12 +0000 Subject: [PATCH 6/6] Updating revision history for Issue 93 --- header.adoc | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/header.adoc b/header.adoc index ec0ba57..ccc785d 100644 --- a/header.adoc +++ b/header.adoc @@ -47,14 +47,17 @@ 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 <>. + - Removed references to tail-calls in jump classifications in <>. + - Corrected typos where `lrid` was inadvertently refered to by an earlier name (`index`) in <>. + - Corrected reference decoder in <> 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 | +- Formatting and typo fixes. + +- Removed ambiguity between 'last' and 'final'. Last was previously used to mean both the instruction before the current one, and the final instruction traced. + |=== [preface]