amd-debug-tools 0.2.0__py3-none-any.whl

amd_debug/wake.py

@@ -0,0 +1,111 @@
+#!/usr/bin/python3
+# SPDX-License-Identifier: MIT
+
+import os
+from pyudev import Context
+
+from amd_debug.common import read_file
+
+
+class WakeGPIO:
+    """Class for wake GPIOs"""
+
+    def __init__(self, num):
+        self.num = int(num)
+        self.name = ""
+
+    def __str__(self):
+        if self.name:
+            return f"{self.num} ({self.name})"
+        return f"{self.num}"
+
+
+class WakeIRQ:
+    """Class for wake IRQs"""
+
+    def __init__(self, num, context=Context()):
+        self.num = num
+        p = os.path.join("/", "sys", "kernel", "irq", str(num))
+        self.chip_name = read_file(os.path.join(p, "chip_name"))
+        self.actions = read_file(os.path.join(p, "actions"))
+        self.driver = ""
+        self.name = ""
+        wakeup = read_file(os.path.join(p, "wakeup"))
+
+        # This is an IRQ tied to _AEI
+        if self.chip_name == "amd_gpio":
+            hw_gpio = read_file(os.path.join(p, "hwirq"))
+            self.name = f"GPIO {hw_gpio}"
+        # legacy IRQs
+        elif "IR-IO-APIC" in self.chip_name:
+            if self.actions == "acpi":
+                self.name = "ACPI SCI"
+            elif self.actions == "i8042":
+                self.name = "PS/2 controller"
+            elif self.actions == "pinctrl_amd":
+                self.name = "GPIO Controller"
+            elif self.actions == "rtc0":
+                self.name = "RTC"
+            elif self.actions == "timer":
+                self.name = "Timer"
+            self.actions = ""
+        elif "PCI-MSI" in self.chip_name:
+            bdf = self.chip_name.split("-")[-1]
+            for dev in context.list_devices(subsystem="pci"):
+                if dev.device_path.endswith(bdf):
+                    vendor = dev.properties.get("ID_VENDOR_FROM_DATABASE")
+                    desc = dev.properties.get("ID_PCI_CLASS_FROM_DATABASE")
+                    if not desc:
+                        desc = dev.properties.get("ID_PCI_INTERFACE_FROM_DATABASE")
+                    name = dev.properties.get("PCI_SLOT_NAME")
+                    self.driver = dev.properties.get("DRIVER")
+                    self.name = f"{vendor} {desc} ({name})"
+                    break
+
+        # "might" look like an ACPI device, try to follow it
+        if not self.name and self.actions:
+            p = os.path.join("/", "sys", "bus", "acpi", "devices", self.actions)
+            if os.path.exists(p):
+                for directory in os.listdir(p):
+                    if "physical_node" not in directory:
+                        continue
+
+                    for root, _dirs, files in os.walk(
+                        os.path.join(p, directory), followlinks=True
+                    ):
+                        if "name" in files:
+                            self.name = read_file(os.path.join(root, "name"))
+                            t = os.path.join(root, "driver")
+                            if os.path.exists(t):
+                                self.driver = os.path.basename(os.readlink(t))
+                            break
+                    if self.name:
+                        break
+
+        # If the name isn't descriptive try to guess further
+        if self.driver and self.actions == self.name:
+            if self.driver == "i2c_hid_acpi":
+                self.name = f"{self.name} I2C HID device"
+
+        # check if it's disabled
+        if not self.name and wakeup == "disabled":
+            self.name = "Disabled interrupt"
+
+    def __str__(self):
+        actions = f" ({self.actions})" if self.actions else ""
+        return f"{self.name}{actions}"
+
+
+if __name__ == "__main__":
+    from tabulate import tabulate
+
+    pyudev = Context()
+
+    p = os.path.join("/sys", "kernel", "irq")
+    irqs = []
+    for d in os.listdir(p):
+        if os.path.isdir(os.path.join(p, d)):
+            w = WakeIRQ(d, pyudev)
+            irqs.append([int(d), str(WakeIRQ(d, pyudev))])
+    irqs.sort()
+    print(tabulate(irqs, tablefmt="fancy_grid"))

