amd-debug-tools 0.2.0__tar.gz

amd_debug_tools-0.2.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,156 @@
+# 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/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=59.8.0", "setuptools-git-versioning>=2.0,<3"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools-git-versioning]
+enabled = true
+
+[project]
+name = "amd-debug-tools"
+authors = [{ name = "Mario Limonciello", email = "superm1@kernel.org" }]
+description = "debug tools for AMD systems"
+readme = "README.md"
+requires-python = ">=3.7"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: POSIX :: Linux",
+]
+dependencies = [
+    "pyudev",
+    "packaging",
+    "pandas",
+    "jinja2",
+    "tabulate",
+    "seaborn",
+    "cysystemd",
+    "Jinja2",
+    "matplotlib",
+    "seaborn",
+]
+dynamic = ["version", "scripts"]
+license = "MIT"
+
+[project.urls]
+"Homepage" = "https://web.git.kernel.org/pub/scm/linux/kernel/git/superm1/amd-debug-tools.git/"

amd_debug_tools-0.2.0/setup.cfg

@@ -0,0 +1,23 @@
+[options]
+package_dir = 
+	=src
+packages = find_namespace:
+
+[options.packages.find]
+where = src
+
+[options.entry_points]
+console_scripts = 
+	amd-s2idle = amd_debug:amd_s2idle
+	amd-bios = amd_debug:amd_bios
+	amd-pstate = amd_debug:amd_pstate
+
+[options.package_data]
+amd_debug = s2idle-hook
+amd_debug.templates = *
+amd_debug.bash = amd-s2idle
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

amd_debug_tools-0.2.0/src/amd_debug/__init__.py

@@ -0,0 +1,45 @@
+#!/usr/bin/python3
+# SPDX-License-Identifier: MIT
+
+
+def amd_s2idle():
+    """Launch the amd-s2idle tool."""
+    from . import s2idle  # pylint: disable=import-outside-toplevel
+
+    return s2idle.main()
+
+
+def amd_bios():
+    """Launch the amd-bios tool."""
+    from . import bios  # pylint: disable=import-outside-toplevel
+
+    return bios.main()
+
+
+def amd_pstate():
+    """Launch the amd-pstate tool."""
+    from . import pstate  # pylint: disable=import-outside-toplevel
+
+    return pstate.main()
+
+
+def install_dep_superset():
+    """Install all supserset dependencies."""
+    from . import installer  # pylint: disable=import-outside-toplevel
+
+    return installer.install_dep_superset()
+
+
+def launch_tool(tool_name):
+    """Launch a tool with the given name and arguments."""
+    tools = {
+        "amd_s2idle.py": amd_s2idle,
+        "amd_bios.py": amd_bios,
+        "amd_pstate.py": amd_pstate,
+        "install_deps.py": install_dep_superset,
+    }
+    if tool_name in tools:
+        return tools[tool_name]()
+    else:
+        print(f"\033[91mUnknown exe: {tool_name}\033[0m")
+        return False

amd_debug_tools-0.2.0/src/amd_debug/acpi.py

