rykit 0.1.0__tar.gz

rykit-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.3
+Name: rykit
+Version: 0.1.0
+Summary: Add your description here
+Author: Ryan Kosta
+Author-email: Ryan Kosta <rkosta@ucsd.edu>
+License: MIT
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+

rykit-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "rykit"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "Ryan Kosta", email = "rkosta@ucsd.edu" }
+]
+license = { text = "MIT" }
+requires-python = ">=3.13"
+dependencies = []
+
+[tool.uv]
+packages = ["rykit"]
+src = "src"
+
+
+[build-system]
+requires = ["uv_build>=0.9.18,<0.10.0"]
+build-backend = "uv_build"

rykit-0.1.0/src/rykit/__init__.py

@@ -0,0 +1,2 @@
+def main() -> None:
+    print("Hello from rykit!")

rykit-0.1.0/src/rykit/cmd.py

@@ -0,0 +1,48 @@
+import subprocess
+def run_command_read_stderr(cmd: str) -> str:
+    """
+    Run a shell command and capture stderr output.
+
+    Args:
+        cmd (str): The shell command to execute.
+
+    Returns:
+        str: The stderr output of the command (perf writes stats here).
+    """
+    print(f"running cmd: {cmd}")
+    result = subprocess.run(
+        cmd, shell=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True
+    )
+    output: str = result.stderr  # perf outputs stats to stderr
+    if result.returncode == 124:  # 124 is timeout exit code
+        print("Command timed out as expected.")
+    elif result.returncode != 0:
+        # output is stderr
+        print(output)
+        raise ValueError(f"Command failed with exit code {result.returncode}.")
+    else:
+        print("command returned 0")
+    return output
+
+
+def run_command_read_stdout(cmd: str) -> str:
+    """
+    Run a shell command and capture stdout output.
+
+    Args:
+        cmd (str): The shell command to execute.
+
+    Returns:
+        str: The stderr output of the command (perf writes stats here).
+    """
+    print(f"running cmd: {cmd}")
+    result = subprocess.run(
+        cmd, shell=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True
+    )
+    output: str = result.stdout
+    if result.returncode == 124:  # 124 is timeout exit code
+        print("Command timed out as expected.")
+    elif result.returncode != 0:
+        print(result.stderr)
+        raise ValueError(f"Command failed with exit code {result.returncode}.")
+    return output

rykit-0.1.0/src/rykit/intel_tools.py

@@ -0,0 +1,10 @@
+import glob
+def get_cha_count() -> int:
+    """
+    Return the number of CHA devices under /sys/devices.
+
+    Returns:
+        int: Count of directories matching 'uncore_cha_*'.
+    """
+    cha_paths = glob.glob("/sys/devices/uncore_cha_*")
+    return len(cha_paths)

rykit-0.1.0/src/rykit/linux_tools.py