amd_debug_tools-0.2.0.dist-info/METADATA

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: amd-debug-tools
+Version: 0.2.0
+Summary: debug tools for AMD systems
+Author-email: Mario Limonciello <superm1@kernel.org>
+License-Expression: MIT
+Project-URL: Homepage, https://web.git.kernel.org/pub/scm/linux/kernel/git/superm1/amd-debug-tools.git/
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyudev
+Requires-Dist: packaging
+Requires-Dist: pandas
+Requires-Dist: jinja2
+Requires-Dist: tabulate
+Requires-Dist: seaborn
+Requires-Dist: cysystemd
+Requires-Dist: Jinja2
+Requires-Dist: matplotlib
+Requires-Dist: seaborn
+Dynamic: license-file
+
+# Helpful tools for debugging AMD Zen systems
+[![codecov](https://codecov.io/github/superm1/amd-debug-tools/graph/badge.svg?token=Z9WTBZADGT)](https://codecov.io/github/superm1/amd-debug-tools)
+[![PyPI](https://img.shields.io/pypi/v/amd-debug-tools.svg)](https://pypi.org/project/amd-debug-tools/)
+
+This repository hosts open tools that are useful for debugging issues on AMD systems.
+
+## Installation
+It is suggested to install tools in a virtual environment either using
+`pipx` or `python3 -m venv`.
+
+### From PyPI
+`amd-debug-tools` is distributed as a python wheel, which is a
+binary package format for Python. To install from PyPI, run the following
+command:
+
+    pipx install amd-debug-tools
+
+### From source
+To build the package from source, you will need to the `python3-build`
+package natively installed by your distribution package manager. Then you
+can generate and install a wheel by running the following commands:
+
+    python3 -m build
+    pipx install dist/amd-debug-tools-*.whl
+
+### Ensuring path
+If you have not used a `pipx` environment before, you may need to run the following command
+to set up the environment:
+
+    pipx ensurepath
+
+This will add the `pipx` environment to your path.
+
+### Running in tree
+If you want to run the tools in tree, you need to make sure that distro dependencies
+that would normally install into a venv are installed. This can be done by running:
+
+    ./install_deps.py
+
+After dependencies are installed, you can run the tools by running:
+
+    ./amd_s2idle.py
+    ./amd_bios.py
+    ./amd_pstate.py
+
+## amd-s2idle
+`amd-s2idle` is a tool used for analyzing the entry and exit of the s2idle
+state of a Linux system.
+
+It is intended to use with Linux kernel 6.1 or later and works by hooking
+into dynamic debugging messages and events that are generated by the kernel.
+
+For analysis of power consumption issues it can be hooked into `systemd` to
+run a command to capture data right before and after the system enters and
+exits the s2idle state.
+
+4 high level commands are supported.
+
+### `amd-s2idle install`
+This will install the systemd hook so that data will be captured before and
+after the system enters and exits the s2idle state.
+
+This will also install a bash completion script that can be used for other
+commands.
+
+**NOTE:** This command is only supported when run from a venv.
+
+### `amd-s2idle uninstall`
+This will uninstall the systemd hook and remove the bash completion script.
+
+**NOTE:** This command is only supported when run from a venv.
+
+### `amd-s2idle test`
+This will run a suspend cycle with a timer based wakeup and capture relevant
+data into a database and produce a report. This can also be used to run multiple cycles.
+
+The following optional arguments are supported for this command:
+
+        --count COUNT         Number of cycles to run
+        --duration DURATION   Duration of the cycle in seconds
+        --wait WAIT           Time to wait before starting the cycle in seconds
+        --format FORMAT       Format of the report to produce (html, txt or md)
+        --report-file         File to write the report to
+        --force               Run a test cycle even if the system fails to pass prerequisite checks
+        --random              Run sleep cycles for random durations and waits, using the --duration and --wait arguments as an upper bound
+        --logind              Use logind to suspend the system
+        --tool-debug          Enable debug logging
+        --bios-debug          Enable BIOS debug logging instead of notify logging
+
+If the tool is launched with an environment that can call `xdg-open`, the report
+will be opened in a browser.
+
+### `amd-s2idle report`
+This will produce a report from the data captured by the `test` command
+and/or from the systemd hook.  The report will default to 60 days of data.
+
+The following optional arguments are supported for this command:
+
+        --since SINCE         Date to start the report from
+        --until UNTIL         Date to end the report at
+        --format FORMAT       Format of the report to produce (html, txt or md)
+        --report-file         File to write the report to
+        --tool-debug          Enable tool debug logging
+        --report-debug        Include debug messages in the report
+
+If the tool is launched with an environment that can call `xdg-open`, the report
+will be opened in a browser.
+
+### `amd-s2idle version`
+This will print the version of the tool and exit.
+
+### Debug output
+All commands support the `--tool-debug` argument which will enable extra debug output. This is often needed for debugging issues with a particular cycle.
+
+**NOTE:** enabling debug output significantly increases the size of the report.
+It's suggested that you use `--since` and `--until` to focus on the cycles that you are interested in.
+
+## amd-bios
+`amd-bios` is a a tool that can be used to enable or disable BIOS AML debug logging
+-and to parse a kernel log that contains BIOS logs.
+
+### `amd-bios trace`
+Modify BIOS AML trace debug logging.
+
+One of the following arguments must be set for this command:
+
+        --enable       Enable BIOS AML tracing
+        --disable      Disable BIOS AML tracing
+
+The following optional arguments are supported for this command:
+
+        --tool-debug   Enable tool debug logging
+
+### `amd-bios parse`
+Parses a kernel log that contains BIOS AML debug logging and produces a report.
+
+The following optional arguments are supported for this command:
+
+        --input INPUT  Optional input file to parse
+        --tool-debug   Enable tool debug logging
+
+### `amd-bios version`
+This will print the version of the tool and exit.
+
+## amd-pstate
+`amd-pstate` is a tool used for identification of issues with amd-pstate.
+It will capture some state from the system as well as from the machine specific registers that
+amd-pstate uses.
+
+## Compatibility scripts
+
+Compatibility scripts are provided for the previous names the tools went by:
+`amd_s2idle.py`, `amd_bios.py` and `amd_pstate.py`.
+These allow cloning the repository and running the scripts without installing
+the package.
+

amd_debug_tools-0.2.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+amd_debug/__init__.py,sha256=aOtpIEKGLUStrh0e4qgilHW7HgF4Od-r9pOoZ87NwAM,1105
+amd_debug/acpi.py,sha256=fkD3Sov8cRT5ryPlakRlT7Z9jiCLT9x_MPWxt3xU_tc,3161
+amd_debug/battery.py,sha256=WN-6ys9PHCZIwg7PdwyBOa62GjBp8WKG0v1YZt5_W5s,3122
+amd_debug/bios.py,sha256=wmPKDsTZeQqsHjWpv-YHdgRNlCtFdzHQ6jJf0H3hjN8,3971
+amd_debug/common.py,sha256=Xi47CAutEAE6mPz3IkdUnU0ayGEkJo30OXr9DIHhu_0,8822
+amd_debug/database.py,sha256=GkRg3cmaNceyQ2_hy0MBAlMbnTDPHo2co2o4ObWpnQg,10621
+amd_debug/failures.py,sha256=QV3wxl9NYxUV5e0VmMy-pNLg4PoLeCVy0RvBux1pnZM,22536
+amd_debug/installer.py,sha256=fSUGLGElpVdUyYJjD4LWntVSmcF_faU6hRCM9t4kNAU,12154
+amd_debug/kernel.py,sha256=xzAy-sDY5-sd4jxyU7EaBokS7YsvEjoWRuexaTJNRBc,11851
+amd_debug/prerequisites.py,sha256=Tu6tDMXTptSSlkDtY_39SGLiJn8MDhUKUE2GLDtmRNI,46731
+amd_debug/pstate.py,sha256=akGdJkIxBp0bx3AeGv6ictNxwv8m0j9vQ2IZB0Jx3dM,9518
+amd_debug/s2idle-hook,sha256=LLiaqPtGd0qetu9n6EYxKHZaIdHpVQDONdOuSc0pfFg,1695
+amd_debug/s2idle.py,sha256=S6IAf87K16-G2xGIXCR6oym7GHGi1TZjxlFiz3s7bU4,12461
+amd_debug/sleep_report.py,sha256=dRoE21nkPMFoa5L9i5XrzPug4KesLfAf1RpPFB7Xpt0,15555
+amd_debug/validator.py,sha256=VomxJOp6ZYBp3oYEaNsD-rvio_b346VSRz7-hyhCS_c,33234
+amd_debug/wake.py,sha256=xT8WrFrN6voCmXWo5dsn4mQ7iR2QJxHrrYBd3EREG-Q,3936
+amd_debug/bash/amd-s2idle,sha256=g_cle1ElCJpwE4wcLezL6y-BdasDKTnNMhrtzKLE9ks,1142
+amd_debug/templates/html,sha256=tnpqHDZF5FfhC6YNRUfOG6Vn9ZtISFr10kEXSB476Mw,14518
+amd_debug/templates/md,sha256=F0xt7m-lOsSz1VeucHA6a-1gsOH7rrik15biXnDgd54,904
+amd_debug/templates/stdout,sha256=hyoOJ96K2dJfnWRWhyCuariLKbEHXvs9mstV_g5aMdI,469
+amd_debug/templates/txt,sha256=nNdsvbPFOhGdL7VA-_4k5aN3nB-6ouGQt6AsWst7T3w,649
+amd_debug_tools-0.2.0.dist-info/licenses/LICENSE,sha256=RBlZI6r3MRGzymI2VDX2iW__D2APDbMhu_Xg5t6BWeo,1066
+amd_debug_tools-0.2.0.dist-info/METADATA,sha256=iyX-wpq8WWdx619aSLbeUd8knAdfm_UCcamPu5mLQVE,6783
+amd_debug_tools-0.2.0.dist-info/WHEEL,sha256=0CuiUZ_p9E4cD6NyLD6UG80LBXYyiSYZOKDm5lp32xk,91
+amd_debug_tools-0.2.0.dist-info/entry_points.txt,sha256=HC11T2up0pPfroAn6Pg5M2jOZXhkWIipToJ1YPTKqu8,116
+amd_debug_tools-0.2.0.dist-info/top_level.txt,sha256=7yUDU3ZY79gqXz0vl4TJzoTfngMPfQhrYFRU8PR2CB4,10
+amd_debug_tools-0.2.0.dist-info/RECORD,,

amd_debug_tools-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.3.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

amd_debug_tools-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+amd-bios = amd_debug:amd_bios
+amd-pstate = amd_debug:amd_pstate
+amd-s2idle = amd_debug:amd_s2idle

amd_debug_tools-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2025 Advanced Micro Devices
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

amd_debug_tools-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+amd_debug