projects/linux·blob uaccess-cleanups · refs

672 lines · 15.8 KiB

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."""