PtDefinitions.h File Reference

Intel Processor Trace (PT) related data structures and hardware definitions shared between the kernel and user-mode components. More...

Go to the source code of this file.

Classes
union	_PT_RTIT_CTL_REGISTER
	IA32_RTIT_CTL — PT master control register. More...
union	_PT_RTIT_STATUS_REGISTER
	IA32_RTIT_STATUS — PT status / error register. More...
union	_PT_OUTPUT_MASK_PTRS_REGISTER
	IA32_RTIT_OUTPUT_MASK_PTRS — Output position tracker. More...
union	_PT_TOPA_ENTRY
	ToPA Table Entry. More...
struct	_PT_CAPABILITIES
	Discovered Intel PT capabilities (populated from CPUID leaf 0x14). More...
struct	_PT_ADDR_RANGE
	Intel PT IP filter range. More...
struct	_PT_TRACE_CONFIG
	Intel PT trace configuration — what the user specifies. More...
struct	_PT_BUFFER
	Per-CPU PT buffer layout. More...
struct	_PT_PER_CPU
	Per-CPU Intel PT state — one of these per logical processor. More...
struct	_PT_OUTPUT_BUFFER
	Trace output descriptor. More...
struct	_PT_USER_BUFFER_DESC
	One per-CPU descriptor returned by the PT mmap surface. More...

Macros
#define	MSR_IA32_RTIT_OUTPUT_BASE   0x00000560
#define	MSR_IA32_RTIT_OUTPUT_MASK_PTRS   0x00000561
#define	MSR_IA32_RTIT_CTL   0x00000570
#define	MSR_IA32_RTIT_STATUS   0x00000571
#define	MSR_IA32_RTIT_CR3_MATCH   0x00000572
#define	MSR_IA32_RTIT_ADDR0_A   0x00000580
#define	MSR_IA32_RTIT_ADDR0_B   0x00000581
#define	MSR_IA32_RTIT_ADDR1_A   0x00000582
#define	MSR_IA32_RTIT_ADDR1_B   0x00000583
#define	MSR_IA32_RTIT_ADDR2_A   0x00000584
#define	MSR_IA32_RTIT_ADDR2_B   0x00000585
#define	MSR_IA32_RTIT_ADDR3_A   0x00000586
#define	MSR_IA32_RTIT_ADDR3_B   0x00000587
#define	MSR_IA32_PERF_GLOBAL_STATUS   0x0000038E
#define	MSR_IA32_PERF_GLOBAL_OVF_CTRL   0x00000390
#define	PERF_GLOBAL_STATUS_TOPA_PMI   (1ULL << 55)
#define	PT_PAGE_SIZE   0x1000ULL /* 4 KB */
#define	PT_DEFAULT_BUFFER_SIZE   0x200000ULL /* 2 MB */
#define	PT_OVERFLOW_SIZE   PT_PAGE_SIZE /* 4 KB overflow landing zone */
#define	PT_MAX_ADDR_RANGES   4
#define	PT_MAX_CPUS_FOR_MMAP   64
#define	PT_TOPA_SIZE_4K   0
#define	PT_TOPA_SIZE_8K   1
#define	PT_TOPA_SIZE_16K   2
#define	PT_TOPA_SIZE_32K   3
#define	PT_TOPA_SIZE_64K   4
#define	PT_TOPA_SIZE_128K   5
#define	PT_TOPA_SIZE_256K   6
#define	PT_TOPA_SIZE_512K   7
#define	PT_TOPA_SIZE_1M   8
#define	PT_TOPA_SIZE_2M   9
#define	PT_TOPA_SIZE_4M   10
#define	PT_TOPA_SIZE_8M   11
#define	PT_TOPA_SIZE_16M   12
#define	PT_TOPA_SIZE_32M   13
#define	PT_TOPA_SIZE_64M   14
#define	PT_TOPA_SIZE_128M   15

Typedefs
typedef union _PT_RTIT_CTL_REGISTER	PT_RTIT_CTL_REGISTER
	IA32_RTIT_CTL — PT master control register.
typedef union _PT_RTIT_STATUS_REGISTER	PT_RTIT_STATUS_REGISTER
	IA32_RTIT_STATUS — PT status / error register.
typedef union _PT_OUTPUT_MASK_PTRS_REGISTER	PT_OUTPUT_MASK_PTRS_REGISTER
	IA32_RTIT_OUTPUT_MASK_PTRS — Output position tracker.
typedef union _PT_TOPA_ENTRY	PT_TOPA_ENTRY
	ToPA Table Entry.
typedef struct _PT_CAPABILITIES	PT_CAPABILITIES
	Discovered Intel PT capabilities (populated from CPUID leaf 0x14).
typedef enum _PT_STATE	PT_STATE
	Intel PT trace state machine.
typedef struct _PT_ADDR_RANGE	PT_ADDR_RANGE
	Intel PT IP filter range.
