1PT_QRY_TIME(3) PT_QRY_TIME(3)
2
6 pt_qry_time, pt_qry_core_bus_ratio, pt_insn_time, pt_insn_core_bus_ra‐
7 tio, pt_blk_time, pt_blk_core_bus_ratio - query an Intel(R) Processor
8 Trace decoder for timing information
9
11 #include <intel-pt.h>
12 int pt_qry_time(struct pt_query_decoder *decoder, uint64_t *time,
13 uint32_t *lost_mtc, uint32_t *lost_cyc);
14 int pt_qry_core_bus_ratio(struct pt_query_decoder *decoder,
15 uint32_t *cbr);
16 int pt_insn_time(struct pt_insn_decoder *decoder, uint64_t *time,
17 uint32_t *lost_mtc, uint32_t *lost_cyc);
18 int pt_insn_core_bus_ratio(struct pt_insn_decoder *decoder,
19 uint32_t *cbr);
20 int pt_blk_time(struct pt_block_decoder *decoder, uint64_t *time,
21 uint32_t *lost_mtc, uint32_t *lost_cyc);
22 int pt_blk_core_bus_ratio(struct pt_block_decoder *decoder,
23 uint32_t *cbr);
24 Link with -lipt.
26
28 pt_qry_time(), pt_insn_time(), and pt_blk_time() provide the current
29 estimated timestamp count (TSC) value in the unsigned integer variable
30 pointed to by the time argument. The returned value corresponds to
31 what an rdtsc instruction would have returned.
32 At configurable intervals, Intel PT contains the full, accurate TSC
34 value. Between those intervals, the timestamp count is estimated using
35 a collection of lower-bandwidth packets, the Mini Time Counter (MTC)
36 packet and the Cycle Count Packet (CYC). Depending on the Intel PT
37 configuration, timing can be very precise at the cost of increased
38 bandwidth or less precise but requiring lower bandwidth.
39 The decoder needs to be calibrated in order to translate Cycle Counter
41 ticks into Core Crystal Clock ticks. Without calibration, CYC packets
42 need to be dropped. The decoder calibrates itself using MTC, CYC, and
43 CBR packets.
44 To interpret MTC and CYC packets, the decoder needs additional informa‐
46 tion provided in respective fields in the pt_config structure. Lacking
47 this information, MTC packets may need to be dropped. This will impact
48 the precision of the estimated timestamp count by losing periodic up‐
49 dates and it will impact calibration, which may result in reduced pre‐
50 cision for cycle-accurate timing.
51 The number of dropped MTC and CYC packets gives a rough idea about the
53 quality of the estimated timestamp count. The value of dropped MTC and
54 CYC packets is given in the unsigned integer variables pointed to by
55 the lost_mtc and lost_cyc arguments respectively. If one or both of
56 the arguments is NULL, no information on lost packets is provided for
57 the respective packet type.
58 pt_qry_core_bus_ratio(), pt_insn_core_bus_ratio(), and
60 pt_blk_core_bus_ratio() give the last known core:bus ratio as provided
61 by the Core Bus Ratio (CBR) Intel PT packet.
62
64 All functions return zero on success or a negative pt_error_code enu‐
65 meration constant in case of an error.
66
68 pte_invalid
69 The decoder or time (pt_qry_time(), pt_insn_time(), and
70 pt_blk_time()) or cbr (pt_qry_core_bus_ratio(), pt_in‐
71 sn_core_bus_ratio(), and pt_blk_core_bus_ratio()) argument is
72 NULL.
73 pte_no_time
75 There has not been a TSC packet to provide the full, accurate
76 Time Stamp Count. There may have been MTC or CYC packets, so
77 the provided time may be non-zero. It is zero if there has not
78 been any timing packet yet.
79 Depending on the Intel PT configuration, TSC packets may not
81 have been enabled. In this case, the time value provides the
82 relative time based on other timing packets.
83 pte_no_cbr
85 There has not been a CBR packet to provide the core:bus ratio.
86 The cbr value is undefined in this case.
87
89 pt_qry_alloc_decoder(3), pt_qry_free_decoder(3), pt_qry_cond_branch(3),
90 pt_qry_indirect_branch(3), pt_qry_event(3), pt_insn_alloc_decoder(3),
91 pt_insn_free_decoder(3), pt_insn_next(3), pt_blk_alloc_decoder(3),
92 pt_blk_free_decoder(3), pt_blk_next(3)
93 PT_QRY_TIME(3)