-
Notifications
You must be signed in to change notification settings - Fork 32
/
RISC-V-N-Trace.adoc
2079 lines (1626 loc) · 134 KB
/
RISC-V-N-Trace.adoc
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
[[header]]
:description: RISC-V N-Trace (Nexus-based Trace)
:company: RISC-V.org
:revdate: Sep 16, 2024
:revnumber: 1.0_rc51
:revremark: Frozen state (Ratification Ready)
:url-riscv: http://riscv.org
:doctype: book
:preface-title: Preamble
:colophon:
:appendix-caption: Appendix
:title-logo-image: image:docs-resources/images/risc-v_logo.svg[pdfwidth=3.25in,align=center]
// Settings:
:experimental:
:reproducible:
:WaveDromEditorApp: wavedrom-cli
:pdf-theme: ./riscv-pdf.yml
:pdf-fontsdir: docs-resources/fonts/
:imagesoutdir: images
:icons: font
:lang: en
:listing-caption: Listing
:sectnums:
:sectnumlevels: 5
:toclevels: 5
:toc: left
:source-highlighter: pygments
ifdef::backend-pdf[]
:source-highlighter: coderay
endif::[]
:data-uri:
:hide-uri-scheme:
:stem: latexmath
:footnote:
:xrefstyle: short
:bibtex-file: example.bib
:bibtex-order: alphabetical
:bibtex-style: apa
= RISC-V N-Trace (Nexus-based Trace) Specification
RISC-V N-Trace Task Group
// Preamble
[WARNING]
.This document is in the link:http://riscv.org/spec-state[Frozen state]
====
Change is extremely unlikely. A high threshold will be used, and a change will only occur because of some truly critical issue being identified during the public review cycle. Any other desired or needed changes can be the subject of a follow-on new extension.
====
[preface]
== Change Log
PDF generated on: {localdatetime}
=== Version 1.0_rc51
* 2024-09-16
** Frozen (Ratification Ready).
** One clarifications and 3 typos.
=== Version 1.0_rc50
* 2024-08-14
** Frozen (for Public Review)
[Preface]
== Copyright and license information
This specification is licensed under the Creative Commons Attribution 4.0 International License
(CC-BY 4.0). The full license text is available at https://creativecommons.org/licenses/by/4.0/
Copyright 2019-2024 by RISC-V International.
[Preface]
== Contributors
Key contributors to RISC-V N-Trace (Nexus-based Trace) specification in alphabetical order: +
Bruce Ableidinger (SiFive) => Initial SiFive donation, reviews +
Robert Chyla (IAR, SiFive, MIPS) => Most topics, editing, publishing +
Ernie Edgar (SiFive) => Initial SiFive donation, reviews +
Jay Gamoneda (NXP) => Reviews, contributing, editing +
Markus Goehrle (Lauterbach) => Reviews, updates +
Ved Shanbhogue (Rivos) => Detailed Architecture Review Committee notes +
Nino Vidovic (Segger) => Reviews
== Introduction to N-Trace
This *RISC-V N-Trace (Nexus based trace) Specification* is based on the well-established *IEEE-5001 Nexus Standard* tailored to support the trace of RISC-V ISA cores, harts and SoC/MCU designs.
It serves multiple audiences:
* N-Trace encoder logic/IP developers.
* Validation teams testing of N-Trace implementation.
* Debug and trace tools developers.
* Software programmers utilizing the trace for debugging and performance tuning of RISC-V-based systems.
This specification, together with the *RISC-V Trace Control Interface Specification* and *RISC-V Trace Connectors Specification* provide a complete, end-to-end, trace system for RISC-V based SoC.
A trace ingress port, which serves as the connection between the RISC-V hart and the trace system, is defined in the ratified *Efficient Trace for RISC-V Specification*.
This port enables the RISC-V hart to communicate execution information to the trace system.
The N-Trace encoder is responsible for encoding an execution flow into a stream of trace messages.
This document describes an appropriate selection of N-Trace messages compatible with the original IEEE-5001 Nexus Standard.
The primary objective was to define the program flow trace messages. Extensions have been introduced to enable better trace compression. Future versions may include IEEE-5001 Nexus-compatible data and bus trace.
The registers controlling the N-trace decoder are defined by the *RISC-V Trace Control Interface Specification*. This specification is shared with E-trace, so not all registers and register fields are supported by N-trace.
Trace connectors defined by IEEE-5001 Nexus Standard were debug oriented, so could not be directly applied. Instead, industry standard MIPI-compliant connectors are defined in *RISC-V Trace Connectors Specification*. These connectors are pure extensions of debug-only, MIPI-compliant connectors defined by ratified *RISC-V Debug Specification*.
=== Related Specifications
This document provides reference to separated documents developed together with this *RISC-V N-Trace Specification*:
[#RISC-V_Trace_Control_Interface]
* *RISC-V Trace Control Interface Specification* - Defines RISC-V trace control interface.
** This document is intended to be shared with ratified *Efficient Trace for RISC-V Specification*.
* *RISC-V Trace Connectors Specification* - Defines RISC-V trace connectors (for external trace probes).
[#E-Trace_Specification]
Ratified *Efficient Trace for RISC-V Specification* defines RISC-V Trace Ingress Port signals (chapter *4 Instruction Trace Interface*). At the moment of this writing this is version 2.0 (ratified May 5-th 2022).
NOTE: In the future trace ingress port may be defined in separated document - in such a a case reference to E-Trace specification will not be necessary.
////
This comment is taken AS-IS from iommu_intro.adoc file
Please in ditaa figures don't use the minus key '-' in your keyboard when
typing text (like 'non-privileged' in the figure below).
'-' is a special character that is used by ditaa to draw lines, not text.
Instead use a different unicode character that looks similar.
The figure below uses the unicode character with code U+2212 instead of the '-'
character of your keyboard (which has the unicode code U+002B).
Note that in your editor both probably look the same, but when rendered by
ditaa/asciidoc the '-' from your keyboard is used to draw a line, while the
alternative looks as a minus symbol.
If you don't know how to type an unicode character in your editor you might
simply copy the '−' character in the 'non−privileged' word from the drawing
below.
Other potential unicode characters might be found in the following links:
- https://www.compart.com/en/unicode/category/Pd
- https://www.compart.com/en/unicode/bidiclass/ES
////
=== Trace Encoder Interfaces
The diagram below shows one possible implementation with only a single RISC-V hart. In a system with multiple cores/harts the *Trace Ingress Port*, *Trace Encoder Control* and *Trace Encoder* blocks should be replicated for each hart.
The main *Trace Control Layer* controlling other (shared) components in the trace system is not replicated.
[[fig:trace-encoder-interfaces]]
.Trace Encoder Interfaces
["ditaa",shadows=true, separation=false, fontsize: 14]
....
+--- Control register
| read/write
|
+----------+ V +---------------------+
| | | Trace Control Layer |
| Debug |<=======>| |-----> Control of other
| Module | | +-------------+ | trace components
| |<------->| |Trace Encoder| | (transport/storage)
+----------+ ^ +--| Control |----+
^ | +-------------+
| <--- triggers, ^
| stall etc. |
V | <------ Encoder control/status signals
+----------------+ | (bits/fields in registers)
| RISC−V Hart | V
| +---------+ +---------+
| | Trace | | Trace | To N−Trace transport
| | Ingress |======>| Encoder |==============> for multiplexing/
| | Port | ^ | | ^ storage/export
| +---------+ | +---------+ |
| | | +--- Encoded trace messages
| | | Ingress port for single hart (with
+----------------+ +-- signals defined optional source ID)
in E−Trace spec
....
NOTE: Placement of the Trace Encoder and Trace Control Layer are implementation dependent.
=== Definitions and Terminology
[#Terms Used In This Specification]
.Terms Used In This Specification
[cols="20%,~",options="header"]
|======================================================================================================
|Term| Definition
|Message|N-Trace messages are sequences of bytes. First byte of every message includes the TCODE field, which defines the type of information carried in the message and its format. When messages are transmitted or stored, a protocol, described in <<N-Trace Transmission Protocol,N-Trace Transmission Protocol>> chapter, defines the start and the end of each message.
|Field| A field is a distinct piece of the information contained within a message, and messages may contain one or more fields (in addition to the first TCODE field). Fields can be either of fixed-length or variable-length. Several fields may be packed into single byte and single field may span multiple bytes. Definitions of all fields can be found in <<Fields in Messages,Fields in Messages>> chapter.
|Variable-length Field|Specifying that a field is variable-length (*Var* used as field size definition) means that the message must contain the field, but the field's size may vary from a minimum of 1 bit. When messages are transmitted or stored, variable-length fields must end on a byte boundary. If necessary, they must zero-fill bit positions beyond the highest order bit of the variable-length data. Because variable-length fields may be of different lengths in messages of the same type, when messages are transmitted or stored, a protocol, described in <<N-Trace Transmission Protocol,N-Trace Transmission Protocol>> chapter, defines the end of each variable-length field.
|Configurable Field|Configurable field (*Cfg* used as field size) means that existence and size of this field depends on some configuration setting. See <<N-Trace Specific Trace Controls,N-Trace Specific Trace Controls>> chapter for details.
|N-Trace| IEEE-5001 Nexus Standard Based Trace for RISC-V (as defined by this specification).
|E-Trace| Efficient Trace for RISC-V (as defined by <<E-Trace_Specification,E-Trace Specification>>).
|Unconditional Jump|On RISC-V ISA all jump instructions are always unconditional, but these two words are always used together to avoid any confusions with the term 'branch' used by the IEEE-5001 Nexus Standard. The two main sub-categories of unconditional jumps that are relevant for tracing are: direct unconditional jump and indirect unconditional jump.
|Direct Conditional Branch|On RISC-V ISA all branch instructions are always direct and conditional (and also relative), but these three words are always used together to avoid confusion with the term 'branch' used by the IEEE-5001 Nexus Standard.
|======================================================================================================
== Trace Ingress Port
N-Trace uses the same ingress port as specified in <<E-Trace_Specification,E-Trace Specification>> (chapter *4 Instruction Trace Interface*).
* As this specification does not define the data trace yet, sub-chapters *4.3 Data Trace Interface requirements* and *4.4 Data Trace Interface* are not applicable.
* It is an ambition to extract single, shared *RISC-V Trace Ingress Port* specifications (combining this chapter with relevant E-Trace chapter).
** Names of 'itype' values used in this specification are a bit different than names in E-Trace specification. These names were unconditionally enforced by ARC (during review phase) as compulsory in all relevant specifications from now on.
The table below provides a detailed mapping of causes for terminating an instruction block to the corresponding *itype* encoding. It could be used during development of ingress port logic inside of a hart. For some instructions operands matter - for example *JALR rd,rs1* instruction may generate 5 different, distinct *itype* values.
[#Generating itype for different instructions]
.Generating itype for different instructions
[cols="18%,~,35%",options="header"]
|======================================================================================================
|Instruction|Condition/Notes|itype Value/Name
|Exception in instruction|An exception trap that occurred following the final retired instruction in the block.|1 = Exception
|EBREAK, ECALL, C.EBREAK|An exception trap that occurred following the final retired instruction in the block due to these instructions. These instructions do not retire.
|1 = Exception
|Interrupted instruction|An interrupt trap occurred following the final retired instruction in the block.|2 = Interrupt
|MRET, SRET| Return from an exception or interrupt handler. |3 = Trap return
|<<itype_branch,Conditional branch>>|Not-taken direct, conditional branch.|4 = Not-taken branch
|<<itype_branch,Conditional branch>>|Taken direct, conditional branch.|5 = Taken branch
|Any other instruction|All other instructions that are not directly listed in this table.
|0 = No special type
3+|*Values of itype (<<itype_3_4,3-bit>>) (without <<Implicit Return Optimization,Implicit Return Optimization>>*)
|JAL rd |Any direct jump/call. |0 = No special type
|JALR rd, rs |Any indirect jump/call. |6 = Indirect jump (with or without linkage)
|C.J or C.JAL |C extension has direct jump/calls only. |0 = No special type
|CM.JT |Defined by <<zcmt,Zcmt>> extension. |0 = No special type
|CM.JALT |Defined by <<zcmt,Zcmt>> extension. |0 = No special type
|CM.POPRET* |Defined by **Zcmp** extension. |6 = Indirect jump (with or without linkage)
3+|*Values of itype (<<itype_3_4,4-bit>>) (needed for <<Implicit Return Optimization,Implicit Return Optimization>>*). <<link,link>> means *x1* or *x5*.
|JAL rd |rd = `link` |9 = Direct call
| |rd = *x0* |11 = Direct jump (without linkage)
| |rd != `link` and rd != *x0* |15 = Other direct jump (with linkage)
|JALR rd, rs |rd = `link` and rs != `link` |8 = Indirect call
| |rd = `link` and rs = `link` and rd = rs |8 = Indirect call
| |rd = `link` and rs = `link` and rd != rs |12 = Co-routine swap
| |rd != `link` and rs = `link` |13 = Function return
| |rd = *x0* and rs != `link` |10 = Indirect jump (without linkage)
| |rd != `link` and rd != *x0* and rs != `link` |14 = Other indirect jump (with linkage)
|C.JAL |Expands to `JAL x1, offset` |9 = Direct call
|C.JALR rs |rs = *x5* |12 = Co-routine swap
| |rs != *x5* |8 = Indirect call
|C.JR rs |rs = `link` |13 = Function return
| |rs != `link` |10 = Indirect jump (without linkage)
|C.J |Expands to `JAL x0, offset` |11 = Direct jump (without linkage)
|CM.JT |Defined by <<zcmt,Zcmt>> extension. |11 = Direct jump (without linkage)
|CM.JALT |Defined by <<zcmt,Zcmt>> extension. |9 = Direct call
|CM.POPRET* |Defined by **Zcmp** extension. |13 = Function return
|======================================================================================================
[[itype_branch]]
NOTE: Branches (*itype*=4, 5) are always conditional, direct branches. In RISC-V ISA all jumps, calls, returns are always unconditional.
[[itype_3_4]]
NOTE: Extended 4-bit *itype* (codes 8..15) are only necessary when <<Implicit Return Optimization,Implicit Return Optimization>> is implemented.
[[link]]
NOTE: Symbol `link` means register *x1* or *x5* as specified in *The RISC-V Instruction Set Manual, Volume I: Unprivileged ISA* document.
[[zcmt]]
NOTE: Jump instructions (CM.JT and CM.JALT) defined by ratified *Zcmt* extension are handled as direct (inferable) jumps as jump tables are assumed to be static and known to the decoder.
Table below defines how N-Trace encoder should handle different 3-bit *itype* values on trace ingress port.
[#Handling of 3-bit itype values]
.Handling of 3-bit itype values
[cols="5%,20%,75%",options="header"]
|======================================================================================================
|#|itype|Encoder Action
|0|No special type|Only update <<field_I-CNT,I-CNT>> field.
|1|Exception|Update <<field_I-CNT,I-CNT>> field. +
Emit Indirect Branch message with <<field_B-TYPE,B-TYPE>>=2 or 1. +
*IMPORTANT:* An address emitted is known at the next valid ingress port cycle.
|2|Interrupt|Update <<field_I-CNT,I-CNT>> field. +
Emit Indirect Branch message with <<field_B-TYPE,B-TYPE>>=3 or 1. +
*IMPORTANT:* An address emitted is known at the next valid ingress port cycle.
|3|Trap return|Update <<field_I-CNT,I-CNT>> field. +
Emit Indirect Branch message with <<field_B-TYPE,B-TYPE>>=0. +
*IMPORTANT:* An address emitted is known at the next valid ingress port cycle.
|4|Not-taken branch|*For <<mode_BTM,BTM>> mode:* +
Only update <<field_I-CNT,I-CNT>> field.
*For <<mode_HTM,HTM>> mode:* +
Update <<field_I-CNT,I-CNT>> field. +
Add 0 as least significant bit to <<field_HIST,HIST>> field.
|5|Taken branch|*For <<mode_BTM,BTM>> mode:* +
Update <<field_I-CNT,I-CNT>> field. +
Generate <<msg_DirectBranch,DirectBranch>> message.
*For <<mode_HTM,HTM>> mode:* +
Update <<field_I-CNT,I-CNT>> field. +
Add 1 as least significant bit to <<field_HIST,HIST>> field.
|6|Indirect jump (with or without linkage)|Update <<field_I-CNT,I-CNT>> field. +
Emit Indirect Branch message with <<field_B-TYPE,B-TYPE>>=0. +
*IMPORTANT:* An address emitted is known at the next valid ingress port cycle.
|7|Reserved|-
|======================================================================================================
When the *itype* input of ingress port is 4-bit wide, the Indirect jump (with or without linkage) *itype=6* should not be generated and one of the following values should be generated instead. Encoder must handle call stack action as described in the <<Implicit Return Optimization,Implicit Return Optimization>> chapter (if enabled).
[#Handling of 4-bit itype values]
.Handling of 4-bit itype values
[cols="5%,20%,63%,12%",options="header"]
|======================================================================================================
|#|itype|Encoder Action|Stack Action
|8|Indirect call|Update <<field_I-CNT,I-CNT>> field. Emit Indirect Branch message with <<field_B-TYPE,B-TYPE>>=0.|Push
|9|Direct call|Only update <<field_I-CNT,I-CNT>> field.|Push
|10|Indirect jump (without linkage)|Update <<field_I-CNT,I-CNT>> field. +
Emit Indirect Branch message with <<field_B-TYPE,B-TYPE>>=0. +
<<same_handling,Same handing>> as *itype=14*.|-
|11|Direct jump (without linkage)|Only update <<field_I-CNT,I-CNT>> field. +
<<same_handling,Same handing>> as *itype=15*.|-
|12|Co-routine swap|Update <<field_I-CNT,I-CNT>> field. +
If Pop does not returns the same address as PC at next valid ingress port cycle, emit Indirect Branch message with <<field_B-TYPE,B-TYPE>>=0.|Pop,Push
|13|Return|Update <<field_I-CNT,I-CNT>> field. +
If Pop does not returns the same address as PC at next valid ingress port cycle, emit Indirect Branch message with <<field_B-TYPE,B-TYPE>>=0.
|Pop
|14|Other indirect jump (with linkage)|Update <<field_I-CNT,I-CNT>> field. +
Emit Indirect Branch message with <<field_B-TYPE,B-TYPE>>=0. +
<<same_handling,Same handing>> as *itype=10*.|-
|15|Other direct jump (with linkage)|Only update <<field_I-CNT,I-CNT>> field. +
<<same_handling,Same handing>> as *itype=11*.|-
|======================================================================================================
[[same_handling]]
IMPORTANT: N-Trace messages do not differentiate instructions classified as *... jump (with linkage)* and *... jump (without linkage)*, so both N-Trace ingress ports and N-Trace encoders implementations may ignore differences between *with/without linkage* values.
If optional <<trTeInstEnAllJumps,trTeInstEnAllJumps>> bit is set, trace ingress port is required to report *itype*=5 (Taken branch) for all direct unconditional jumps, which are normally reported as *itype* = 0 or 15.
IMPORTANT: The N-Trace encoder does not require *cause* and *tval* ingress port
signals, which are valid only for exceptions and interrupts, as these
details are not reported in N-Trace messages. Instead, N-Trace solely
provides the address of the exception or interrupt handler.
NOTE: Since almost every ingress port cycle updates I-CNT, there is a possibility
of overflow. For more information, see <<I-CNT Details, I-CNT Details>> chapter regarding
I-CNT management and overflow handling.
== N-Trace Transmission Protocol
The IEEE-5001 Nexus Standard defines a trace messaging protocol using several *MDO* (Message Data Out) signals and one or two flag signals known as *MSEO* (Message Start/End Out). A Nexus message is sent or stored in a record composed of *MDO* and *MSEO*.
N-Trace specification defines 6-bit *MDO* and 2-bit *MSEO* so both fit in a single byte.
* It allows easy storage in memory as well as sending using 1-bit/ 2-bit/ 4-bit/ 8-bit/ 16-bit parallel transport (which is supported by many existing trace probes and connectors).
* Decoding software may work on bytes and 32-bit/64-bit words and expect MSEO bits at two least significant bits of each byte.
N-Trace message transmission protocol is a strict subset of IEEE-5001 Nexus Standard trace messaging protocol.
[N-Trace subset]
.N-Trace subset
[cols="25%,20%,~",options="header"]
|====
|Protocol Feature|Nexus Standard|N-Trace (strict subset of Nexus)
|Number of *MSEO* bits|1 or 2|2
|Number of *MDO* bits|At least 1|6
|Total (*MDO*+*MSEO*) bits|At least 2|8 (one byte)
|Order (transmitted or stored)|Vendor defined|*MSEO* before *MDO*, least significant bit for each field first
|Max field size|Not specified|64 bits (some 32 bits or less)
|Max standard message size|Not specified|38 bytes (maximum sum of all fields)
|====
The maximum standard message size of 38 bytes in this version of the specification is
to transmit <<msg_IndirectBranchHistSync,IndirectBranchHistSync>> message which includes TCODE/ SRC/ SYNC/ B-TYPE(5 bytes total), I-CNT(30 bits, 5 bytes), F-ADDR(63 bits, 11 bytes), HIST(32 bits, 6 bytes) TSTAMP(64 bits, 11 bytes).
While implementations may have a shorter maximum message size (e.g. due to I-CNT being smaller), they must assure that the internal FIFOs are designed to hold at least two maximum sized messages that the implementation can produce.
While decoding software may be designed to avoid dynamic memory allocation, it must nonetheless be robust enough to handle messages of any size. This is to account for scenarios when a trace memory could be corrupted, such as a trace consisting entirely of zeros, which could be interpreted as an unusually long variable-length field.
Custom messages and fields may carry different payloads and may be larger than 64 bits and 38 bytes.
=== MSEO Sequences
*MSEO[1:0]* bits (located in the least significant bits of each byte) are defined by the follow rules:
* The first byte of a message sends the least significant bits of the message and is indicated by *MSEO[1:0]=00*.
* Bytes occupied by fixed-length fields are sent using *MSEO[1:0]=00*.
* The last byte of a variable-length field, that is not last byte of a message, is indicated by *MSEO[1:0]=01*.
** A variable-length field in a message always ends on a byte boundary (zero extended as needed).
** The non-last bytes of a variable-length fields are indicated by *MSEO[1:0]=00*.
* The last byte of a message is indicated by *MSEO[1:0]=11*.
** It also implies an end of the last (fixed-length or variable-length) field of a message.
* Idle bytes (between messages or used as padding) are indicated by *MSEO[1:0]=11* and *MDO[5:0]=111111* (entire byte is *0xFF*).
* Value of *MSEO[1:0]=10* is reserved for future extensions.
The table below provides possible sequences of *MSEO[1:0]* bits (to expand above rules - *highlighted* MSEO represent the actual function):
[#MSEO Transitions]
.Transitions of MSEO Bits
[cols="40%,60%",options="header",align=center,width=80%]
|====
|MSEO Function|Previous-*Current* MSEO[1:0] Sequence
|Start of message|11-*00*
|Middle of field|00 (or 01)-*00*
|End of variable-length field|00 (or 01)-*01*
|End of message|00 (or 01)-*11*
|Idle (no message)|11-*11*
|Reserved|11-*01*
|Reserved|any-*10*
|====
[NOTE]
====
Original IEEE-5001 Nexus Standard defines the MSEO protocol as follows:
* Two `1`-s followed by one `0` indicates the start of a message.
* `0` followed by two or more `1`-s indicates the end of a message.
* `0` followed by `1` followed by `0` indicates the end of a variable-length field.
* `0`-s at all other clocks during transmission of a message.
* `1`-s at all clocks during no message transmission (idle).
Dual MSEO protocol (utilized by this N-Trace specification) is a two-pin mode of this general (single and dual) MSEO protocol definition.
====
=== Unified N-Trace Message Structure
Each N-Trace message has identical structure (100% compatible with IEEE-5001 Nexus Standard):
* Very first field is always fixed-length *TCODE* (Transport Code) which defines the meaning and format of subsequent fields.
* In case of simultaneous tracing from more than one hart, the second field is always fixed-length *SRC* (Message Source) field, which provides a unique ID of message source.
** This field allows trace decoders to separate messages from different trace sources (Trace Encoders, harts) without knowing any details of each of the messages.
** This method can be used to handle different (opaque) trace or debug or performance data using N-Trace transport/storage/export infrastructure.
* One or more (fixed-length or variable-length) payload fields. Sequence and selection of these fields depend on the value of *TCODE* field.
** In some rare cases one of preceding fields may define number of following fields.
* Very last field is (optional) variable-length *TSTAMP* (Timestamp) field.
** It may be possible to generate and analyze timestamps in a unified (simpler) way.
=== Order of bits and bytes
Order of bits and bytes:
* Trace messages/packets are considered as sequences of bytes and are always transmitted with least significant bits/bytes first.
* IEEE-5001 Nexus Standard MSEO bits are transmitted on the least significant part and bit#0 first.
* Idle state must be transmitted as all 1s MSEO and MDO bits.
* For transmission on a 16bit interface (e.g. PIB 16-bit mode), the first byte of message/packet is transmitted on the least significant part and the MSEO of the second/odd byte is transmitted on bits #8-#9 and MDO on bits #10-#15.
NOTE: Above rules allow receiving trace probes to skip idle messages.
=== PIB Idle Cycles Explained
This chapter describes N-Trace specific details about the transmission via a Pin Interface Block (PIB), as it is described in the <<RISC-V_Trace_Control_Interface,RISC-V Trace Control Interface>> Specification.
Trace messages may start on any (positive or negative) edge of trace clock.
IMPORTANT: Once a message is started all bits of that message must be transmitted on consecutive trace clock edges (both positive and negative).
Said so, an idle sequence may be sent using any number of trace clock edges (positive or negative).
To explain this let's assume the following serially transmitted (in 1-bit PIB mode) sequences of bits (MSEO[0] bit being first on the left):
* < `11` DDDDDD> - 8 bits in a last byte of a message (`11` = MSEO, DDDDDD = DATA bits)
* < `1*n` > - sequence of `n`-bits long idle bits (each must be `1`)
* < `00` TTTTTT> - 8 bits in a first byte of a message (`00` = MSEO, TTTTTTT = TCODE bits)
The following 4 example sequences are all valid:
* ... < `11` DDDDDD> < `00` TTTTTT> ... => No idle bits/cycles between consecutive messages.
* ... < `11` DDDDDD> < `1*2` > < `00` TTTTTT> ... => Two (even) idle bits.
* ... < `11` DDDDDD> < `1*3` > < `00` TTTTTT> ... => Three (odd) idle bits (second message starts at another trace clock edge).
* ... < `11` DDDDDD> < `1*8` > < `00` TTTTTT> ... => 8 idle bits (idle sequence can be considered as byte 0xFF).
Some implementations may always send idle sequences using even (or even multiple of 8) number of trace clocks - in such a case all messages will always start on a positive or negative trace clock. But conformant trace probes must handle any number of idle clocks.
[NOTE]
====
The trace probe needs to be able to synchronize with the trace stream and to detect trace message boundaries. This procedure is sometimes referred to as "message alignment synchronization" or "alignment-sync".
For 8-bit or 16-bit trace idle cycles are not required (to detect an alignment) as MSEO bits are in well-defined positions and trace probes will know where is a start of a message.
For 1-bit, 2-bit and 4-bit trace modes PIB must generate at least one idle byte to allow trace probes to detect which bit is the first MSEO bit of a message.
How it is done is not defined in this specification. Here are two possible implementations:
* Generate at least one idle byte periodically in a trace stream anywhere between messages (PIB is aware about message boundaries as end of message has MSEO=11 bits).
* Always add an extra idle byte before sending synchronizing messages. It will guarantee that boundaries of every synchronizing message are always detectable and decoding may start from it.
====
=== N-Trace Message Example
Table below shows one N-Trace message with several fields. It is an output from N-Trace dump tool (part of N-Trace reference C code) with an added *Explanation* column.
[#MDO_MSEO Examples]
.MDO and MSEO Encoding Example
[cols="6%,10%,10%,18%,~",options="header"]
|====
|Byte|MDO [5:0]|MSEO [1:0]|Decoded (by reference tool)|Explanation
|0xFF| 111111|11 | Idle | Most likely idle but can also be the last byte of the previous message.
|0x70| 011100|00 | TCODE[6] = 28 - IndirectBranchHist| First byte, all 6 MDO bits have TCODE.
5+|Here we could have an SRC field (it would shift the start of B-TYPE).
|0xD0| 110100|00 | B-TYPE[2] = 0x0| This is a 2-bit (fixed-length) field. As B-TYPE is a fixed-length field, four most significant bits are part of the next field (I-CNT).
|0x1D| 000111|01 | I-CNT[10] = 0x7D| This is a second byte of the 10-bit (value 0x7D) variable-length I-CNT field. Four least significant bits (0b1101=0xD) are defined in previous MDO. Three most significant bits are all 0-s as variable-length field uses all 6 MDO bits.
|0x1D| 000111|01 | U-ADDR[6] = 0x7| This is a single byte variable-length U-ADDR field (with three most significant 0-s).
|0xF8| 111110|00 || Normal transfer of new field (6 least significant bits).
|0xFF| 111111|11 | HIST[12] = 0xFFE| Last byte of message. It implies the end of the 12-bit HIST field. In this field we do not have any extra most significant 0-s.
5+|Here optional TSTAMP field could be sent +
(Previous MSEO should became 01 encoding end of HIST field, but not end of the message).
|0xFF| 111111|11 | Idle|This is idle as this is the second byte with MSEO=11 (NOTE: Last byte of message is also 0xFF).
|====
== N-Trace Specific Trace Controls
This chapter describes how fields and bits from Trace Encoder control registers (named using *trTe...* pattern) are influencing N-Trace encoder and N-Trace protocol messages. N-Trace specific clarifications, in addition to description in <<RISC-V_Trace_Control_Interface,RISC-V Trace Control Interface>> specification are provided.
NOTE: The table below does not provide names of Trace Encoder control registers as names of bits/fields used in Trace Control Interface are unique.
[#Details_Control_Parameters]
.Trace Encoder Parameters and Controls
[cols="25%,15%,~",options="header"]
|======================================================================================================
|Trace Control Field|Applicability|Description
|trTeActive |*Required*|See <<RISC-V_Trace_Control_Interface,RISC-V Trace Control Interface>> Specification.
|trTeEnable |*Required*|See <<RISC-V_Trace_Control_Interface,RISC-V Trace Control Interface>> Specification.
|trTeInstTracing |*Required*|See <<RISC-V_Trace_Control_Interface,RISC-V Trace Control Interface>> Specification.
|trTeEmpty |*Required*|See <<RISC-V_Trace_Control_Interface,RISC-V Trace Control Interface>> Specification.
[[trTeInstMode]]
|trTeInstMode |*Required*|
*3:* Generate instruction trace using <<mode_BTM,BTM>> (Branch Trace Messaging) mode. +
*6:* Generate instruction trace using <<mode_HTM,HTM>> (History Trace Messaging) mode. +
*0, 7:* See <<RISC-V_Trace_Control_Interface,RISC-V Trace Control Interface>> Specification. +
*1-2, 4-5:* Reserved for future N-Trace use. +
At least a value of *3* or *6* must be settable.
[[trTeContext]]
|trTeContext|Optional|Controls generation of <<msg2_Ownership,Ownership>> messages.
|trTeInstTrigEnable |Optional|See <<RISC-V_Trace_Control_Interface,RISC-V Trace Control Interface>> Specification.
|trTeInstStallOrOverflow |*Required*|See <<RISC-V_Trace_Control_Interface,RISC-V Trace Control Interface>> Specification.
|trTeInstStallEna |Optional|See <<RISC-V_Trace_Control_Interface,RISC-V Trace Control Interface>> Specification.
[[trTeInhibitSrc]]
|trTeInhibitSrc|Optional|Controls generation of <<field_SRC,SRC>> field.
[[trTeInstSyncMode]]
|trTeInstSyncMode |*Required*|Controls generation of <<Synchronizing Messages,Synchronizing Messages>> with <<field_SYNC,SYNC>> field=2.
[[trTeInstSyncMax]]
|trTeInstSyncMax |*Required*|Controls generation of <<Synchronizing Messages,Synchronizing Messages>> with <<field_SYNC,SYNC>> field=2.
|trTeFormat |*Required*|Must be set to *1* (which denotes N-Trace format).
|trTeVerMajor |*Required*|See <<RISC-V_Trace_Control_Interface,RISC-V Trace Control Interface>> Specification.
|trTeVerMinor |*Required*|See <<RISC-V_Trace_Control_Interface,RISC-V Trace Control Interface>> Specification.
|trTeCompType |*Required*|See <<RISC-V_Trace_Control_Interface,RISC-V Trace Control Interface>> Specification.
[[trTeProtocolMajor]]
|trTeProtocolMajor|*Required*|*Must be 1* to encode this version (1.0) of N-Trace protocol. Value different than 1 is considered a non-compatible version and must be rejected by the trace tool if it is only compliant with version 1.0 of the N-trace protocol.
[[trTeProtocolMinor]]
|trTeProtocolMinor|*Required*|*Must be 0* to encode this version (1.0) of N-Trace protocol. When trTeProtocolMajor is 1, values other than 0 are considered down compatible extension and should be accepted by the trace tool. Any future non-compatible feature should be specifically enabled (by new control bits), so older tools (which never set these new bits) should work with it.
|trTeInstNoAddrDiff|Not applicable|Must be hard coded as *0*.
|trTeInstNoTrapAddr|Not applicable|Must be hard coded as *0*.
[[trTeInstEnSequentialJump]]
|trTeInstEnSequentialJump|Optional|See <<Sequential Jump Optimization,Sequential Jump Optimization>> chapter.
[[trTeInstEnImplicitReturn]]
|trTeInstEnImplicitReturn|Optional|See <<Implicit Return Optimization,Implicit Return Optimization>> chapter.
|trTeInstEnBranchPrediction|Not applicable|Must be hard coded as *0*.
|trTeInstEnJumpTargetCache|Not applicable|Must be hard coded as *0*.
[[trTeInstImplicitReturnMode]]
|trTeInstImplicitReturnMode|Optional|See <<Implicit Return Optimization,Implicit Return Optimization>> chapter.
[[trTeInstEnRepeatedHistory]]
|trTeInstEnRepeatedHistory|Optional|See <<Repeated History Optimization,Repeated History Optimization>> chapter.
[[trTeInstEnAllJumps]]
|trTeInstEnAllJumps|Optional|See <<RISC-V_Trace_Control_Interface,RISC-V Trace Control Interface>> Specification.
[[trTeInstExtendAddrMSB]]
|trTeInstExtendAddrMSB|Optional|See <<Virtual Addresses Optimization, Virtual Addresses Optimization>> chapter.
[[trTeSrcID]]
|trTeSrcID|Optional|Controls generation of <<field_SRC,SRC>> field.
[[trTeSrcBits]]
|trTeSrcBits|Optional|Controls generation of <<field_SRC,SRC>> field.
|trTeInstFilters|Optional|See <<RISC-V_Trace_Control_Interface,RISC-V Trace Control Interface>> Specification.
|trTeDataImplemented|Not applicable|*Must be 0* as IEEE-5001 Nexus Standard data trace messages are not part of version 1.0 of N-Trace specification.
|*Other* trTeData...|Not applicable|*Must be 0* as IEEE-5001 Nexus Standard defines data trace messages, future versions of N-Trace may allow these (as an optional extension).
|*All* trTeTrig...|Optional|See <<RISC-V_Trace_Control_Interface,RISC-V Trace Control Interface>> Specification.
|*All* trTeFilter...|Optional|See <<RISC-V_Trace_Control_Interface,RISC-V Trace Control Interface>> Specification.
|*All* trTeComp...|Optional|See <<RISC-V_Trace_Control_Interface,RISC-V Trace Control Interface>> Specification.
[[trTsEnable]]
|trTsEnable|Optional| Part of potentially shared Timestamp Unit controls generation of <<field_TSTAMP,TSTAMP>> field. See <<RISC-V_Trace_Control_Interface,RISC-V Trace Control Interface>> Specification for details of the Timestamp Unit.
|======================================================================================================
== Main N-Trace Trace Modes
RISC-V N-Trace defines two instruction trace modes:
[[mode_BTM]]
* *Branch Trace Messaging (BTM)* - each taken direct conditional branch generates a minimum two-byte message. However, repeated branches can be aggregated and reported as a single message with a count, rather than numerous identical messages.
[[mode_HTM]]
* *History Trace Messaging (HTM)* - every direct conditional branch, whether taken or not-taken, contributes a single bit to the history buffer, significantly enhancing the trace efficiency.
The encoder is required to implement at least one of these modes. Both may be supported, but is not required.
[NOTE]
====
Above modes correspond to the following IEEE-5001 Nexus Standard instruction trace modes:
* *Branch Trace Messaging using Traditional Messages*
* *Branch Trace Messaging using Branch History Messages*
====
IMPORTANT: The IEEE-5001 Nexus Standard defines different conformance levels. These levels are not directly applicable to N-Trace as Nexus levels always include debug levels. Different N-Trace options are provided in <<N-Trace Specific Trace Controls,N-Trace Specific Trace Controls>> chapter.
== N-Trace Messages (Overview)
IMPORTANT: The terminology `Indirect Branch` as used by the IEEE-5001 Nexus Standard may lead to confusion, given that the RISC-V ISA exclusively permits direct conditional branches, which are always relative. Furthermore, the RISC-V ISA makes a distinction between 'jump' (unconditional flow change) and 'branch' (conditional flow change), a differentiation not observed in Nexus terminology, where any flow change, including exceptions and interrupts, is uniformly referred to as a 'branch'. This specification employs the terms 'branch' and 'jump' as defined by RISC-V ISA.
// [#Fields in Messages]
=== Fields in Messages
The table presented below enumerates all message types that can be generated, with each row comprehensively defining the fields associated with a particular message type. Fields that are present in different messages are consistently ordered.
Message field attributes are described using the following terminology:
* *[n]*: A fixed-length field that is *n* bits wide.
* *[Var]*: A variable-length, non-empty (at least 1-bit wide), field.
* *[Cfg]*: A configurable field, where the existence and size depend on the encoder configuration options.
.Fields in Messages
[cols="22%,8%,5%,6%,8%,14%,7%,8%,8%,~",options="header",]
|===========================================================================================
| Message ID/Field [size]|<<field_TCODE,TCODE>> [6]|<<field_SRC,SRC>> [Cfg]|<<field_SYNC,SYNC>> [4]|<<field_B-TYPE,B-TYPE>> [2]|Other fields|<<field_I-CNT,I-CNT>> [Var]|<<Address Compression,x-ADDR>> [Var]|<<field_HIST,HIST>> [Var]|<<field_TSTAMP,TSTAMP>> [Var,Cfg]
|[[msg_Ownership]]<<msg2_Ownership,Ownership>> |2 |Cfg| | |<<field_PROCESS,PROCESS>> *[Var]* | | ||Cfg
|[[msg_DirectBranch]]<<msg2_DirectBranch,DirectBranch>> |3 |Cfg| | | |Yes | ||Cfg
|[[msg_IndirectBranch]]<<msg2_IndirectBranch,IndirectBranch>> |4 |Cfg| |Yes | |Yes |<<field_U-ADDR,U-ADDR>>||Cfg
|[[msg_Error]]<<msg2_Error,Error>> |8 |Cfg| | |<<field_ETYPE,ETYPE>> *[4]* + <<field_ECODE,ECODE>> *[Var]* | | ||Cfg
|[[msg_ProgTraceSync]]<<msg2_ProgTraceSync,ProgTraceSync>> |9 |Cfg|Yes | | |Yes |<<field_F-ADDR,F-ADDR>>||Cfg
|[[msg_DirectBranchSync]]<<msg2_DirectBranchSync,DirectBranchSync>> |11 |Cfg|Yes | | |Yes |<<field_F-ADDR,F-ADDR>>||Cfg
|[[msg_IndirectBranchSync]]<<msg2_IndirectBranchSync,IndirectBranchSync>> |12 |Cfg|Yes |Yes | |Yes |<<field_F-ADDR,F-ADDR>>||Cfg
|[[msg_ResourceFull]]<<msg2_ResourceFull,ResourceFull>> |27 |Cfg| | |<<field_RCODE,RCODE>> *[4]* + <<field_RDATA,RDATA>> *[Var]*| | ||Cfg
|[[msg_IndirectBranchHist]]<<msg2_IndirectBranchHist,IndirectBranchHist>> |28 |Cfg| |Yes | |Yes |<<field_U-ADDR,U-ADDR>>|Yes|Cfg
|[[msg_IndirectBranchHistSync]]<<msg2_IndirectBranchHistSync,IndirectBranchHistSync>>|29 |Cfg|Yes |Yes | |Yes |<<field_F-ADDR,F-ADDR>>|Yes|Cfg
|[[msg_RepeatBranch]]<<msg2_RepeatBranch,RepeatBranch>> |30 |Cfg| | |<<field_B-CNT,B-CNT>> *[Var]* | | ||Cfg
|[[msg_ProgTraceCorrelation]]<<msg2_ProgTraceCorrelation,ProgTraceCorrelation>> |33 |Cfg| | |<<field_EVCODE,EVCODE>> *[4]* + <<field_CDF,CDF>> *[2]* |Yes | |*Cfg*|Cfg
|<<msg_other,Vendor Defined>>|56..62|Cfg 7+| Designated for use by Vendor Defined messages
|<<msg_other,Reserved>>|other|Cfg 7+| Reserved for future extensions of N-Trace specification
|===========================================================================================
IMPORTANT: Any message may include the optional <<field_TSTAMP,TSTAMP>> *[Var,Cfg]* field as the very last field of a message. It must be enabled by <<trTsEnable,trTsEnable>> control bit. Timestamp field always starts at byte-boundary (as it is always preceded by variable-length field). See <<Timestamp Reporting,Timestamp Reporting>> chapter for more details.
[[msg_other]]
NOTE: Messages marked as *Reserved* or *Vendor Defined* should be ignored by decoders interested in program flow only.
However, decoders should provide an option to display/dump them and/or generate a warning as such a message may be seen when trace capture is corrupted.
*Vendor Defined* messages can be used for prototyping, debugging, validation and maintenance purposes.
Reference code header https://github.com/riscv-non-isa/tg-nexus-trace/blob/main/refcode/c/NexRvMsg.h[NexRvMsg.h] defines all N-Trace messages in machine-readable format. Here is small snipped from this file as an example:
[source,c]
----
// Naming:
// NEXM=Nexus Message, BEG/END=Beginning/End of definition.
// SRC=Message source (system-field). Name of an option given.
// FLD/VAR=Fixed/variable size field.
// ADR=Special case of variable field (without least significant bit).
// CFG=Configurable, Name of an option given.
NEXM_BEG(IndirectBranchSync, 12)
NEXM_SRC(SrcBits) // Configurable
NEXM_FLD(SYNC, 4)
NEXM_FLD(BTYPE, 2)
NEXM_VAR(ICNT)
NEXM_ADR(FADDR)
NEXM_VAR(TSTAMP)
NEXM_END()
NEXM_BEG(ResourceFull, 27)
NEXM_SRC(SrcBits) // Configurable
NEXM_FLD(RCODE, 4)
NEXM_VAR(RDATA)
NEXM_VAR_CFG(HREPEAT, EnaRepeatedHistory) // Configurable
NEXM_VAR(TSTAMP)
NEXM_END()
NEXM_BEG(IndirectBranchHist, 28)
NEXM_SRC(SrcBits) // Configurable
NEXM_FLD(BTYPE, 2)
NEXM_VAR(ICNT)
NEXM_ADR(UADDR)
NEXM_VAR(HIST)
NEXM_VAR(TSTAMP)
NEXM_END()
----
NOTE: Reference code is using plain C-style identifiers, so the field name as *B-TYPE* will become *BTYPE*.
=== Common Fields
The table below provides details for fields which are used in more than one message type. Fields which are present in only one message are described with each message.
.Details of Common Fields
[cols="9%,5%,15%,~",options="header"]
|======================================================================================================
| Name | Bits | Description | Values/Notes
4+|*Fields used in many messages*
[[field_TCODE]]
| TCODE | 6 | Transfer Code | Message header that identifies the number and/or size of fields to be transferred, and how to interpret each of the fields following it.
[[field_SRC]]
| SRC | *Cfg* | Source of Message Transmission | Width of SRC field is defined by <<trTeSrcBits,trTeSrcBits>> control field and it may be enabled/disabled by <<trTeInhibitSrc,trTeInhibitSrc>> control bit. This optional field is used to identify the source of the message transmission. In configurations that comprise only a single hart, this field need not be transmitted. For devices that comprise multiple harts, this field must be transmitted (if enabled) as part of the message to identify the source of the message transmission. The transmitted SRC field size should be the same for all enabled trace encoders sharing a trace stream.
[[field_SYNC]]
| SYNC | 4 |Reason for Synchronization| Encodings and details are provided in the <<Synchronizing Messages,Synchronizing Messages>> chapter. +
*NOTE:* The SYNC field is always sent together with the <<field_F-ADDR,F-ADDR>> field, so decoding may start from a message containing the SYNC field.
[[field_B-TYPE]]
| B-TYPE | 2 | Branch Type | Reason for indirect flow change: +
*0:* Indirect control flow change (jump, call or return) or in a <<Synchronizing Messages,synchronizing message>> not related to code execution. +
*1:* Exception or interrupt (if the encoder is not capable of reporting 2 and 3). +
*2:* *Extension:* Exception +
*3:* *Extension:* Interrupt +
*NOTE:* Either 1-only or both 2 and 3 should be implemented and consistently reported. Extended values 2 and 3 allow trace tools to distinguish exceptions and interrupts easily.
[[field_I-CNT]]
| I-CNT | *Var* | Instruction Count | As RISC-V allows variable-length instructions, this is the number of 16-bit (INST_LEN/2) instruction units executed/retired since the I-CNT counter was transmitted or reset. See <<I-CNT Details,I-CNT Details>> chapter for more details.
[[field_F-ADDR]]
| F-ADDR | *Var* | Full Target Address | Full PC without the least significant bit.
The least significant bit is not reported as it is always 0.
See <<Address Compression,Address Compression>> chapter for more details. +
*NOTE:* The F-ADDR field is always sent together with the <<field_SYNC,SYNC>> field.
[[field_U-ADDR]]
| U-ADDR | *Var* | Unique part of Target Address | Unique part of PC address (XOR with recently reported address).
See <<Address Compression,Address Compression>> chapter for more details. +
The U-ADDR field is always sent together with the <<field_B-TYPE,B-TYPE>> field.
[[field_HIST]]
| HIST | *Var* | Direct Branch History map | Most significant bit (always 1) serves as a 'stop-bit', the least significant bit denotes the last direct conditional branch. See <<HIST Field Generation,HIST Field Generation>> chapter for more details.
[[field_TSTAMP]]
| TSTAMP | *Var* | Timestamp (optional) | It must be enabled by <<trTsEnable,trTsEnable>> control bit. See <<Timestamp Reporting,Timestamp Reporting>> chapter for more details.
|======================================================================================================
IEEE-5001 Nexus Standard does not define limits for variable-length fields, but N-Trace provides some limits. It will help to write efficient decoding software but is not limiting hardware in any way.
[#Max_Field_Sizes]
.Maximum Field Sizes
[cols="10%,25%,5%,~",options="header"]
|======================================================================================================
|Field|Symbol|Bits|Description
[[NTRACE_MAX_SRC]]
|SRC|NTRACE_MAX_SRC|12|Determined by size of Trace Control register field. Enough for 4096 (4K) trace sources.
[[NTRACE_MAX_ICNT]]
|I-CNT|NTRACE_MAX_ICNT|22|Usually a smaller value will be sufficient. An overflow bit may be used for efficient I-CNT full detection.
[[NTRACE_MAX_ADDR]]
|F-ADDR, U-ADDR|NTRACE_MAX_ADDR|63|Only 63 bits suffice as the least significant bit of an instruction address is always 0 and does not need to be reported.
[[NTRACE_MAX_HIST]]
|HIST|NTRACE_MAX_HIST|32|It includes stop-bit. This size is optimal for not wasting any bits in very often used <<msg_ResourceFull,ResourceFull>> messages.
[[NTRACE_MAX_TSTAMP]]
|TSTAMP|NTRACE_MAX_TSTAMP|64|It is certainly big enough. It corresponds to architecture defined timer and cycle count registers.
[[NTRACE_MAX_HREPEAT]]
|HREPEAT|NTRACE_MAX_HREPEAT|18|Assure some trace is periodically generated for very long loops.
[[NTRACE_MAX_BCNT]]
|B-CNT|NTRACE_MAX_BCNT|18|Assure some trace is periodically generated for very long loops.
|======================================================================================================
== N-Trace Messages (Details)
This chapter provides a detailed description of all N-Trace messages. Overview of all fields in all messages is provided in the <<Fields in Messages,Fields in Messages>> table.
Common fields are described in the <<Common Fields,Common Fields>> chapter, but fields specific to message *TCODE* values are explained here.
Size of field in *Bits* column may be one or more of the following values:
* *n (1..6)* - This is an *n*-bits wide, fixed-length field.
* *Var* - This is a variable-length, at least 1-bit wide field.
* *Cfg* - Size of this field depends on configuration setting (*Cfg* fields are always optional).
Each message has its own table showing all fields in that message.
IMPORTANT: The IEEE-5001 Nexus Standard presents tables with *TCODE* (which is sent first) in the last row. In contrast, this specification shows <<Fields in Messages,Fields in Messages>> in the order they are sent (the first field sent is described first), aligning with the order of storage, processing, and text dumps.
[[msg2_Ownership]]
=== Ownership Message
This message furnishes the requisite context (privileged mode and Context ID, as assigned by the operating system or hypervisor), enabling the decoder to correlate program flow with distinct code
segments associated with various programs. Activation of this feature requires explicit enabling of the <<trTeContext,trTeContext>> control bit.
Reporting of this information occurs under one of the following three conditions:
* Upon the retirement of an instruction that writes to the *scontext/hcontext* CSR (as reported via `priv` and `context` field on an ingress port).
* In the event of a trap or trap return that results in a change in privilege mode (including *ECALL* and *EBREAK* instructions).
* Following any trace <<Synchronizing Messages,synchronizing message>>.
IMPORTANT: Should *hcontext* be implemented, the protocol requires two consecutive messages: the first presenting *hcontext* information
and the second *scontext* information. This sequence is important for enabling the decoder to identify the code associated with a specific process.
NOTE: If tracing multiple OS-es, main decoder may route messages to an OS-specific decoder after seeing *hcontext* and the *scontext* (which follows) will be decoded by decoder determined by *hcontext*.
[#Fields_Ownership]
.Ownership Message Fields
[cols="8%,10%,~",options="header"]
|======================================================================================================
|Bits|Name|Description
|6 |TCODE |Value=2(0x2). Standard Transfer Code (<<field_TCODE,TCODE>>) field.
|Cfg |SRC |Standard Message Source (<<field_SRC,SRC>>) field.
[[field_PROCESS]]
|Var |PROCESS |This is a variable-length field, which encodes *V* and *PRV* privilege mode bits as well as *scontext/hcontext* CSR values. Details are provided below.
|Var,Cfg |TSTAMP |Standard Timestamp (<<field_TSTAMP,TSTAMP>>) field.
|======================================================================================================
*Explanations and Notes*
Field PROCESS is encoded as 4 sub-fields (FORMAT, PRV, V, CONTEXT). Bit layout is defined in RTL-like syntax as follows:
PROCESS[x+5:0] = {CONTEXT[x:0], V[0], PRV[1:0], FORMAT[1:0]}
.Encoding of PROCESS field (in LSB to MSB order)
[cols="35%,20%,12%,8%,25%",options="header",align=center,width=80%]
|======================================================================================================
|Reason|FORMAT[1:0]|PRV[1:0]|V[0]|CONTEXT[x:0]
| V and/or PRV change |00 |Yes|Yes|--
| Reserved |01|--|--|--
| Sync or *scontext* change |10|Yes|Yes|*scontext* value
| Sync or *hcontext* change |11|Yes|Yes|*hcontext* value
|======================================================================================================
Encodings of *V/PRV* follow ISA privilege mode encodings and are encoded as follows:
U-mode: V=0, PRV[1:0]=00
S-mode: V=0, PRV[1:0]=01
M-mode: V=0, PRV[1:0]=11
VU-mode: V=1, PRV[1:0]=00
VS-mode: V=1, PRV[1:0]=01
All unused encodings are reserved.
Examples:
PROCESS=0x3B2 = 0b11101_1_00_10 => scontext=0x1D,V=1,PRV[1:0]=00 (VU-mode)
PROCESS=0xC 0b0_11_00 => V=0,PRV[1:0]=11 (M-mode)
<<<
[[msg2_DirectBranch]]
=== DirectBranch Message
It is applicable to <<mode_BTM,BTM>> mode only.
This message is generated when the taken direct conditional branch has retired.
[#Fields_DirectBranch]
.Direct Branch Message Fields
[cols="8%,10%,~",options="header"]
|======================================================================================================
|Bits|Name|Description
|6 |TCODE |Value=3(0x3). Standard Transfer Code (<<field_TCODE,TCODE>>) field.
|Cfg |SRC |Standard Message Source (<<field_SRC,SRC>>) field.
|Var |I-CNT |Standard Instruction Count (<<field_I-CNT,I-CNT>>) field.
|Var,Cfg |TSTAMP |Standard Timestamp (<<field_TSTAMP,TSTAMP>>) field.
|======================================================================================================
*Explanations and Notes*
Last instruction in the code block (or blocks) with all inferable instructions (described by I-CNT) is a taken, direct conditional branch instruction.
Next PC is determined by decoding the conditional branch instruction opcode to determine the encoded signed offset and adding it to the address of the conditional branch instruction.
NOTE: Not-taken direct conditional branches and direct unconditional jumps increment I-CNT but do not generate any trace.
Direct unconditional jumps change the PC to the destination address of such a jump. The I-CNT enables determination of the PC of the last instruction in the code block(s).
<<<
[[msg2_IndirectBranch]]
=== IndirectBranch Message
It is applicable to <<mode_BTM,BTM>> mode only.
This message is generated under two conditions:
* An instruction that causes an indirect unconditional control flow change has retired.
* A trap due to an interrupt or exception is delivered.
[#Fields_IndirectBranch]
.Indirect Branch Message Fields
[cols="8%,10%,~",options="header"]
|======================================================================================================
|Bits|Name|Description
|6 |TCODE |Value=4(0x4). Standard Transfer Code (<<field_TCODE,TCODE>>) field.
|Cfg |SRC |Standard Message Source (<<field_SRC,SRC>>) field.
|2 |B-TYPE |Standard Branch Type (<<field_B-TYPE,B-TYPE>>) field.
|Var |I-CNT |Standard Instruction Count (<<field_I-CNT,I-CNT>>) field.
|Var |U-ADDR |Standard Unique Address (<<field_U-ADDR,U-ADDR>>) field.
|Var,Cfg |TSTAMP |Standard Timestamp (<<field_TSTAMP,TSTAMP>>) field.
|======================================================================================================
*Explanations and Notes*
The last instruction within the code block(s), as specified by the I-CNT field, either represents an indirect unconditional control flow
change (i.e., jump, call, or return) or this packet is generated in response to an exception or interrupt reported on the ingress port.
The next PC is determined by applying the <<Address Compression,Address Compression>> rules to the U-ADDR field present in this message.
NOTE: Not-taken conditional branches and direct unconditional jumps do not generate any trace. However, they do increase the I-CNT.
Additionally, direct unconditional jumps modify the PC to the destination address specified in the instruction.
Consequently, the PC of the last instruction in a code block(s) can be determined.
<<<
[[msg2_Error]]
=== Error Message
An error message must be generated in the event of an internal messages FIFO overflow, resulting in the loss of a trace message.
[#Fields_Error]
.Error Message Fields
[cols="8%,10%,~",options="header"]
|======================================================================================================
|Bits|Name|Description
|6 |TCODE |Value=8(0x8). Standard Transfer Code (<<field_TCODE,TCODE>>) field.
|Cfg |SRC |Standard Message Source (<<field_SRC,SRC>>) field.
[[field_ETYPE]]
|4 |ETYPE |Standard Error Type (a subset of IEEE-5001 Nexus Standard encoding): +
*0:* A FIFO overrun has resulted in the loss of one or more messages. +
*1..7:* Reserved. +
*8..15:* Designated for Vendor Defined Error(s).
[[field_ECODE]]
|Var |ECODE |Standard Error Code (a subset of IEEE-5001 Nexus Standard encoding). A bit mask that when not equal to 0 may have one or more bits set as follows to indicate errors: +
*0:* Exact reason unknown/not provided. +
*xxxxxxx1:* Reserved. +
*xxxxxx1x:* Reserved (for data trace in future). +
*xxxxx1xx:* Program Trace Message(s) lost. +
*xxxx1xxx:* Ownership Trace Message(s) lost. +
*xxx1xxxx:* Reserved. +
*xx1xxxxx:* Reserved (for data trace in future). +
*x1xxxxxx:* Reserved. +
*1xxxxxxx:* Vendor Defined Message(s) lost. +
*IMPORTANT:* The field must be generated even if the reported value is always 0, to guarantee that the TSTAMP field aligns at the byte boundary.
|Var,Cfg |TSTAMP |Standard Timestamp (<<field_TSTAMP,TSTAMP>>) field.
|======================================================================================================
*Explanations and Notes*
Error Message must be sent immediately prior to a <<Synchronizing Messages,synchronizing message>> as soon as space is available in the Trace Encoder output queue. It is recommended that the timestamp reported in the message corresponds to the moment when the first trace message was dropped; however, this is not a requirement.
[NOTE]
====
This message *is required* as otherwise decoder (even though restart after FIFO overflow is signaled) would not be aware that trace was lost in case of the following sequence of events:
* Trace is turned off by trigger (or from any other reason).
* Message reporting 'trace off' event is lost (due to lack of space for it).
** Here Error Message should be generated (as soon as there is a room)
* Trace is never restarted.
* Trace is stopped (this will not generate any trace as trace is turned off).
In the above case, Error Message will be the last message in trace stream.
====
<<<
[[msg2_ProgTraceSync]]
=== ProgTraceSync Message
[#Fields_ProgTraceSync]
.Program Trace Synchronization Message Fields
[cols="8%,10%,~",options="header"]
|======================================================================================================
|Bits|Name|Description
|6 |TCODE |Value=9(0x9). Standard Transfer Code (<<field_TCODE,TCODE>>) field.
|Cfg |SRC |Standard Message Source (<<field_SRC,SRC>>) field.
|4 |SYNC |Standard Synchronization Reason (<<field_SYNC,SYNC>>) field.
|Var |I-CNT |Standard Instruction Count (<<field_I-CNT,I-CNT>>) field.
|Var |F-ADDR |Standard Full Address (<<field_F-ADDR,F-ADDR>>) field.
|Var,Cfg |TSTAMP |Standard Timestamp (<<field_TSTAMP,TSTAMP>>) field.
|======================================================================================================
*Explanations and Notes*
This message is produced at the start or restart of trace. In such instances, the I-CNT field is required to be set to 0. However, under certain conditions
associated with the SYNC parameter (e.g., `External Trace Trigger`), the I-CNT field may not be zero.
Instead, it serves to pinpoint the precise Program Counter (PC) location at which the specified trigger or event occurred.
Additionally, the F-ADDR field provides the complete PC address at the moment the trigger was activated.
This message may be also generated on linear code for certain synchronization events as described in <<Synchronizing Messages,Synchronizing Message>> chapter.
<<<
[[msg2_DirectBranchSync]]
=== DirectBranchSync Message
[#Fields_DirectBranchSync]
.Direct Branch with Sync Message Fields
[cols="8%,10%,~",options="header"]
|======================================================================================================
|Bits|Name|Description
|6 |TCODE |Value=11(0xB). Standard Transfer Code (<<field_TCODE,TCODE>>) field.
|Cfg |SRC |Standard Message Source (<<field_SRC,SRC>>) field.
|4 |SYNC |Standard Synchronization Reason (<<field_SYNC,SYNC>>) field.
|Var |I-CNT |Standard Instruction Count (<<field_I-CNT,I-CNT>>) field.
|Var |F-ADDR |Standard Full Address (<<field_F-ADDR,F-ADDR>>) field.
|Var,Cfg |TSTAMP |Standard Timestamp (<<field_TSTAMP,TSTAMP>>) field.
|======================================================================================================
*Explanations and Notes*
This message is produced under the same conditions as the <<msg2_DirectBranch,DirectBranch>> message.
However, it further includes details on the reason for synchronization via the SYNC field, as well as the full Program Counter (PC) address through the F-ADDR field.
This message may be also generated on linear code for certain synchronization events as described in <<Synchronizing Messages,Synchronizing Message>> chapter.
<<<
[[msg2_IndirectBranchSync]]
=== IndirectBranchSync Message
[#Fields_IndirectBranchSync]
.Indirect Branch with Sync Message Fields
[cols="8%,10%,~",options="header"]
|======================================================================================================
|Bits|Name|Description
|6 |TCODE |Value=12(0xC). Standard Transfer Code (<<field_TCODE,TCODE>>) field.
|Cfg |SRC |Standard Message Source (<<field_SRC,SRC>>) field.
|4 |SYNC |Standard Synchronization Reason (<<field_SYNC,SYNC>>) field.
|2 |B-TYPE |Standard Branch Type (<<field_B-TYPE,B-TYPE>>) field.
|Var |I-CNT |Standard Instruction Count (<<field_I-CNT,I-CNT>>) field.
|Var |F-ADDR |Standard Full Address (<<field_F-ADDR,F-ADDR>>) field.
|Var,Cfg |TSTAMP |Standard Timestamp (<<field_TSTAMP,TSTAMP>>) field.
|======================================================================================================
*Explanations and Notes*
This message is generated in the same conditions as <<msg2_IndirectBranch,IndirectBranch>> message, but additionally provides a reason for synchronization (SYNC field) and full PC (F-ADDR field).
This message may be also generated (with <<field_B-TYPE,B-TYPE>>=0 field) on linear code for certain synchronization events as described in <<Synchronizing Messages,Synchronizing Message>> chapter.
<<<