typedef struct _PT_TRACE_CONFIG	PT_TRACE_CONFIG
	Intel PT trace configuration — what the user specifies.
typedef struct _PT_BUFFER	PT_BUFFER
	Per-CPU PT buffer layout.
typedef struct _PT_PER_CPU	PT_PER_CPU
	Per-CPU Intel PT state — one of these per logical processor.
typedef struct _PT_OUTPUT_BUFFER	PT_OUTPUT_BUFFER
	Trace output descriptor.
typedef struct _PT_USER_BUFFER_DESC	PT_USER_BUFFER_DESC
	One per-CPU descriptor returned by the PT mmap surface.

Enumerations
enum	_PT_STATE {   PT_STATE_DISABLED = 0 , PT_STATE_READY , PT_STATE_TRACING , PT_STATE_PAUSED ,   PT_STATE_STOPPED , PT_STATE_ERROR }
	Intel PT trace state machine. More...

Detailed Description

Intel Processor Trace (PT) related data structures and hardware definitions shared between the kernel and user-mode components.

Author

Masoud Rahimi Jafari (Masoo.nosp@m.drah.nosp@m.imy13.nosp@m.79@g.nosp@m.mail..nosp@m.com)

Version

0.19

Date

2026-04-29

Copyright

This project is released under the GNU Public License v3.

Macro Definition Documentation

MSR_IA32_PERF_GLOBAL_OVF_CTRL

#define MSR_IA32_PERF_GLOBAL_OVF_CTRL   0x00000390

MSR_IA32_PERF_GLOBAL_STATUS

#define MSR_IA32_PERF_GLOBAL_STATUS   0x0000038E

MSR_IA32_RTIT_ADDR0_A

#define MSR_IA32_RTIT_ADDR0_A   0x00000580

MSR_IA32_RTIT_ADDR0_B

#define MSR_IA32_RTIT_ADDR0_B   0x00000581

MSR_IA32_RTIT_ADDR1_A

#define MSR_IA32_RTIT_ADDR1_A   0x00000582

MSR_IA32_RTIT_ADDR1_B

#define MSR_IA32_RTIT_ADDR1_B   0x00000583

MSR_IA32_RTIT_ADDR2_A

#define MSR_IA32_RTIT_ADDR2_A   0x00000584

MSR_IA32_RTIT_ADDR2_B

#define MSR_IA32_RTIT_ADDR2_B   0x00000585

MSR_IA32_RTIT_ADDR3_A

#define MSR_IA32_RTIT_ADDR3_A   0x00000586

MSR_IA32_RTIT_ADDR3_B

#define MSR_IA32_RTIT_ADDR3_B   0x00000587

MSR_IA32_RTIT_CR3_MATCH

#define MSR_IA32_RTIT_CR3_MATCH   0x00000572

MSR_IA32_RTIT_CTL

#define MSR_IA32_RTIT_CTL   0x00000570

MSR_IA32_RTIT_OUTPUT_BASE

#define MSR_IA32_RTIT_OUTPUT_BASE   0x00000560

MSR_IA32_RTIT_OUTPUT_MASK_PTRS

#define MSR_IA32_RTIT_OUTPUT_MASK_PTRS   0x00000561

MSR_IA32_RTIT_STATUS

#define MSR_IA32_RTIT_STATUS   0x00000571

PERF_GLOBAL_STATUS_TOPA_PMI

#define PERF_GLOBAL_STATUS_TOPA_PMI   (1ULL << 55)

PT_DEFAULT_BUFFER_SIZE

#define PT_DEFAULT_BUFFER_SIZE   0x200000ULL /* 2 MB */

PT_MAX_ADDR_RANGES

#define PT_MAX_ADDR_RANGES   4

PT_MAX_CPUS_FOR_MMAP

#define PT_MAX_CPUS_FOR_MMAP   64

PT_OVERFLOW_SIZE

#define PT_OVERFLOW_SIZE   PT_PAGE_SIZE /* 4 KB overflow landing zone */

PT_PAGE_SIZE

#define PT_PAGE_SIZE   0x1000ULL /* 4 KB */

PT_TOPA_SIZE_128K

#define PT_TOPA_SIZE_128K   5

PT_TOPA_SIZE_128M

#define PT_TOPA_SIZE_128M   15

PT_TOPA_SIZE_16K

#define PT_TOPA_SIZE_16K   2

PT_TOPA_SIZE_16M

#define PT_TOPA_SIZE_16M   12

PT_TOPA_SIZE_1M

#define PT_TOPA_SIZE_1M   8

PT_TOPA_SIZE_256K

#define PT_TOPA_SIZE_256K   6

PT_TOPA_SIZE_2M

#define PT_TOPA_SIZE_2M   9

PT_TOPA_SIZE_32K

#define PT_TOPA_SIZE_32K   3

PT_TOPA_SIZE_32M

#define PT_TOPA_SIZE_32M   13

