amd-debug-tools 0.2.9__tar.gz → 0.2.10__tar.gz

amd_debug_tools-0.2.10/.github/workflows/ci.yml

@@ -0,0 +1,117 @@
+name: CI
+on:
+  push:
+  pull_request:
+  workflow_run:
+    workflows: ["mirror"]
+    types:
+      - completed
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - name: Build release distributions
+        run: |
+          python -m pip install build
+          python -m build
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: >-
+      Publish Python 🐍 distribution 📦 to PyPI
+    if: startsWith(github.ref, 'refs/tags/')
+    needs:
+    - build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/amd-debug-tools
+    permissions:
+      id-token: write
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Publish distribution 📦 to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: >-
+      Sign the Python 🐍 distribution 📦 with Sigstore
+      and upload them to GitHub Release
+    needs:
+    - publish-to-pypi
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write  # IMPORTANT: mandatory for making GitHub Releases
+      id-token: write  # IMPORTANT: mandatory for sigstore
+
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Sign the dists with Sigstore
+      uses: sigstore/gh-action-sigstore-python@v3.0.0
+      with:
+        inputs: >-
+          ./dist/*.tar.gz
+          ./dist/*.whl
+    - name: Create GitHub Release
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      run: >-
+        gh release create
+        "$GITHUB_REF_NAME"
+        --repo "$GITHUB_REPOSITORY"
+        --notes ""
+    - name: Upload artifact signatures to GitHub Release
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      # Upload to GitHub Release using the `gh` CLI.
+      # `dist/` contains the built packages, and the
+      # sigstore-produced signatures and certificates.
+      run: >-
+        gh release upload
+        "$GITHUB_REF_NAME" dist/**
+        --repo "$GITHUB_REPOSITORY"
+
+  coverage:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
+      with:
+        python-version: "3.x"
+    - name: install apt deps
+      run: |
+        sudo apt install libsystemd-dev -y
+    - name: install deps
+      run: |
+        pip install .
+    - name: Generate Report
+      run: |
+        pip install pytest-cov
+        pytest --cov --junitxml=junit.xml
+    - name: Upload coverage reports to Codecov
+      uses: codecov/codecov-action@v5
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
+    - name: Upload test results to Codecov
+      if: ${{ !cancelled() }}
+      uses: codecov/test-results-action@v1
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}

amd_debug_tools-0.2.10/.github/workflows/mirror.yml

@@ -0,0 +1,24 @@
+name: 'mirror'
+on:
+  push:
+    branches:
+        - __mirror
+  schedule:
+    # Run everyday at 3 AM UTC
+    - cron: '0 3 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  mirror:
+    runs-on: ubuntu-latest
+    name: mirror
+    steps:
+      - name: mirror
+        id: mirror
+        uses: bridgelightcloud/github-mirror-action@v3
+        with:
+          origin: git://git.kernel.org/pub/scm/linux/kernel/git/superm1/amd-debug-tools.git
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

amd_debug_tools-0.2.10/.gitignore

@@ -0,0 +1,11 @@
+/.vscode
+*.txt
+__pycache__
+amd*.egg-info
+build
+dist
+amd*.md
+*.html
+deb_dist/
+*.tar.gz
+.coverage

amd_debug_tools-0.2.10/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+default_stages: [pre-commit]
+repos:
+-   repo: https://github.com/ambv/black
+    rev: 25.1.0
+    hooks:
+    - id: black
+      exclude_types: [symlink]

amd_debug_tools-0.2.10/.vscode/settings.json

@@ -0,0 +1,129 @@
+{
+        "cSpell.words": [
+                "abled",
+                "acpica",
+                "alarmtimer",
+                "ASIC",
+                "aspm",
+                "ASPM",
+                "asus",
+                "ASUS",
+                "cmos",
+                "CPPC",
+                "cpuid",
+                "cpuidle",
+                "cpus",
+                "crashkernel",
+                "cryptdevice",
+                "cryptkey",
+                "cstates",
+                "cysystemd",
+                "dbus",
+                "dmar",
+                "dmcub",
+                "Dmcub",
+                "DMCUB",
+                "DMUB",
+                "dpia",
+                "DPIA",
+                "DSDT",
+                "earlycon",
+                "earlyprintk",
+                "edid",
+                "edids",
+                "ENDC",
+                "ertm",
+                "evmisc",
+                "FACP",
+                "geteuid",
+                "gobject",
+                "gpiolib",
+                "gpios",
+                "guids",
+                "hpet",
+                "HPET",
+                "hsmp",
+                "Hsmp",
+                "HSMP",
+                "hwirq",
+                "hwsleep",
+                "Iasl",
+                "idlemask",
+                "Iommu",
+                "irqs",
+                "IVRS",
+                "kconfig",
+                "klass",
+                "kmajor",
+                "kminor",
+                "kwin",
+                "levelname",
+                "logf",
+                "logind",
+                "luks",
+                "minv",
+                "modalias",
+                "netdev",
+                "netroot",
+                "nfsaddrs",
+                "nfsroot",
+                "noplymouth",
+                "notsupported",
+                "nowatchdog",
+                "ostree",
+                "powerprofilesctl",
+                "powersave",
+                "ppfeaturemask",
+                "prefcore",
+                "prereq",
+                "propf",
+                "reques",
+                "resumeflags",
+                "rhgb",
+                "rootflags",
+                "rootfstype",
+                "roothash",
+                "sadm",
+                "seeked",
+                "showopts",
+                "sscanf",
+                "SSDT",
+                "subleaf",
+                "sysfs",
+                "tmpd",
+                "UBTC",
+                "uefi",
+                "uevent",
+                "Unserviced",
+                "usec",
+                "userspace",
+                "usrflags",
+                "usrfstype",
+                "virt",
+                "wakealarm",
+                "xhci",
+                "Xhci",
+                "zswap"
+        ],
+        "python.testing.unittestArgs": [
+                "-v",
+                "-s",
+                "./src",
+                "-p",
+                "test_*.py"
+        ],
+        "python.testing.pytestEnabled": true,
+        "python.testing.unittestEnabled": false,
+        "cSpell.ignoreWords": [
+                "barplot",
+                "intf",
+                "line",
+                "message",
+                "showindex",
+                "tablefmt",
+                "xlabel",
+                "xticks",
+                "ylabel",
+                "yscale"
+        ]
+}

amd_debug_tools-0.2.10/Makefile

@@ -0,0 +1,9 @@
+build:
+	python3 -m build
+check:
+	pytest
+coverage:
+	coverage run -m unittest
+	coverage report
+clean:
+	rm -rf build src/*.egg-info build dist amd*.txt amd*md amd*html

{amd_debug_tools-0.2.9/src/amd_debug_tools.egg-info → amd_debug_tools-0.2.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: amd-debug-tools
-Version: 0.2.9
+Version: 0.2.10
 Summary: debug tools for AMD systems
 Author-email: Mario Limonciello <superm1@kernel.org>
 License-Expression: MIT

amd_debug_tools-0.2.10/amd_pstate.py

@@ -0,0 +1,34 @@
+#!/usr/bin/python3
+# SPDX-License-Identifier: MIT
+"""
+This module is a launcher for the AMD Debug Tools package. It is meant for
+launching various tools within the package without installation.
+"""
+
+import sys
+import os
+
+URL = "git://git.kernel.org/pub/scm/linux/kernel/git/superm1/amd-debug-tools.git"
+try:
+    import amd_debug
+    from amd_debug.common import fatal_error
+except ModuleNotFoundError:
+    sys.exit(
+        f"\033[91m{sys.argv[0]} can not be run standalone.\n"
+        f"\033[0m\033[94mCheck out the full branch from {URL}\033[0m"
+    )
+
+
+def main():
+    """Main function to launch the appropriate tool based on the script name."""
+    try:
+        return amd_debug.launch_tool(os.path.basename(sys.argv[0]))
+    except ModuleNotFoundError as e:
+        fatal_error(
+            f"Missing dependency: {e}\n"
+            f"Run ./install_deps.py to install dependencies."
+        )
+
+
+if __name__ == "__main__":
+    sys.exit(main())

amd_debug_tools-0.2.10/amd_s2idle.py

@@ -0,0 +1,34 @@
+#!/usr/bin/python3
+# SPDX-License-Identifier: MIT
+"""
+This module is a launcher for the AMD Debug Tools package. It is meant for
+launching various tools within the package without installation.
+"""
+
+import sys
+import os
+
+URL = "git://git.kernel.org/pub/scm/linux/kernel/git/superm1/amd-debug-tools.git"
+try:
+    import amd_debug
+    from amd_debug.common import fatal_error
+except ModuleNotFoundError:
+    sys.exit(
+        f"\033[91m{sys.argv[0]} can not be run standalone.\n"
+        f"\033[0m\033[94mCheck out the full branch from {URL}\033[0m"
+    )
+
+
+def main():
+    """Main function to launch the appropriate tool based on the script name."""
+    try:
+        return amd_debug.launch_tool(os.path.basename(sys.argv[0]))
+    except ModuleNotFoundError as e:
+        fatal_error(
+            f"Missing dependency: {e}\n"
+            f"Run ./install_deps.py to install dependencies."
+        )
+
+
+if __name__ == "__main__":
+    sys.exit(main())

amd_debug_tools-0.2.10/amd_ttm.py

@@ -0,0 +1,34 @@
+#!/usr/bin/python3
+# SPDX-License-Identifier: MIT
+"""
+This module is a launcher for the AMD Debug Tools package. It is meant for
+launching various tools within the package without installation.
+"""
+
+import sys
+import os
+
+URL = "git://git.kernel.org/pub/scm/linux/kernel/git/superm1/amd-debug-tools.git"
+try:
+    import amd_debug
+    from amd_debug.common import fatal_error
+except ModuleNotFoundError:
+    sys.exit(
+        f"\033[91m{sys.argv[0]} can not be run standalone.\n"
+        f"\033[0m\033[94mCheck out the full branch from {URL}\033[0m"
+    )
+
+
+def main():
+    """Main function to launch the appropriate tool based on the script name."""
+    try:
+        return amd_debug.launch_tool(os.path.basename(sys.argv[0]))
+    except ModuleNotFoundError as e:
+        fatal_error(
+            f"Missing dependency: {e}\n"
+            f"Run ./install_deps.py to install dependencies."
+        )
+
+
+if __name__ == "__main__":
+    sys.exit(main())

amd_debug_tools-0.2.10/docs/amd-bios.md

@@ -0,0 +1,26 @@
+# BIOS log parser
+`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_debug_tools-0.2.10/docs/amd-pstate.md

@@ -0,0 +1,4 @@
+# AMD P-State issue triage tool
+`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.

amd_debug_tools-0.2.10/docs/amd-s2idle.md

@@ -0,0 +1,73 @@
+# s2idle debugging tool
+
+`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
+        --no-report-debug
+                              Include debug messages in report (WARNING: can significantly increase report size)
+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_debug_tools-0.2.10/docs/amd-ttm.md

@@ -0,0 +1,35 @@
+# Translation Table Manager (TTM) page setting tool
+`amd-ttm` is a tool used for managing the TTM memory settings on AMD systems.
+It manipulates the amount of memory allocated for the TTM. This amount can be increased or decreased by changing the kernel’s Translation Table Manager (TTM) page setting available at `/sys/module/ttm/parameters/pages_limit`.
+
+## Querying current TTM settings
+Running the tool with no arguments will display the current TTM settings.
+
+```
+❯ amd-ttm
+💻 Current TTM pages limit: 16469033 pages (62.82 GB)
+💻 Total system memory: 125.65 GB
+```
+
+## Setting new TTM value
+Setting a new TTM page size is done by using the `--set` argument with the new limit (in GB).
+The system must be rebooted for it to take effect and you will be prompted to do this automatically.
+
+```
+❯ amd-ttm --set 100
+🐧 Successfully set TTM pages limit to 26214400 pages (100.00 GB)
+🐧 Configuration written to /etc/modprobe.d/ttm.conf
+○ NOTE: You need to reboot for changes to take effect.
+Would you like to reboot the system now? (y/n): y
+```
+
+## Clearing the TTM value
+To revert back to the kernel defaults, run the tool with the `--clear` argument.
+The system must be rebooted for it to take effect and you will be prompted to do this automatically.
+The kernel default (at the time of writing) is system memory / 2.
+
+```
+❯ amd-ttm --clear
+🐧 Configuration /etc/modprobe.d/ttm.conf removed
+Would you like to reboot the system now? (y/n): y
+```

amd_debug_tools-0.2.10/docs/in-tree.md

@@ -0,0 +1,12 @@
+# 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_ttm.py

amd_debug_tools-0.2.10/install_deps.py

@@ -0,0 +1,34 @@
+#!/usr/bin/python3
+# SPDX-License-Identifier: MIT
+"""
+This module is a launcher for the AMD Debug Tools package. It is meant for
+launching various tools within the package without installation.
+"""
+
+import sys
+import os
+
+URL = "git://git.kernel.org/pub/scm/linux/kernel/git/superm1/amd-debug-tools.git"
+try:
+    import amd_debug
+    from amd_debug.common import fatal_error
+except ModuleNotFoundError:
+    sys.exit(
+        f"\033[91m{sys.argv[0]} can not be run standalone.\n"
+        f"\033[0m\033[94mCheck out the full branch from {URL}\033[0m"
+    )
+
+
+def main():
+    """Main function to launch the appropriate tool based on the script name."""
+    try:
+        return amd_debug.launch_tool(os.path.basename(sys.argv[0]))
+    except ModuleNotFoundError as e:
+        fatal_error(
+            f"Missing dependency: {e}\n"
+            f"Run ./install_deps.py to install dependencies."
+        )
+
+
+if __name__ == "__main__":
+    sys.exit(main())