Added Synchronizing Messages Examples (images)

docs/RISC-V-N-Trace.adoc

@@ -51,7 +51,10 @@ Change is extremely unlikely.
 PDF generated on: {localdatetime}
 
 === Version 1.0.0_rc15
-* Added I-CNT Full example
+* Added examples of synchronizing messages (images).
+* Moved Timestamp chapter above Corner Cases.
+* Clarified I-CNT FUll in BTM mode.
+* Added I-CNT Full example.
 
 === Version 1.0.0_rc14
 * 2024-02-29
@@ -1383,6 +1386,33 @@ Decoders should report synchronization SYNC field values from messages (includin
 * All synchronizing messages emit an absolute <<field_TSTAMP,TSTAMP>> field (if enabled), so decoder may report full/absolute timestamp.
 ====
 
+=== Timestamp Reporting
+
+Timestamp recording must be enabled by <<trTsEnable,trTsEnable>> trace control bit.
+
+If timestamp is enabled all <<Synchronizing Messages,Synchronizing Messages>> include an absolute timestamp value with upper zeroes suppressed. Other message types with timestamp emit the timestamp as relative offset from last reported (absolute or relative) timestamp.
+
+NOTE: The TSTAMP field is a variable-length field and most significant bits=0 will not be transmitted. It will provide good compression for relative and absolute timestamps.
+
+To reconstruct the full timestamp, software begins at a <<Synchronizing Messages,synchronizing message>> and stores the TSTAMP value found there, zero-extended to the full timestamp width. Shortly after starting a trace session, even a 64-bit timestamp will typically require far less than 64 bits to transmit. Software extracts the compressed TSTAMP from each message thereafter and adds it with the previous decompressed timestamp to obtain the full timestamp value associated with this message.
+
+The following rules must be observed:
+
+* If timestamps are enabled, ALL <<Synchronizing Messages,Synchronizing Messages>> must include absolute TSTAMP value.
+* It is not required that ALL non-synchronizing messages are always reporting timestamp.
+** It may be done to save trace bandwidth or in case of sending back to back messages.
+* Absolute timestamp cannot exceed 64 bits (even with 1ps resolution, 64-bit counters will overflow in about 584 years).
+** Implementation may choose a smaller counter - trace tools may assume timestamp will not overflow in a single session, however it would not be very hard to add support for it.
+* It is suggested that in multi-hart systems all Trace Encoders use a shared timestamp (for better trace correlation), but it is not necessary.
+* Timestamp at all cases, when an address is provided should be at a time when an event leading to that particular address being sent happened.
+
+[NOTE]
+====
+If the above is not possible, timestamps should be at least reported in a consistent way, so time distance between distant events (for example periodic timer interrupt every) can be reliably calculated.
+
+It is needed to assure that time reported at exceptions/interrupt handlers will be a moment when exception or interrupt was observed.
+====
+
 === Corner Cases and Sequences
 
 Normal program flow generates a sequence of messages with I-CNT>0 (reporting at least 1 instruction retired), some HIST fields (to report direct conditional branches) and F-ADDR/U-ADDR fields (to report non-inferable unconditional flow changes).
@@ -1404,32 +1434,33 @@ However, sometimes normal flow is interrupted (by exception or interrupt) or som
 |Hart halted with trace disabled|<<msg2_ProgTraceCorrelation,ProgTraceCorrelation>> with <<field_EVCODE,EVCODE>>=0 (Enter Debug mode) and <<field_I-CNT,I-CNT>>=0 (nothing executed). 
 |====
 
-=== Timestamp Reporting
+=== Examples of Synchronizing Messages
 
-Timestamp recording must be enabled by <<trTsEnable,trTsEnable>> trace control bit.
+This chapter provides examples of several sequences of events and clarifies what types of <<Synchronizing Messages,synchronizing message>> should be generated in each case.
 
-If timestamp is enabled all <<Synchronizing Messages,Synchronizing Messages>> include an absolute timestamp value with upper zeroes suppressed. Other message types with timestamp emit the timestamp as relative offset from last reported (absolute or relative) timestamp.
+*Case1: Enable/disable debug while tracing:*
 
-NOTE: The TSTAMP field is a variable-length field and most significant bits=0 will not be transmitted. It will provide good compression for relative and absolute timestamps.
+image:./images/case1_enable_disable_debug_while_tracing.PNG[image]
 
-To reconstruct the full timestamp, software begins at a <<Synchronizing Messages,synchronizing message>> and stores the TSTAMP value found there, zero-extended to the full timestamp width. Shortly after starting a trace session, even a 64-bit timestamp will typically require far less than 64 bits to transmit. Software extracts the compressed TSTAMP from each message thereafter and adds it with the previous decompressed timestamp to obtain the full timestamp value associated with this message.
+*Case2: Enable trace while in debug:*
 
-The following rules must be observed:
+image:./images/case2_enable_trace_while_in_debug.PNG[image]
 
-* If timestamps are enabled, ALL <<Synchronizing Messages,Synchronizing Messages>> must include absolute TSTAMP value.
-* It is not required that ALL non-synchronizing messages are always reporting timestamp.
-** It may be done to save trace bandwidth or in case of sending back to back messages.
-* Absolute timestamp cannot exceed 64 bits (even with 1ps resolution, 64-bit counters will overflow in about 584 years).
-** Implementation may choose a smaller counter - trace tools may assume timestamp will not overflow in a single session, however it would not be very hard to add support for it.
-* It is suggested that in multi-hart systems all Trace Encoders use a shared timestamp (for better trace correlation), but it is not necessary.
-* Timestamp at all cases, when an address is provided should be at a time when an event leading to that particular address being sent happened.
+*Case3: Disable trace while in debug:*
 
-[NOTE]
-====
-If the above is not possible, timestamps should be at least reported in a consistent way, so time distance between distant events (for example periodic timer interrupt every) can be reliably calculated.
+image:./images/case3_disable_trace_while_in_debug.PNG[image]
 
-It is needed to assure that time reported at exceptions/interrupt handlers will be a moment when exception or interrupt was observed.
-====
+*Case4: Sync trigger event:*
+
+image:./images/case4_sync_trigger_event.PNG[image]
+
+*Case5: Enable/disable while in debug:*
+
+image:./images/case5_enable_disable_while_in_debug.PNG[image]
+
+*Case6: Periodic:*
+
+image:./images/case6_periodic.PNG[image]
 
 == Optimization Extensions