@@ -0,0 +1,107 @@
+#!/usr/bin/python3
+# SPDX-License-Identifier: MIT
+
+import os
+import logging
+from amd_debug.common import BIT, read_file
+
+ACPI_METHOD = "M460"
+
+
+def search_acpi_tables(pattern):
+    """Search for a pattern in ACPI tables"""
+    p = os.path.join("/", "sys", "firmware", "acpi", "tables")
+
+    for fn in os.listdir(p):
+        if not fn.startswith("SSDT") and not fn.startswith("DSDT"):
+            continue
+        fp = os.path.join(p, fn)
+        with open(fp, "rb") as file:
+            content = file.read()
+            if pattern.encode() in content:
+                return True
+    return False
+
+
+class AcpicaTracer:
+    """Class for ACPI tracing"""
+
+    def __init__(self):
+        self.acpi_base = os.path.join("/", "sys", "module", "acpi", "parameters")
+        keys = [
+            "trace_debug_layer",
+            "trace_debug_level",
+            "trace_method_name",
+            "trace_state",
+        ]
+        self.original = {}
+        self.supported = False
+        for key in keys:
+            fname = os.path.join(self.acpi_base, key)
+            if not os.path.exists(fname):
+                logging.debug("ACPI Notify() debugging not available")
+                return
+            v = read_file(fname)
+            if v and v != "(null)":
+                self.original[key] = v
+        self.supported = True
+
+    def _write_expected(self, expected):
+        for key, value in expected.items():
+            p = os.path.join(self.acpi_base, key)
+            if isinstance(value, int):
+                t = str(int(value))
+            else:
+                t = value
+            with open(p, "w", encoding="utf-8") as w:
+                w.write(t)
+
+    def trace_notify(self):
+        """Trace notify events"""
+        if not self.supported:
+            return False
+        expected = {
+            "trace_debug_layer": BIT(2),
+            "trace_debug_level": BIT(2),
+            "trace_state": "enable",
+        }
+        self._write_expected(expected)
+        logging.debug("Enabled ACPI debugging for ACPI_LV_INFO/ACPI_EVENTS")
+        return True
+
+    def trace_bios(self):
+        """Trace BIOS events"""
+        if not self.supported:
+            return False
+        if not search_acpi_tables(ACPI_METHOD):
+            logging.debug(
+                "will not work on this system: ACPI tables do not contain %s",
+                ACPI_METHOD,
+            )
+            return False
+        expected = {
+            "trace_debug_layer": BIT(7),
+            "trace_debug_level": BIT(4),
+            "trace_method_name": f"\\{ACPI_METHOD}",
+            "trace_state": "method",
+        }
+        self._write_expected(expected)
+        logging.debug("Enabled ACPI debugging for BIOS")
+        return True
+
+    def disable(self):
+        """Disable ACPI tracing"""
+        if not self.supported:
+            return False
+        expected = {
+            "trace_state": "disable",
+        }
+        self._write_expected(expected)
+        return True
+
+    def restore(self):
+        """Restore original ACPI tracing settings"""
+        if not self.supported:
+            return False
+        self._write_expected(self.original)
+        return True

amd_debug_tools-0.2.0/src/amd_debug/bash/amd-s2idle

@@ -0,0 +1,89 @@
+_cmd_list=(
+	'install'
+	'uninstall'
+	'test'
+	'report'
+	'version'
+)
+
+_general_opts=(
+)
+
+_report_opts=(
+	'--since'
+	'--until'
+	'--report-file'
+	'--format'
+	'--report-debug'
+)
+
+_test_opts=(
+	'--wait'
+	'--count'
+	'--duration'
+	'--report-file'
+	'--format'
+	'--force'
+	'--logind'
+	'--tool-debug'
+	'--report-debug'
+)
+
+_format_opts=(
+	'md'
+	'html'
+	'txt'
+)
+
+_show_test_opts()
+{
+	COMPREPLY+=( $(compgen -W '${_test_opts[@]}' -- "$cur") )
+}
+
+_show_report_opts()
+{
+	COMPREPLY+=( $(compgen -W '${_report_opts[@]}' -- "$cur") )
+}
+
+_show_format_completion()
+{
+	COMPREPLY+=( $(compgen -W '${_format_opts[@]}' -- "$cur") )
+}
+
+_amd_s2idle()
+{
+	local cur prev command arg args
+	COMPREPLY=()
+	_get_comp_words_by_ref cur prev
+	_get_first_arg
+	_count_args
+
+	case $prev in
+	--log|--duration|--count|--wait|--since|--report-file)
+		return 0
+		;;
+	--format)
+		_show_format_completion
+		return 0
+		;;
+	esac
+	case $arg in
+	test)
+		_show_test_opts
+		;;
+	report)
+		_show_report_opts
+		;;
+
+	*)
+		#find first command
+		if [[ "$args" = "1" ]]; then
+			COMPREPLY=( $(compgen -W '${_cmd_list[@]}' -- "$cur") )
+		fi
+		;;
+	esac
+
+	return 0
+}
+
+complete -F _amd_s2idle amd-s2idle