@@ -0,0 +1,108 @@
+from typing import Dict,List
+from rykit.cmd import run_command_read_stdout
+def lscpu() -> Dict[str, str]:
+    """
+    Parse the output of `lscpu` into a dictionary.
+
+    Returns:
+        Dict[str, str]: Mapping of lscpu fields to their values.
+    """
+    res = {}
+    for line in run_command_read_stdout("lscpu").split("\n"):
+        if ":" not in line:
+            continue
+        segments = [x.strip() for x in line.split(":")]
+        res[segments[0]] = segments[1]
+    return res
+
+
+def normalize(x: str, units: Dict[str, int], default: str):
+    """
+    Normalize a string containing a number and a unit into the default unit.
+
+    Args:
+        x (str): Input string, e.g., "64KB".
+        units (Dict[str, int]): Dictionary mapping unit strings to their scale factors.
+        default (str): The default unit to normalize to.
+
+    Returns:
+        int: The value converted to the default unit.
+
+    Raises:
+        AssertionError: If the default unit is not in the units dictionary.
+        ValueError: If the input string does not contain a recognized unit.
+    """
+    assert default in units
+    units_longest_first = sorted(list(units.keys()), key=len, reverse=True)
+    for unit in units_longest_first:
+        if unit in x:
+            val = int(x.split(unit)[0].strip())
+            scale_factor = units[unit] / units[default]
+            return int(val * scale_factor)
+    raise ValueError(
+        f"{x} did not contain a valid unit out of choices {units_longest_first}"
+    )
+
+
+def lscpu_cache() -> Dict[str, Dict[str, str]]:
+    """
+    Parse `lscpu -C` output to get per-CPU cache and CPU info.
+
+    Returns:
+        Dict[str, Dict[str, str]]: Mapping from CPU ID to its properties.
+    """
+    rows = run_command_read_stdout("lscpu -C").split("\n")
+    col_names = rows[0].split()
+    res = {}
+    for row in rows[1:]:
+        cells = row.split()
+        if len(cells) < 1:
+            continue
+        key = cells[0]
+        val = {k: v for k, v in zip(col_names[1:], cells[1:])}
+        res[key] = val
+    return res
+
+
+def parse_range_list(s: str) -> List[int]:
+    """
+    Convert a string representing ranges into a list of integers.
+
+    Args:
+        s (str): Range string, e.g., "0-3,5,7-8".
+
+    Returns:
+        List[int]: Expanded list of integers from the range string.
+    """
+    result = []
+    for part in s.split(","):
+        if "-" in part:
+            start, end = map(int, part.split("-"))
+            result.extend(range(start, end + 1))
+        else:
+            result.append(int(part))
+    return result
+
+
+def get_socket(skt: int) -> List[int]:
+    """
+    Get the list of CPU IDs belonging to a specific NUMA socket.
+
+    Args:
+        skt (int): NUMA socket index (0-based).
+
+    Returns:
+        List[int]: List of CPU IDs for the socket.
+
+    Raises:
+        AssertionError: If the socket index is invalid.
+    """
+    assert skt >= 0
+
+    info = lscpu()
+    node_ct = int(info["NUMA node(s)"])
+
+    assert skt < node_ct
+    nodestr = info[f"NUMA node{skt} CPU(s)"]
+
+    return parse_range_list(nodestr)

rykit-0.1.0/src/rykit/perf_sample.py

