PTWRITE

PTWRITE puts a value of the program’s choosing into the trace that Intel Processor Trace records. The trace is mostly control flow: which branches went which way, with timing. PTWRITE adds data at the points where the program asks for it, a loop counter, a request number or an argument, as a PTW packet whose payload is the 4 or 8 bytes of its operand. The packet carries no tag of its own: a decoder knows what a value means from where the PTWRITE that wrote it sits in the code.

Silent when nobody listens#

PTWRITE emits a packet only while tracing is on and its filters let the current code through (TriggerEn, ContextEn and FilterEn in IA32_RTIT_STATUS) and the tool that set up the trace enabled PTW packets with PTWEn, bit 12 of IA32_RTIT_CTL. Otherwise it changes nothing. With FUPonPTW, bit 5, each PTW packet is followed by a FUP packet that gives the address of the PTWRITE. The operand is read either way: a memory operand still raises #PF on an unmapped page, or #AC where alignment checking is on, whether or not a trace is running. PTWRITE runs at any privilege level.

Sizes and bytes#

• ptwrite r/m32 writes 4 bytes; with REX.W, 8 bytes. A 66 prefix raises #UD instead of selecting 16 bits.
• The encoding, F3 0F AE /4, sits beside the FS and GS base reads and writes, F3 0F AE /0 to /3 with a register operand (RDFSBASE and its kin); without F3, 0F AE /4 with a memory operand is XSAVE.

With -mptwrite, or an -march such as goldmont-plus, alderlake or sapphirerapids, GCC 14 and Clang 23 at -O2 compile _ptwrite32(x) to ptwrite edi and _ptwrite64(*p) to ptwrite QWORD PTR [rdi].

Where it runs#

PTWRITE needs CPUID leaf 14H, the Processor Trace leaf, to report it in EBX bit 4, and raises #UD otherwise. Intel’s manual introduces it with the Goldmont Plus Atom cores. AMD’s manual defines no PTWRITE, and the Zen 5 guest that ran the probe reported leaf 14H as all zeros: all four recorded cases, with 32- and 64-bit register and memory operands, raised #UD.

In the optimization guide

What the optimization guide says about PTWRITE, a line per claim. Each links to the claim in the guide, with its sources and where they differ.

Silvermont to Goldmont Plus

• Instruction set and counters: Silvermont is the first Atom core with SSE4.2 and POPCNT; Goldmont Plus adds RDPID and PTWRITE.

Forms

Latency and throughput

Operation

What the forms do, in pseudocode that our tests run against results recorded on real processors. How to read.

if not cpuid_leaf(0x14, 0)[1] >> 4 & 1:
    fault(UD)                    # CPUID: no PTWRITE
v = src.read()                   # 32 bits, or 64 with REX.W; read
                                 # whether it is traced or not
s = rtit_status                  # FilterEn, ContextEn, TriggerEn:
if s & 7 == 7 and rtit_ctl >> 12 & 1:
    ptw_packet(v, OSIZE, rtit_ctl >> 5 & 1)
                                 # PTWEn: a PTW packet, and with
                                 # FUPonPTW a FUP packet of the
                                 # instruction's address after it
# nothing else changes. With a 66 prefix, #UD

Operands

Flags

None: XED records no flag that the forms test or change.

Intrinsics

The C intrinsics of Clang 23.1.2 that compile to PTWRITE, each with the form it compiles to and the Clang options it needs. The forms come from compiling every intrinsic and decoding the result with Intel XED; all intrinsics A–Z explains the method.

CPUID and processors

Each form belongs to an XED ISA set. A form can be used when the processor reports every CPUID bit of one of its ISA set's alternatives.