1"""Type stubs for the perf Python module.""" 2from typing import Callable, Dict, List, Optional, Any, Iterator, Union 3 4def config_get(name: str) -> Optional[str]: 5 """Get a configuration value from perf config. 6 7 Args: 8 name: The configuration variable name (e.g., 'colors.top'). 9 10 Returns: 11 The configuration value as a string, or None if not set. 12 """ 13 ... 14 15def metrics() -> List[Dict[str, Union[str, List[str]]]]: 16 """Get a list of available metrics. 17 18 Returns: 19 A list of dictionaries, each describing a metric. 20 """ 21 ... 22 23def syscall_name(id: int, *, elf_machine: Optional[int] = None) -> str: 24 """Convert a syscall number to its name. 25 26 Args: 27 sc_id: The syscall number. 28 elf_machine: Optional ELF machine type. 29 30 Returns: 31 The name of the syscall. 32 """ 33 ... 34 35def syscall_id(name: str, *, elf_machine: Optional[int] = None) -> int: 36 """Convert a syscall name to its number. 37 38 Args: 39 name: The syscall name. 40 elf_machine: Optional ELF machine type. 41 42 Returns: 43 The number of the syscall. 44 """ 45 ... 46 47def parse_events( 48 event_string: str, 49 cpus: Optional[cpu_map] = None, 50 threads: Optional['thread_map'] = None 51) -> 'evlist': 52 """Parse an event string and return an evlist. 53 54 Args: 55 event_string: The event string (e.g., 'cycles,instructions'). 56 cpus: Optional CPU map to bind events to. 57 threads: Optional thread map to bind events to. 58 59 Returns: 60 An evlist containing the parsed events. 61 """ 62 ... 63 64def parse_metrics( 65 metrics_string: str, 66 pmu: Optional[str] = None, 67 cpus: Optional[cpu_map] = None, 68 threads: Optional['thread_map'] = None 69) -> 'evlist': 70 """Parse a string of metrics or metric groups and return an evlist.""" 71 ... 72 73def tracepoint(sys: str, name: str) -> int: 74 """Returns the tracepoint ID for a given system and name.""" 75 ... 76 77def pmus() -> Iterator[Any]: 78 """Returns a sequence of pmus.""" 79 ... 80 81class data: 82 """Represents a perf data file.""" 83 def __init__(self, path: str = ..., fd: int = ...) -> None: ... 84 85class thread: 86 """Represents a thread in the system.""" 87 def comm(self) -> str: 88 """Get the command name of the thread.""" 89 ... 90 pid: int 91 tid: int 92 ppid: int 93 cpu: int 94 95class counts_values: 96 """Raw counter values.""" 97 id: int 98 val: int 99 ena: int 100 run: int 101 lost: int 102 values: List[int] 103 104class thread_map: 105 """Map of threads being monitored.""" 106 def __init__(self, pid: int = -1, tid: int = -1) -> None: 107 """Initialize a thread map. 108 109 Args: 110 pid: Process ID to monitor (-1 for all). 111 tid: Thread ID to monitor (-1 for all). 112 """ 113 ... 114 def __len__(self) -> int: ... 115 def __getitem__(self, index: int) -> int: ... 116 def __iter__(self) -> Iterator[int]: ... 117 118class evsel: 119 """Event selector, represents a single event being monitored.""" 120 def __init__( 121 self, 122 type: int = ..., 123 config: int = ..., 124 sample_freq: int = ..., 125 sample_period: int = ..., 126 sample_type: int = ..., 127 read_format: int = ..., 128 disabled: bool = ..., 129 inherit: bool = ..., 130 pinned: bool = ..., 131 exclusive: bool = ..., 132 exclude_user: bool = ..., 133 exclude_kernel: bool = ..., 134 exclude_hv: bool = ..., 135 exclude_idle: bool = ..., 136 mmap: bool = ..., 137 context_switch: bool = ..., 138 comm: bool = ..., 139 freq: bool = ..., 140 inherit_stat: bool = ..., 141 enable_on_exec: bool = ..., 142 task: bool = ..., 143 watermark: int = ..., 144 precise_ip: int = ..., 145 mmap_data: bool = ..., 146 sample_id_all: bool = ..., 147 wakeup_events: int = ..., 148 bp_type: int = ..., 149 bp_addr: int = ..., 150 bp_len: int = ..., 151 idx: int = ..., 152 ) -> None: ... 153 def __str__(self) -> str: 154 """Return string representation of the event.""" 155 ... 156 def open(self) -> None: 157 """Open the event selector file descriptor table.""" 158 ... 159 def read(self, cpu: int, thread: int) -> counts_values: 160 """Read counter values for a specific CPU and thread.""" 161 ... 162 ids: List[int] 163 def cpus(self) -> cpu_map: 164 """Get CPU map for this event.""" 165 ... 166 def threads(self) -> thread_map: 167 """Get thread map for this event.""" 168 ... 169 tracking: bool 170 config: int 171 read_format: int 172 sample_period: int 173 sample_type: int 174 size: int 175 type: int 176 wakeup_events: int 177 178 179class _sample_members: 180 sample_pid: int 181 sample_tid: int 182 sample_time: int 183 sample_id: int 184 sample_stream_id: int 185 sample_period: int 186 sample_cpu: int 187 188class sample_event(_sample_members): 189 """Represents a sample event from perf.""" 190 evsel: evsel 191 sample_ip: int 192 sample_addr: int 193 sample_phys_addr: int 194 sample_weight: int 195 sample_data_src: int 196 sample_insn_count: int 197 sample_cyc_count: int 198 type: int 199 raw_buf: bytes 200 dso: str 201 dso_long_name: str 202 dso_bid: Optional[bytes] 203 map_start: int 204 map_end: int 205 map_pgoff: int 206 symbol: str 207 sym_start: int 208 sym_end: int 209 brstack: Optional['branch_stack'] 210 callchain: Optional['callchain'] 211 def srccode(self) -> str: ... 212 def insn(self) -> str: ... 213 def __getattr__(self, name: str) -> Any: ... 214 215class mmap_event(_sample_members): 216 """Represents a mmap event from perf.""" 217 type: int 218 misc: int 219 pid: int 220 tid: int 221 start: int 222 len: int 223 pgoff: int 224 filename: str 225 evsel: Optional['evsel'] 226 227class mmap2_event(_sample_members): 228 """Represents a mmap2 event from perf.""" 229 type: int 230 misc: int 231 pid: int 232 tid: int 233 start: int 234 len: int 235 pgoff: int 236 prot: int 237 flags: int 238 filename: str 239 maj: Optional[int] 240 min: Optional[int] 241 ino: Optional[int] 242 ino_generation: Optional[int] 243 build_id: Optional[bytes] 244 evsel: Optional['evsel'] 245 246class lost_event(_sample_members): 247 """Represents a lost events record.""" 248 type: int 249 id: int 250 lost: int 251 evsel: Optional['evsel'] 252 253class comm_event(_sample_members): 254 """Represents a COMM record.""" 255 type: int 256 pid: int 257 tid: int 258 comm: str 259 evsel: Optional['evsel'] 260 261class task_event(_sample_members): 262 """Represents an EXIT or FORK record.""" 263 type: int 264 pid: int 265 ppid: int 266 tid: int 267 ptid: int 268 time: int 269 evsel: Optional['evsel'] 270 271class throttle_event(_sample_members): 272 """Represents a THROTTLE or UNTHROTTLE record.""" 273 type: int 274 time: int 275 id: int 276 stream_id: int 277 evsel: Optional['evsel'] 278 279class read_event(_sample_members): 280 """Represents a READ record.""" 281 type: int 282 pid: int 283 tid: int 284 evsel: Optional['evsel'] 285 286class switch_event(_sample_members): 287 """Represents a SWITCH or SWITCH_CPU_WIDE record.""" 288 type: int 289 next_prev_pid: int 290 next_prev_tid: int 291 evsel: Optional['evsel'] 292 293class branch_entry: 294 """Represents a branch entry in the branch stack. 295 296 Attributes: 297 from_ip: Source address of the branch (corresponds to 'from' keyword in C). 298 to_ip: Destination address of the branch. 299 mispred: True if the branch was mispredicted. 300 predicted: True if the branch was predicted. 301 in_tx: True if the branch was in a transaction. 302 abort: True if the branch was an abort. 303 cycles: Number of cycles since the last branch. 304 type: Type of branch. 305 """ 306 from_ip: int 307 to_ip: int 308 mispred: bool 309 predicted: bool 310 in_tx: bool 311 abort: bool 312 cycles: int 313 type: int 314 315class branch_stack: 316 """Sequence of branch entries in the branch stack.""" 317 def __len__(self) -> int: ... 318 def __getitem__(self, index: int) -> branch_entry: ... 319 320class callchain_node: 321 """Represents a frame in the callchain.""" 322 ip: int 323 symbol: Optional[str] 324 dso: Optional[str] 325 326class callchain: 327 """Sequence of callchain frames.""" 328 def __len__(self) -> int: ... 329 def __getitem__(self, index: int) -> callchain_node: ... 330 331class stat_event(_sample_members): 332 """Represents a stat event from perf.""" 333 type: int 334 id: int 335 cpu: int 336 thread: int 337 val: int 338 ena: int 339 run: int 340 evsel: Optional['evsel'] 341 342class stat_round_event(_sample_members): 343 """Represents a stat round event from perf.""" 344 type: int 345 time: int 346 stat_round_type: int 347 evsel: Optional['evsel'] 348 349class cpu_map: 350 """Map of CPUs being monitored.""" 351 def __init__(self, cpustr: Optional[str] = None) -> None: ... 352 def __len__(self) -> int: ... 353 def __getitem__(self, index: int) -> int: ... 354 def __iter__(self) -> Iterator[int]: ... 355 356 357class evlist: 358 def __init__(self, cpus: cpu_map, threads: thread_map) -> None: ... 359 def open(self) -> None: 360 """Open the events in the list.""" 361 ... 362 def close(self) -> None: 363 """Close the events in the list.""" 364 ... 365 def mmap(self) -> None: 366 """Memory map the event buffers.""" 367 ... 368 def poll(self, timeout: int) -> int: 369 """Poll for events. 370 371 Args: 372 timeout: Timeout in milliseconds. 373 374 Returns: 375 Number of events ready. 376 """ 377 ... 378 def read_on_cpu(self, cpu: int) -> Optional[Any]: 379 """Read a sample event from a specific CPU. 380 381 Args: 382 cpu: The CPU number. 383 384 Returns: 385 A sample_event or other event type if available, or None. 386 """ 387 ... 388 def all_cpus(self) -> cpu_map: 389 """Get a cpu_map of all CPUs in the system.""" 390 ... 391 def metrics(self) -> List[str]: 392 """Get a list of metric names within the evlist.""" 393 ... 394 def compute_metric(self, metric: str, cpu: int, thread: int) -> float: 395 """Compute metric for given name, cpu and thread. 396 397 Args: 398 metric: The metric name. 399 cpu: The CPU number. 400 thread: The thread ID. 401 402 Returns: 403 The computed metric value. 404 """ 405 ... 406 def config(self) -> None: 407 """Configure the events in the list.""" 408 ... 409 def disable(self) -> None: 410 """Disable all events in the list.""" 411 ... 412 def enable(self) -> None: 413 """Enable all events in the list.""" 414 ... 415 def get_pollfd(self) -> List[int]: 416 """Get a list of file descriptors for polling.""" 417 ... 418 def add(self, evsel: evsel) -> int: 419 """Add an event to the list.""" 420 ... 421 def __iter__(self) -> Iterator[evsel]: 422 """Iterate over the events (evsel) in the list.""" 423 ... 424 425 426class session: 427 def __init__( 428 self, 429 data: data, 430 sample: Optional[Callable[[sample_event], None]] = None, 431 stat: Optional[Callable[[Any, Optional[str]], None]] = None 432 ) -> None: 433 """Initialize a perf session. 434 435 Args: 436 data: The perf data file to read. 437 sample: Callback for sample events. 438 stat: Callback for stat events. 439 """ 440 ... 441 def process_events(self) -> None: 442 """Process all events in the session.""" 443 ... 444 def find_thread(self, pid: int) -> thread: 445 """Returns the thread associated with a pid.""" 446 ... 447 448# Event Types 449TYPE_HARDWARE: int 450"""Hardware event.""" 451 452TYPE_SOFTWARE: int 453"""Software event.""" 454 455TYPE_TRACEPOINT: int 456"""Tracepoint event.""" 457 458TYPE_HW_CACHE: int 459"""Hardware cache event.""" 460 461TYPE_RAW: int 462"""Raw hardware event.""" 463 464TYPE_BREAKPOINT: int 465"""Breakpoint event.""" 466 467 468# Hardware Counters 469COUNT_HW_CPU_CYCLES: int 470"""Total cycles. Be wary of what happens during CPU frequency scaling.""" 471 472COUNT_HW_INSTRUCTIONS: int 473"""Retired instructions. Be careful, these can be affected by various issues, 474most notably hardware interrupt counts.""" 475 476COUNT_HW_CACHE_REFERENCES: int 477"""Cache accesses. Usually this indicates Last Level Cache accesses but this 478may vary depending on your CPU.""" 479 480COUNT_HW_CACHE_MISSES: int 481"""Cache misses. Usually this indicates Last Level Cache misses.""" 482 483COUNT_HW_BRANCH_INSTRUCTIONS: int 484"""Retired branch instructions.""" 485 486COUNT_HW_BRANCH_MISSES: int 487"""Mispredicted branch instructions.""" 488 489COUNT_HW_BUS_CYCLES: int 490"""Bus cycles, which can be different from total cycles.""" 491 492COUNT_HW_STALLED_CYCLES_FRONTEND: int 493"""Stalled cycles during issue [This event is an alias of idle-cycles-frontend].""" 494 495COUNT_HW_STALLED_CYCLES_BACKEND: int 496"""Stalled cycles during retirement [This event is an alias of idle-cycles-backend].""" 497 498COUNT_HW_REF_CPU_CYCLES: int 499"""Total cycles; not affected by CPU frequency scaling.""" 500 501 502# Cache Counters 503COUNT_HW_CACHE_L1D: int 504"""Level 1 data cache.""" 505 506COUNT_HW_CACHE_L1I: int 507"""Level 1 instruction cache.""" 508 509COUNT_HW_CACHE_LL: int 510"""Last Level Cache.""" 511 512COUNT_HW_CACHE_DTLB: int 513"""Data TLB.""" 514 515COUNT_HW_CACHE_ITLB: int 516"""Instruction TLB.""" 517 518COUNT_HW_CACHE_BPU: int 519"""Branch Processing Unit.""" 520 521COUNT_HW_CACHE_OP_READ: int 522"""Read accesses.""" 523 524COUNT_HW_CACHE_OP_WRITE: int 525"""Write accesses.""" 526 527COUNT_HW_CACHE_OP_PREFETCH: int 528"""Prefetch accesses.""" 529 530COUNT_HW_CACHE_RESULT_ACCESS: int 531"""Accesses.""" 532 533COUNT_HW_CACHE_RESULT_MISS: int 534"""Misses.""" 535 536 537# Software Counters 538COUNT_SW_CPU_CLOCK: int 539"""CPU clock event.""" 540 541COUNT_SW_TASK_CLOCK: int 542"""Task clock event.""" 543 544COUNT_SW_PAGE_FAULTS: int 545"""Page faults.""" 546 547COUNT_SW_CONTEXT_SWITCHES: int 548"""Context switches.""" 549 550COUNT_SW_CPU_MIGRATIONS: int 551"""CPU migrations.""" 552 553COUNT_SW_PAGE_FAULTS_MIN: int 554"""Minor page faults.""" 555 556COUNT_SW_PAGE_FAULTS_MAJ: int 557"""Major page faults.""" 558 559COUNT_SW_ALIGNMENT_FAULTS: int 560"""Alignment faults.""" 561 562COUNT_SW_EMULATION_FAULTS: int 563"""Emulation faults.""" 564 565COUNT_SW_DUMMY: int 566"""Dummy event.""" 567 568 569# Sample Fields 570SAMPLE_IP: int 571"""Instruction pointer.""" 572 573SAMPLE_TID: int 574"""Process and thread ID.""" 575 576SAMPLE_TIME: int 577"""Timestamp.""" 578 579SAMPLE_ADDR: int 580"""Sampled address.""" 581 582SAMPLE_READ: int 583"""Read barcode.""" 584 585SAMPLE_CALLCHAIN: int 586"""Call chain.""" 587 588SAMPLE_ID: int 589"""Unique ID.""" 590 591SAMPLE_CPU: int 592"""CPU number.""" 593 594SAMPLE_PERIOD: int 595"""Sample period.""" 596 597SAMPLE_STREAM_ID: int 598"""Stream ID.""" 599 600SAMPLE_RAW: int 601"""Raw sample.""" 602 603 604# Format Fields 605FORMAT_TOTAL_TIME_ENABLED: int 606"""Total time enabled.""" 607 608FORMAT_TOTAL_TIME_RUNNING: int 609"""Total time running.""" 610 611FORMAT_ID: int 612"""Event ID.""" 613 614FORMAT_GROUP: int 615"""Event group.""" 616 617 618# Record Types 619RECORD_MMAP: int 620"""MMAP record. Contains header, pid, tid, addr, len, pgoff, filename, and sample_id.""" 621 622RECORD_LOST: int 623"""Lost events record. Contains header, id, lost count, and sample_id.""" 624 625RECORD_COMM: int 626"""COMM record. Contains header, pid, tid, comm, and sample_id.""" 627 628RECORD_EXIT: int 629"""EXIT record. Contains header, pid, ppid, tid, ptid, time, and sample_id.""" 630 631RECORD_THROTTLE: int 632"""THROTTLE record. Contains header, time, id, stream_id, and sample_id.""" 633 634RECORD_UNTHROTTLE: int 635"""UNTHROTTLE record. Contains header, time, id, stream_id, and sample_id.""" 636 637RECORD_FORK: int 638"""FORK record. Contains header, pid, ppid, tid, ptid, time, and sample_id.""" 639 640RECORD_READ: int 641"""READ record. Contains header, and read values.""" 642 643RECORD_SAMPLE: int 644"""SAMPLE record. Contains header, and sample data requested by sample_type.""" 645 646RECORD_MMAP2: int 647"""MMAP2 record. Contains header, pid, tid, addr, len, pgoff, maj, min, ino, 648ino_generation, prot, flags, filename, and sample_id.""" 649 650RECORD_AUX: int 651"""AUX record. Contains header, aux_offset, aux_size, flags, and sample_id.""" 652 653RECORD_ITRACE_START: int 654"""ITRACE_START record. Contains header, pid, tid, and sample_id.""" 655 656RECORD_LOST_SAMPLES: int 657"""LOST_SAMPLES record. Contains header, lost count, and sample_id.""" 658 659RECORD_SWITCH: int 660"""SWITCH record. Contains header, and sample_id.""" 661 662RECORD_SWITCH_CPU_WIDE: int 663"""SWITCH_CPU_WIDE record. Contains header, and sample_id.""" 664 665RECORD_STAT: int 666"""STAT record.""" 667 668RECORD_STAT_ROUND: int 669"""STAT_ROUND record.""" 670 671RECORD_MISC_SWITCH_OUT: int 672"""MISC_SWITCH_OUT record.""" 673