path: root/tools/perf/python/perf.pyi

"""Type stubs for the perf Python module."""
from typing import Callable, Dict, List, Optional, Any, Iterator, Union

def config_get(name: str) -> Optional[str]:
    """Get a configuration value from perf config.

    Args:
        name: The configuration variable name (e.g., 'colors.top').

    Returns:
        The configuration value as a string, or None if not set.
    """
    ...

def metrics() -> List[Dict[str, Union[str, List[str]]]]:
    """Get a list of available metrics.

    Returns:
        A list of dictionaries, each describing a metric.
    """
    ...

def syscall_name(id: int, *, elf_machine: Optional[int] = None) -> str:
    """Convert a syscall number to its name.

    Args:
        sc_id: The syscall number.
        elf_machine: Optional ELF machine type.

    Returns:
        The name of the syscall.
    """
    ...

def syscall_id(name: str, *, elf_machine: Optional[int] = None) -> int:
    """Convert a syscall name to its number.

    Args:
        name: The syscall name.
        elf_machine: Optional ELF machine type.

    Returns:
        The number of the syscall.
    """
    ...

def parse_events(
    event_string: str,
    cpus: Optional[cpu_map] = None,
    threads: Optional['thread_map'] = None
) -> 'evlist':
    """Parse an event string and return an evlist.

    Args:
        event_string: The event string (e.g., 'cycles,instructions').
        cpus: Optional CPU map to bind events to.
        threads: Optional thread map to bind events to.

    Returns:
        An evlist containing the parsed events.
    """
    ...

def parse_metrics(
    metrics_string: str,
    pmu: Optional[str] = None,
    cpus: Optional[cpu_map] = None,
    threads: Optional['thread_map'] = None
) -> 'evlist':
    """Parse a string of metrics or metric groups and return an evlist."""
    ...

def tracepoint(sys: str, name: str) -> int:
    """Returns the tracepoint ID for a given system and name."""
    ...

def pmus() -> Iterator[Any]:
    """Returns a sequence of pmus."""
    ...

class data:
    """Represents a perf data file."""
    def __init__(self, path: str = ..., fd: int = ...) -> None: ...

class thread:
    """Represents a thread in the system."""
    def comm(self) -> str:
        """Get the command name of the thread."""
        ...
    pid: int
    tid: int
    ppid: int
    cpu: int

class counts_values:
    """Raw counter values."""
    id: int
    val: int
    ena: int
    run: int
    lost: int
    values: List[int]

class thread_map:
    """Map of threads being monitored."""
    def __init__(self, pid: int = -1, tid: int = -1) -> None:
        """Initialize a thread map.

        Args:
            pid: Process ID to monitor (-1 for all).
            tid: Thread ID to monitor (-1 for all).
        """
        ...
    def __len__(self) -> int: ...
    def __getitem__(self, index: int) -> int: ...
    def __iter__(self) -> Iterator[int]: ...

class evsel:
    """Event selector, represents a single event being monitored."""
    def __init__(
        self,
        type: int = ...,
        config: int = ...,
        sample_freq: int = ...,
        sample_period: int = ...,
        sample_type: int = ...,
        read_format: int = ...,
        disabled: bool = ...,
        inherit: bool = ...,
        pinned: bool = ...,
        exclusive: bool = ...,
        exclude_user: bool = ...,
        exclude_kernel: bool = ...,
        exclude_hv: bool = ...,
        exclude_idle: bool = ...,
        mmap: bool = ...,
        context_switch: bool = ...,
        comm: bool = ...,
        freq: bool = ...,
        inherit_stat: bool = ...,
        enable_on_exec: bool = ...,
        task: bool = ...,
        watermark: int = ...,
        precise_ip: int = ...,
        mmap_data: bool = ...,
        sample_id_all: bool = ...,
        wakeup_events: int = ...,
        bp_type: int = ...,
        bp_addr: int = ...,
        bp_len: int = ...,
        idx: int = ...,
    ) -> None: ...
    def __str__(self) -> str:
        """Return string representation of the event."""
        ...
    def open(self) -> None:
        """Open the event selector file descriptor table."""
        ...
    def read(self, cpu: int, thread: int) -> counts_values:
        """Read counter values for a specific CPU and thread."""
        ...
    ids: List[int]
    def cpus(self) -> cpu_map:
        """Get CPU map for this event."""
        ...
    def threads(self) -> thread_map:
        """Get thread map for this event."""
        ...
    tracking: bool
    config: int
    read_format: int
    sample_period: int
    sample_type: int
    size: int
    type: int
    wakeup_events: int


class _sample_members:
    sample_pid: int
    sample_tid: int
    sample_time: int
    sample_id: int
    sample_stream_id: int
    sample_period: int
    sample_cpu: int

class sample_event(_sample_members):
    """Represents a sample event from perf."""
    evsel: evsel
    sample_ip: int
    sample_addr: int
    sample_phys_addr: int
    sample_weight: int
    sample_data_src: int
    sample_insn_count: int
    sample_cyc_count: int
    type: int
    raw_buf: bytes
    dso: str
    dso_long_name: str
    dso_bid: Optional[bytes]
    map_start: int
    map_end: int
    map_pgoff: int
    symbol: str
    sym_start: int
    sym_end: int
    brstack: Optional['branch_stack']
    callchain: Optional['callchain']
    def srccode(self) -> str: ...
    def insn(self) -> str: ...
    def __getattr__(self, name: str) -> Any: ...

class mmap_event(_sample_members):
    """Represents a mmap event from perf."""
    type: int
    misc: int
    pid: int
    tid: int
    start: int
    len: int
    pgoff: int
    filename: str
    evsel: Optional['evsel']

class mmap2_event(_sample_members):
    """Represents a mmap2 event from perf."""
    type: int
    misc: int
    pid: int
    tid: int
    start: int
    len: int
    pgoff: int
    prot: int
    flags: int
    filename: str
    maj: Optional[int]
    min: Optional[int]
    ino: Optional[int]
    ino_generation: Optional[int]
    build_id: Optional[bytes]
    evsel: Optional['evsel']

class lost_event(_sample_members):
    """Represents a lost events record."""
    type: int
    id: int
    lost: int
    evsel: Optional['evsel']

class comm_event(_sample_members):
    """Represents a COMM record."""
    type: int
    pid: int
    tid: int
    comm: str
    evsel: Optional['evsel']

class task_event(_sample_members):
    """Represents an EXIT or FORK record."""
    type: int
    pid: int
    ppid: int
    tid: int
    ptid: int
    time: int
    evsel: Optional['evsel']

class throttle_event(_sample_members):
    """Represents a THROTTLE or UNTHROTTLE record."""
    type: int
    time: int
    id: int
    stream_id: int
    evsel: Optional['evsel']

class read_event(_sample_members):
    """Represents a READ record."""
    type: int
    pid: int
    tid: int
    evsel: Optional['evsel']

class switch_event(_sample_members):
    """Represents a SWITCH or SWITCH_CPU_WIDE record."""
    type: int
    next_prev_pid: int
    next_prev_tid