5.1. Timestamping

5.1. Timestamping

The support for Timestamps is optional and so the contents of this chapter are informative only.

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 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 one to judge performance of sections of code execution (to the granularity of timestamp insertion). The latter helps debugging multi-hart MP problems.

An implementation may have the following:

  • A timestamp is (up to) a 64-bit time value.

  • Configurable options for generating timestamp values such as a hart’s 'time' values or 'cycle' values.

  • Options could may also include things like taking 'time' values with the low 4 or 8 bits dropped off which would create a coarser granularity time values

  • Timestamp generation may be enabled or disabled. If enabled, a timestamp packet would be generated periodically which may be based on configurable interval or rate, e.g. once every 2n items where 'n' and 'items' are configurable among some limited set of choices. The choices could be:

    • Time

    • Time scaled down. An implementation specific scaled or divided down derivative of time. This may be useful in providing a smaller coarser graularity values

    • Time Interpolated up. An implementation specific interpolated up derivative of time. This may be useful in providing higher resolution time values

    • Cycle

    • Implementation specific

  • A timestamp packet may also be generated in conjunction with a sync packet

  • Timestamp packets are highly compressible and variable in size depending on the number of low bits of the current value that have changed wrt the last emitted timestamp value. If timestamp packets are emitted rarely (but not as rare as sync packets), then they will tend to be, say, 2-4 bytes in size (still much less than the full up to 64-bit size). If timestamp packets are emitted somewhat frequently, then they will tend to be 1-2 bytes in size. If timestamp packets are emitted very frequently, then they will tend to be <1 byte in size. Timestamp values associated with sync packets would always be the full implemented size.

Where packets are encapsulated according to the Unformatted Trace & Diagnostic Data Packet Encapsulation for RISC-V Specification, this includes provision for an optional N-byte timestamp within the encapsulation itself. This can be used to include a timestamp value with any of the trace packets defined in this specification. It is not usually desirable to include full timestamps (e.g. up to 64-bits) in each packet, as this adds a significant overhead, and the difference in timestamp values between successive packets is usually quite small. Using smaller, partial encapsulation timestamps (e.g. 16 bits) is typical.

With partial encapsulation timestamps, software can reconstruct the full timestamp value of any packet, provided that it initially receives a full timestamp (either in a sync packet, or possibly a dedicated timestamp packet), and then the interval between successive packets carrying only a partial encapsulation timestamp is less than 2N*8 ticks of the timestamp clock. The lower 2N*8 bits of the reconstructed timestamp are taken directly from the encapsulation timestamp. If the encapsulation timestamp value is smaller than the previous one, software can deduce that time has moved forward by an additional 2N*8 ticks, and add this to the reconstructed timestamp.

However, this reconstruction process fails if the interval between packets exceeds 2N*8. To prevent this, if the interval between packets does exceed 2N*8, the first packet sent subsequently must contain a full timestamp. This is typically a sync packet, but could be a dedicated timestamp packet. Requesting the insertion of packets containing full timestamps should be automatically managed by the packet encapsulation process.