PT_QRY_TIME(3)

🎀 NAME 🎀

okay bestie, gather round, because this one is literally all about asking your Intel(R) Processor Trace decoder for timing info 💖

The squad of functions living on this page is:

• pt_qry_time, pt_insn_time, pt_blk_time
• pt_qry_core_bus_ratio, pt_insn_core_bus_ratio, pt_blk_core_bus_ratio

and they're all here in section 3 of the manual. ✨

---

🦋 SYNOPSIS 🦋

Like, here's the whole cast list, verbatim, no notes:

#include <intel-pt.h>
int pt_qry_time(struct pt_query_decoder *decoder, uint64_t *time,
                uint32_t *lost_mtc, uint32_t *lost_cyc);
int pt_qry_core_bus_ratio(struct pt_query_decoder *decoder,
                          uint32_t *cbr);
int pt_insn_time(struct pt_insn_decoder *decoder, uint64_t *time,
                 uint32_t *lost_mtc, uint32_t *lost_cyc);
int pt_insn_core_bus_ratio(struct pt_insn_decoder *decoder,
                           uint32_t *cbr);
int pt_blk_time(struct pt_block_decoder *decoder, uint64_t *time,
                uint32_t *lost_mtc, uint32_t *lost_cyc);
int pt_blk_core_bus_ratio(struct pt_block_decoder *decoder,
                          uint32_t *cbr);

and you gotta link with -lipt. no cap, that part is not optional. 💅

---

🌸 DESCRIPTION 🌸

so, pt_qry_time(), pt_insn_time(), and pt_blk_time() hand you the current estimated timestamp count (TSC) value, and they drop it into the unsigned integer variable that the time argument points at. the value you get back? that's what an rdtsc instruction would have returned. iconic. ⭐

here's the tea on how that estimate even happens. at configurable intervals, Intel PT just straight up contains the full, accurate TSC value. but between those intervals, the timestamp count is estimated using a little collection of lower-bandwidth packets: the Mini Time Counter (MTC) packet and the Cycle Count Packet (CYC). depending on your Intel PT configuration, timing can be very precise at the cost of increased bandwidth, or less precise but requiring lower bandwidth. pick your fighter, bestie. 🥊

now, the decoder needs to be calibrated in order to translate Cycle Counter ticks into Core Crystal Clock ticks. without calibration, CYC packets need to be dropped. and the decoder calibrates itself using MTC, CYC, and CBR packets — it's self-sufficient like that. 👑

to interpret MTC and CYC packets, the decoder needs additional information provided in respective fields in the pt_config structure. lacking this information, MTC packets may need to be dropped. and like, that's not a vibe — it will impact the precision of the estimated timestamp count by losing periodic updates, and it will impact calibration, which may result in reduced precision for cycle-accurate timing. 😭

here's a little quality meter for you: the number of dropped MTC and CYC packets gives a rough idea about the quality of the estimated timestamp count. that dropped-packet value goes into the unsigned integer variables pointed to by the lost_mtc and lost_cyc arguments respectively. and if one or both of those arguments is NULL, then no information on lost packets is provided for the respective packet type. shrug, your call. 🙈

lastly, pt_qry_core_bus_ratio(), pt_insn_core_bus_ratio(), and pt_blk_core_bus_ratio() give you the last known core:bus ratio as provided by the Core Bus Ratio (CBR) Intel PT packet. cute, simple, done. 💜

---

✨ RETURN VALUE ✨

all of these functions return zero on success, or a negative pt_error_code enumeration constant in case of an error. that's the whole story, periodt. 🫶

---

💀 ERRORS 💀

• pte_invalid — the decoder argument is NULL, or the time argument is NULL (for pt_qry_time(), pt_insn_time(), and pt_blk_time()), or the cbr argument is NULL (for pt_qry_core_bus_ratio(), pt_insn_core_bus_ratio(), and pt_blk_core_bus_ratio()). basically somebody handed over a null pointer and the decoder is not having it. 🚫
• pte_no_time — there has not been a TSC packet to provide the full, accurate Time Stamp Count. there may have been MTC or CYC packets though, so the provided time may be non-zero. it is zero if there has not been any timing packet yet. 🕰️

also, depending on the Intel PT configuration, TSC packets may not have been enabled. in that case, the time value provides the relative time based on other timing packets. so like, still useful, just not absolute. iykyk. 🌈

• pte_no_cbr — there has not been a CBR packet to provide the core:bus ratio. the cbr value is undefined in this case. do not trust it, bestie, do not look at it. 🙈

---

🎀 SEE ALSO 🎀

go read these next, fr fr:

• pt_qry_alloc_decoder(3)
• pt_qry_free_decoder(3)
• pt_qry_cond_branch(3)
• pt_qry_indirect_branch(3)
• pt_qry_event(3)
• pt_insn_alloc_decoder(3)
• pt_insn_free_decoder(3)
• pt_insn_next(3)
• pt_blk_alloc_decoder(3)
• pt_blk_free_decoder(3)
• pt_blk_next(3)

---

and that's the whole page, bestie!! 🫶 this was PT_QRY_TIME(3) from the intel-pt.h library — go forth and query your timestamps with main character energy. slay. 💅✨