@@ -0,0 +1,172 @@
+from rykit.cmd import run_command_read_stdout
+from rykit.cmd import run_command_read_stderr
+from typing import List, Dict 
+
+def set_perf_event_paranoid(level: int):
+    """
+    Sets the kernel's perf_event_paranoid level.
+
+    The perf_event_paranoid setting controls the restrictions on
+    performance monitoring for non-root users:
+        -1 : No restrictions
+         0 : Normal access, but system-wide tracepoints may be restricted
+         1 : Restricted access to CPU performance events
+         2 : Disallow CPU performance events for unprivileged users
+         3 : Maximum restriction (default on many systems)
+
+    Args:
+        level (int): The desired paranoid level (-1 to 3).
+
+    Raises:
+        AssertionError: If level is not an int or not in the allowed range.
+    """
+    assert type(level) == int
+    assert -1 <= level and level <= 3, f"tried to set perf_event_paranoid to {level}, allowed values are -1 through 3"
+    cmd = f"sudo sysctl -w kernel.perf_event_paranoid={level}"
+    run_command_read_stdout(cmd)
+
+def get_perf_event_paranoid() -> int:
+    """
+    Returns the current kernel perf_event_paranoid level
+    """
+    try:
+        with open("/proc/sys/kernel/perf_event_paranoid", "r") as f:
+            return int(f.read().strip())
+    except Exception as e:
+        raise RuntimeError(f"Failed to read perf_event_paranoid: {e}")
+
+
+def interpret_umask(binval: str) -> str:
+    """
+    Convert a binary string umask into its hexadecimal representation.
+
+    Args:
+        binval (str): A string representing a binary number (e.g., "1101").
+
+    Returns:
+        str: The hexadecimal representation of the binary umask
+             (e.g., "0xd" for "1101").
+
+    Raises:
+        ValueError: If `binval` is not a valid binary string.
+    """
+    try:
+        val: int = int(binval, 2)
+    except:
+        raise ValueError(f"mask {binval} was not a valid binary string")
+
+    if val > 255:
+        raise ValueError(f"{binval} was more then 8 bits")
+
+    hex_str = str(hex(val))
+    return hex_str
+
+
+
+
+def interpret_core_events(output: str, core_events: List[str]) -> Dict[str, int]:
+    """
+    Parse perf output for core events.
+
+    Args:
+        output (str): Raw stderr output from perf.
+        core_events (List[str]): List of event names to extract.
+
+    Returns:
+        Dict[str,int]: Mapping of event name -> event counter value.
+    """
+    lines = output.split("\n")
+    res: Dict[str, int] = {}
+    for line in lines:
+        for event in core_events:
+            if event in line:
+                # remove name of event
+                valstr = line.split(event)[0]
+                valstr = valstr.strip()
+
+                # remove commas
+                valstr = valstr.replace(",", "")
+
+                if "Byte" in valstr:
+
+                    valstr = valstr.split("Byte")[0]
+
+                    # TODO this is debatable whether you want this,
+                    # Many events which are labeled byte
+                    # cast from cache line to byte (ie: *64)
+                    # so casting back (ie /64) is natural in most cases
+                    val = int(int(valstr) / 64)
+                else:
+                    val = int(valstr)
+                res[event] = val
+    return res
+def interpret_per_core_event(output:str,event:str,socket:int) -> Dict[str,int]:
+    data : Dict[int,Dict[str,int]] = {skt:{} for skt in range(2)}
+    for line in output.split("\n"):
+        if event not in line:
+            continue
+        fields : List[str] = [x for x in line.split(";") if x != ""]
+        #print(fields)
+        #[S0,D0,C0]
+        core_code = fields[0].split("-")
+        socket_num = int(core_code[0][1:])
+        core = core_code[2][1:]
+        ctr = int(fields[2])
+        data[socket_num][core] = ctr
+    #print(data[socket])
+    return data[socket]
+def perf_sample_per_core_event(cmd:str,event:str,socket:int) -> Dict[str,int]:
+    perf_cmd = f"sudo perf stat --per-core -x \\; -a -e {event} {cmd}"
+    output = run_command_read_stderr(perf_cmd)
+    return interpret_per_core_event(output,event,socket)
+def perf_sample_per_core_events(cmd:str,events:List[str],socket:int) -> Dict[str,Dict[str,int]]:
+    eventstr = " ".join([f"-e {event}" for event in events])
+    perf_cmd = f"sudo perf stat --per-core -x \\; -a {eventstr} {cmd}"
+    output = run_command_read_stderr(perf_cmd)
+    return {event:interpret_per_core_event(output,event,socket) for event in events}
+def perf_normalize_per_core_events(cmd:str,events:List[str],socket:int) -> Dict[str,Dict[str,float]]:
+    events += ["cycles"]
+    res = perf_sample_per_core_events(cmd,events,socket)
+    cycles = res["cycles"]
+    normalized_res = {event:{core:ctr/cycles[core] for core,ctr in percore.items()} for event,percore in res.items()}
+    return normalized_res
+
+
+
+
+
+
+
+def add_zeroes_to_eventcode(eventcode: str, zeroct: int):
+    raw_hex_str = eventcode.split("0x")[1]
+    return "0x" + ("0" * zeroct) + raw_hex_str
+
+def perf_sample_core_events(cmd: str, core_events: List[str]) -> Dict[str, int]:
+    """
+    Run perf sampling for core events.
+
+    Args:
+        cmd (str): Command to run under perf.
+        core_events (List[str]): List of core event names.
+
+    Returns:
+        Dict[str,int]: Mapping of event name -> event counter value.
+    """
+
+    event_flags = [f"-e {e}" for e in core_events]
+    event_flag_str = " ".join(event_flags)
+
+    output = run_command_read_stderr(f"sudo perf stat {event_flag_str} {cmd}")
+    return interpret_core_events(output, core_events)
+def perf_sample_core_event(cmd: str, core_event: str) -> int:
+    """
+    Run perf sampling for core event.
+
+    Args:
+        cmd (str): Command to run under perf.
+        core_event (str):  core event name.
+
+    Returns:
+        int: core event value 
+    """
+    return perf_sample_core_events(cmd,[core_event])[core_event]