PT_TOPA_SIZE_4K

#define PT_TOPA_SIZE_4K   0

PT_TOPA_SIZE_4M

#define PT_TOPA_SIZE_4M   10

PT_TOPA_SIZE_512K

#define PT_TOPA_SIZE_512K   7

PT_TOPA_SIZE_64K

#define PT_TOPA_SIZE_64K   4

PT_TOPA_SIZE_64M

#define PT_TOPA_SIZE_64M   14

PT_TOPA_SIZE_8K

#define PT_TOPA_SIZE_8K   1

PT_TOPA_SIZE_8M

#define PT_TOPA_SIZE_8M   11

Typedef Documentation

PT_ADDR_RANGE

typedef struct _PT_ADDR_RANGE PT_ADDR_RANGE

Intel PT IP filter range.

PT_BUFFER

typedef struct _PT_BUFFER PT_BUFFER

Per-CPU PT buffer layout.

ToPA Table (one 4KB page, 3 entries used): Entry[0] — Main data buffer (BufferSize), INT=1 Entry[1] — Overflow zone (4KB), INT=0 Entry[2] — END, points back to ToPA table (circular)

PT_CAPABILITIES

typedef struct _PT_CAPABILITIES PT_CAPABILITIES

Discovered Intel PT capabilities (populated from CPUID leaf 0x14).

PT_OUTPUT_BUFFER

typedef struct _PT_OUTPUT_BUFFER PT_OUTPUT_BUFFER

Trace output descriptor.

Passed to the engine to receive trace data. WriteOffset serves dual purpose:

• Input: where in Buffer to start writing new data.
• Output: updated to Buffer[0..WriteOffset) = valid data after the call.

If the remaining space (Length - WriteOffset) is smaller than the new data, the copy is skipped and WriteOffset is not updated. Pass NULL instead of a PT_OUTPUT_BUFFER * to skip copying entirely.

PT_OUTPUT_MASK_PTRS_REGISTER

typedef union _PT_OUTPUT_MASK_PTRS_REGISTER PT_OUTPUT_MASK_PTRS_REGISTER

IA32_RTIT_OUTPUT_MASK_PTRS — Output position tracker.

Intel SDM Vol. 3, Section 32.2.7.8

PT_PER_CPU

typedef struct _PT_PER_CPU PT_PER_CPU

Per-CPU Intel PT state — one of these per logical processor.

PT_RTIT_CTL_REGISTER

typedef union _PT_RTIT_CTL_REGISTER PT_RTIT_CTL_REGISTER

IA32_RTIT_CTL — PT master control register.

Intel SDM Vol. 3, Section 32.2.7.2

PT_RTIT_STATUS_REGISTER

typedef union _PT_RTIT_STATUS_REGISTER PT_RTIT_STATUS_REGISTER

IA32_RTIT_STATUS — PT status / error register.

Intel SDM Vol. 3, Section 32.2.7.4

PT_STATE

typedef enum _PT_STATE PT_STATE

Intel PT trace state machine.

PT_TOPA_ENTRY

typedef union _PT_TOPA_ENTRY PT_TOPA_ENTRY

ToPA Table Entry.

Intel SDM Vol. 3, Section 32.2.7.2 (Table of Physical Addresses)

PT_TRACE_CONFIG

typedef struct _PT_TRACE_CONFIG PT_TRACE_CONFIG

Intel PT trace configuration — what the user specifies.

PT_USER_BUFFER_DESC

typedef struct _PT_USER_BUFFER_DESC PT_USER_BUFFER_DESC

One per-CPU descriptor returned by the PT mmap surface.

   The main output buffer and the 4 KB overflow page are stitched
   into a single virtually contiguous region in the calling user
   process — main first, then overflow, matching the order PT
   writes them on a ToPA PMI. Consumers read the whole stream
   as Size bytes starting at UserVa.

   UserVa is valid only in the address space of the process that
   issued the mmap IOCTL, and only until PT is disabled / flushed
   (at which point the underlying kernel buffers are torn down).

Enumeration Type Documentation

_PT_STATE

enum _PT_STATE

Intel PT trace state machine.

Enumerator
PT_STATE_DISABLED
PT_STATE_READY
PT_STATE_TRACING
PT_STATE_PAUSED
PT_STATE_STOPPED
PT_STATE_ERROR

{
    PT_STATE_DISABLED = 0, /* No buffers allocated, PT off                */
    PT_STATE_READY,        /* Buffers allocated, MSRs not yet programmed  */
    PT_STATE_TRACING,      /* TraceEn=1, actively generating packets      */
    PT_STATE_PAUSED,       /* TraceEn=0 temporarily (PMI or user pause)   */
    PT_STATE_STOPPED,      /* Tracing done, buffer has valid data         */
    PT_STATE_ERROR         /* Hardware error (check IA32_RTIT_STATUS)     */
} PT_STATE;