rykit-0.1.0/src/rykit/perf_sample_amd.py

@@ -0,0 +1,29 @@
+from typing import Dict, List, Tuple
+from rykit.perf_sample import perf_sample_core_events,interpret_umask
+def perf_sample_amd_uncore_event_many(
+    cmd: str, unc_events: List[Tuple[str, str]]
+) -> Dict[str, int]:
+    """
+    Run perf sampling for multiple uncore events.
+
+    Args:
+        cmd (str): Command to run under perf.
+        unc_events (List[Tuple[str,str]]): List of (event, binary umask) pairs.
+
+    Returns:
+        Dict[str,Dict[str,int]]: Mapping of event code -> event counter value.
+    """
+    events = [f"amd_df/event={event},umask={interpret_umask(umask)}/" for event,umask in unc_events]
+    return perf_sample_core_events(cmd,events)
+def perf_sample_core_event(cmd: str, core_event: str) -> int:
+    """
+    Run perf sampling for core event.
+
+    Args:
+        cmd (str): Command to run under perf.
+        core_event (str):  core event name.
+
+    Returns:
+        int: core event value 
+    """
+    return perf_sample_core_events(cmd,[core_event])[core_event]

rykit-0.1.0/src/rykit/perf_sample_intel.py

@@ -0,0 +1,193 @@
+import subprocess
+import glob
+from typing import Dict, List, Tuple
+from rykit.perf_sample import interpret_umask, add_zeroes_to_eventcode
+from rykit.intel_tools import get_cha_count
+from rykit.cmd import run_command_read_stderr
+
+
+
+
+def create_unc_cha_event(chanum: int, event: str, hexmask: str) -> str:
+    """
+    Create a perf event string for a single CHA.
+
+    Args:
+        chanum (int): CHA index.
+        event (str): Event code in hexadecimal (e.g., "0xb3").
+        hexmask (str): Umask in hexadecimal (e.g., "0x8").
+
+    Returns:
+        str: Perf event string for the CHA.
+    """
+    return f"uncore_cha_{chanum}/event={event},umask={hexmask}/"
+
+
+def create_unc_cha_events(event: str, hexmask: str) -> List[str]:
+    """
+    Create perf event strings for all CHAs on the system.
+
+    Args:
+        event (str): Event code in hexadecimal.
+        hexmask (str): Umask in hexadecimal.
+
+    Returns:
+        List[str]: Perf event strings for each CHA.
+    """
+
+    num_chas = get_cha_count()
+    return [create_unc_cha_event(chanum, event, hexmask) for chanum in range(num_chas)]
+
+
+def build_perf_sample_uncore_cmd(
+    program_cmd: str, unc_events: List[Tuple[str, str]]
+) -> str:
+    """
+    Build a perf command that samples multiple uncore events.
+
+    Args:
+        program_cmd (str): Command to run under perf.
+        unc_events (List[Tuple[str,str]]): List of (event, binary umask) pairs.
+
+    Returns:
+        str: The full perf command string.
+    """
+    events: List[str] = []
+    for event, mask in unc_events:
+        hexmask = interpret_umask(mask)
+        events += create_unc_cha_events(event, hexmask)
+    event_args: List[str] = [f"-e {e}" for e in events]
+    event_arg_str = " ".join(event_args)
+    return f"sudo perf stat -a {event_arg_str} -- {program_cmd}"
+
+
+def interpret_uncore_event(output: str, event: str) -> Dict[str, int]:
+    """
+    Parse perf output for a single uncore event across CHAs.
+
+    Args:
+        output (str): Raw stderr output from perf.
+        event (str): Event code in hexadecimal.
+
+    Returns:
+        Dict[str,int]: Mapping of CHA index (as str) -> event counter value.
+    """
+    infix = "uncore_cha_"
+    number_suffix = f"/event={event}"
+    result: Dict[str, int] = {}
+    for line in output.split("\n"):
+        # check to ensure this is a cha line
+        if infix not in line or number_suffix not in line:
+            continue
+        # Example:
+        # ex:     8,795      uncore_cha_1/event=0xb3,umask=0x8/
+
+        # remove name of event
+        # ex ->:      8,795
+        count_str_with_commas = line.split(infix)[0]
+
+        # remove ,
+        # ex ->:      8795
+        count_str = count_str_with_commas.replace(",", "")
+
+        count = int(count_str)
+
+        # chanum comes right after infix
+        chanum = line.split(infix)[1].split(number_suffix)[0]
+        result[chanum] = count
+    return result
+
+
+def interpret_uncore_event_many(
+    output: str, events: List[str]
+) -> Dict[str, Dict[str, int]]:
+    """
+    Parse perf output for multiple uncore events.
+
+    Args:
+        output (str): Raw stderr output from perf.
+        events (List[str]): List of event codes in hexadecimal.
+
+    Returns:
+        Dict[str,Dict[str,int]]: Mapping of event code ->
+             CHA index (as str) -> event counter value.
+    """
+    return {e: interpret_uncore_event(output, e) for e in events}
+
+
+def perf_sample_uncore_event_many(
+    program_cmd: str, unc_events: List[Tuple[str, str]]
+) -> Dict[str, Dict[str, int]]:
+    """
+    Run perf sampling for multiple uncore events.
+
+    Args:
+        program_cmd (str): Command to run under perf.
+        unc_events (List[Tuple[str,str]]): List of (event, binary umask) pairs.
+
+    Returns:
+        Dict[str,Dict[str,int]]: Mapping of event code ->
+            CHA index (as str) -> event counter value.
+    """
+    assert isinstance(program_cmd, str), "cmd must be passed as string (passed non-str)"
+    assert len(unc_events) <= 4, "can only run upto 4 uncore events at once"
+
+    events = [e for e, _ in unc_events]
+    if len(events) != len(set(events)):
+        raise ValueError(
+            f'this function does not support passing two identical event codes (passed {events})\n\t hint: prepend 0 ie ["0xF", "0x0F","0x00F","0x000F"]'
+        )
+
+    for _, mask in unc_events:
+        assert isinstance(mask, str), "mask must be a binary string (passed non-str)"
+        assert set(mask) <= {"0", "1"}, f"mask must be a binary string (passed {mask})"
+
+    cmd = build_perf_sample_uncore_cmd(program_cmd, unc_events)
+
+    output = run_command_read_stderr(cmd)
+
+    events = [unce[0] for unce in unc_events]
+
+    return interpret_uncore_event_many(output, events)
+
+
+def perf_sample_uncore_event(program_cmd: str, event: str, mask: str) -> Dict[str, int]:
+    """
+    Run perf sampling for a single uncore event.
+
+    Args:
+        program_cmd (str): Command to run under perf.
+        event (str): Event code in hexadecimal.
+        mask (str): Umask in binary string form.
+
+    Returns:
+        Dict[str,int]: Mapping of CHA index (as str) -> event counter value.
+    """
+    res = perf_sample_uncore_event_many(program_cmd, [(event, mask)])
+    return list(res.values())[0]
+
+
+
+
+def perf_sample_uncore_event_many_named_masks(
+    cmd: str, eventcode: str, masks: Dict[str, str]
+) -> Dict[str, Dict[str, int]]:
+    # create a list of unique eventcodes for each mask by adding zeroes to RHS (ie 0xF, 0x0F, 0x00F, ...) so that we have U  UID for event info from perf
+    name_to_code: dict[str, str] = {
+        k: add_zeroes_to_eventcode(eventcode, zeroct)
+        for zeroct, k in enumerate(masks.keys())
+    }
+    code_to_name: dict[str, str] = {v: k for k, v in name_to_code.items()}
+
+    uncore_events: List[Tuple[str, str]] = [
+        (code, masks[name]) for name, code in name_to_code.items()
+    ]
+
+    res_by_event_code: Dict[str, Dict[str, int]] = perf_sample_uncore_event_many(
+        cmd, uncore_events
+    )
+    # convert keys from eventcode to eventname
+    res_by_event_name: Dict[str, Dict[str, int]] = {
+        code_to_name[code]: ctr for code, ctr in res_by_event_code.items()
+    }
+    return res_by_event_name