You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This repository hosts open tools that are useful for debugging issues on AMD systems.
6
6
7
7
## Installation
8
+
### Distro (Arch)
9
+
`amd-debug-tools` has been [packaged for Arch Linux](https://archlinux.org/packages/extra/any/amd-debug-tools/) (and derivatives). You can install it using:
10
+
11
+
pacman -Sy amd-debug-tools
12
+
13
+
### Using a python wheel (Generic)
8
14
It is suggested to install tools in a virtual environment either using
9
15
`pipx` or `python3 -m venv`.
10
16
11
-
### From PyPI
17
+
####From PyPI
12
18
`amd-debug-tools` is distributed as a python wheel, which is a
13
19
binary package format for Python. To install from PyPI, run the following
14
20
command:
@@ -31,130 +37,14 @@ to set up the environment:
31
37
32
38
This will add the `pipx` environment to your path.
33
39
34
-
### Running in tree
35
-
If you want to run the tools in tree, you need to make sure that distro dependencies
36
-
that would normally install into a venv are installed. This can be done by running:
37
-
38
-
./install_deps.py
39
-
40
-
After dependencies are installed, you can run the tools by running:
41
-
42
-
./amd_s2idle.py
43
-
./amd_bios.py
44
-
./amd_pstate.py
45
-
46
-
## amd-s2idle
47
-
`amd-s2idle` is a tool used for analyzing the entry and exit of the s2idle
48
-
state of a Linux system.
49
-
50
-
It is intended to use with Linux kernel 6.1 or later and works by hooking
51
-
into dynamic debugging messages and events that are generated by the kernel.
52
-
53
-
For analysis of power consumption issues it can be hooked into `systemd` to
54
-
run a command to capture data right before and after the system enters and
55
-
exits the s2idle state.
56
-
57
-
4 high level commands are supported.
58
-
59
-
### `amd-s2idle install`
60
-
This will install the systemd hook so that data will be captured before and
61
-
after the system enters and exits the s2idle state.
62
-
63
-
This will also install a bash completion script that can be used for other
64
-
commands.
65
-
66
-
**NOTE:** This command is only supported when run from a venv.
67
-
68
-
### `amd-s2idle uninstall`
69
-
This will uninstall the systemd hook and remove the bash completion script.
70
-
71
-
**NOTE:** This command is only supported when run from a venv.
72
-
73
-
### `amd-s2idle test`
74
-
This will run a suspend cycle with a timer based wakeup and capture relevant
75
-
data into a database and produce a report. This can also be used to run multiple cycles.
76
-
77
-
The following optional arguments are supported for this command:
78
-
79
-
--count COUNT Number of cycles to run
80
-
--duration DURATION Duration of the cycle in seconds
81
-
--wait WAIT Time to wait before starting the cycle in seconds
82
-
--format FORMAT Format of the report to produce (html, txt or md)
83
-
--report-file File to write the report to
84
-
--force Run a test cycle even if the system fails to pass prerequisite checks
85
-
--random Run sleep cycles for random durations and waits, using the --duration and --wait arguments as an upper bound
86
-
--logind Use logind to suspend the system
87
-
--tool-debug Enable debug logging
88
-
--bios-debug Enable BIOS debug logging instead of notify logging
89
-
90
-
If the tool is launched with an environment that can call `xdg-open`, the report
91
-
will be opened in a browser.
92
-
93
-
### `amd-s2idle report`
94
-
This will produce a report from the data captured by the `test` command
95
-
and/or from the systemd hook. The report will default to 60 days of data.
96
-
97
-
The following optional arguments are supported for this command:
98
-
99
-
--since SINCE Date to start the report from
100
-
--until UNTIL Date to end the report at
101
-
--format FORMAT Format of the report to produce (html, txt or md)
102
-
--report-file File to write the report to
103
-
--tool-debug Enable tool debug logging
104
-
--report-debug
105
-
--no-report-debug
106
-
Include debug messages in report (WARNING: can significantly increase report size)
107
-
If the tool is launched with an environment that can call `xdg-open`, the report
108
-
will be opened in a browser.
109
-
110
-
### `amd-s2idle --version`
111
-
This will print the version of the tool and exit.
112
-
113
-
### Debug output
114
-
All commands support the `--tool-debug` argument which will enable extra debug output. This is often needed for debugging issues with a particular cycle.
115
-
116
-
**NOTE:** enabling debug output significantly increases the size of the report.
117
-
It's suggested that you use `--since` and `--until` to focus on the cycles that you are interested in.
118
-
119
-
## amd-bios
120
-
`amd-bios` is a a tool that can be used to enable or disable BIOS AML debug logging
121
-
-and to parse a kernel log that contains BIOS logs.
122
-
123
-
### `amd-bios trace`
124
-
Modify BIOS AML trace debug logging.
125
-
126
-
One of the following arguments must be set for this command:
127
-
128
-
--enable Enable BIOS AML tracing
129
-
--disable Disable BIOS AML tracing
130
-
131
-
The following optional arguments are supported for this command:
132
-
133
-
--tool-debug Enable tool debug logging
134
-
135
-
### `amd-bios parse`
136
-
Parses a kernel log that contains BIOS AML debug logging and produces a report.
137
-
138
-
The following optional arguments are supported for this command:
139
-
140
-
--input INPUT Optional input file to parse
141
-
--tool-debug Enable tool debug logging
142
-
143
-
### `amd-bios --version`
144
-
This will print the version of the tool and exit.
145
-
146
-
## amd-pstate
147
-
`amd-pstate` is a tool used for identification of issues with amd-pstate.
148
-
It will capture some state from the system as well as from the machine specific registers that
149
-
amd-pstate uses.
150
-
151
-
## amd-ttm
152
-
`amd-ttm` is a tool used for managing the TTM memory settings on AMD systems.
40
+
## Running in-tree
41
+
Documentation about running directly from a git checkout is available [here](docs/in-tree.md).
153
42
154
-
## Compatibility scripts
43
+
## Tools
155
44
156
-
Compatibility scripts are provided for the previous names the tools went by:
157
-
`amd_s2idle.py`, `amd_bios.py` and `amd_pstate.py`.
158
-
These allow cloning the repository and running the scripts without installing
159
-
the package.
45
+
Each tool has its own individual documentation page:
`amd-s2idle` is a tool used for analyzing the entry and exit of the s2idle
4
+
state of a Linux system.
5
+
6
+
It is intended to use with Linux kernel 6.1 or later and works by hooking
7
+
into dynamic debugging messages and events that are generated by the kernel.
8
+
9
+
For analysis of power consumption issues it can be hooked into `systemd` to
10
+
run a command to capture data right before and after the system enters and
11
+
exits the s2idle state.
12
+
13
+
4 high level commands are supported.
14
+
15
+
## `amd-s2idle install`
16
+
This will install the systemd hook so that data will be captured before and
17
+
after the system enters and exits the s2idle state.
18
+
19
+
This will also install a bash completion script that can be used for other
20
+
commands.
21
+
22
+
**NOTE:** This command is only supported when run from a venv.
23
+
24
+
## `amd-s2idle uninstall`
25
+
This will uninstall the systemd hook and remove the bash completion script.
26
+
27
+
**NOTE:** This command is only supported when run from a venv.
28
+
29
+
## `amd-s2idle test`
30
+
This will run a suspend cycle with a timer based wakeup and capture relevant
31
+
data into a database and produce a report. This can also be used to run multiple cycles.
32
+
33
+
The following optional arguments are supported for this command:
34
+
35
+
--count COUNT Number of cycles to run
36
+
--duration DURATION Duration of the cycle in seconds
37
+
--wait WAIT Time to wait before starting the cycle in seconds
38
+
--format FORMAT Format of the report to produce (html, txt or md)
39
+
--report-file File to write the report to
40
+
--force Run a test cycle even if the system fails to pass prerequisite checks
41
+
--random Run sleep cycles for random durations and waits, using the --duration and --wait arguments as an upper bound
42
+
--logind Use logind to suspend the system
43
+
--tool-debug Enable debug logging
44
+
--bios-debug Enable BIOS debug logging instead of notify logging
45
+
46
+
If the tool is launched with an environment that can call `xdg-open`, the report
47
+
will be opened in a browser.
48
+
49
+
## `amd-s2idle report`
50
+
This will produce a report from the data captured by the `test` command
51
+
and/or from the systemd hook. The report will default to 60 days of data.
52
+
53
+
The following optional arguments are supported for this command:
54
+
55
+
--since SINCE Date to start the report from
56
+
--until UNTIL Date to end the report at
57
+
--format FORMAT Format of the report to produce (html, txt or md)
58
+
--report-file File to write the report to
59
+
--tool-debug Enable tool debug logging
60
+
--report-debug
61
+
--no-report-debug
62
+
Include debug messages in report (WARNING: can significantly increase report size)
63
+
If the tool is launched with an environment that can call `xdg-open`, the report
64
+
will be opened in a browser.
65
+
66
+
## `amd-s2idle --version`
67
+
This will print the version of the tool and exit.
68
+
69
+
## Debug output
70
+
All commands support the `--tool-debug` argument which will enable extra debug output. This is often needed for debugging issues with a particular cycle.
71
+
72
+
**NOTE:** enabling debug output significantly increases the size of the report.
73
+
It's suggested that you use `--since` and `--until` to focus on the cycles that you are interested in.
`amd-ttm` is a tool used for managing the TTM memory settings on AMD systems.
3
+
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`.
4
+
5
+
## Querying current TTM settings
6
+
Running the tool with no arguments will display the current TTM settings.
7
+
8
+
```
9
+
❯ amd-ttm
10
+
💻 Current TTM pages limit: 16469033 pages (62.82 GB)
11
+
💻 Total system memory: 125.65 GB
12
+
```
13
+
14
+
## Setting new TTM value
15
+
Setting a new TTM page size is done by using the `--set` argument with the new limit (in GB).
16
+
The system must be rebooted for it to take effect and you will be prompted to do this automatically.
17
+
18
+
```
19
+
❯ amd-ttm --set 100
20
+
🐧 Successfully set TTM pages limit to 26214400 pages (100.00 GB)
21
+
🐧 Configuration written to /etc/modprobe.d/ttm.conf
22
+
○ NOTE: You need to reboot for changes to take effect.
23
+
Would you like to reboot the system now? (y/n): y
24
+
```
25
+
26
+
## Clearing the TTM value
27
+
To revert back to the kernel defaults, run the tool with the `--clear` argument.
28
+
The system must be rebooted for it to take effect and you will be prompted to do this automatically.
29
+
The kernel default (at the time of writing) is system memory / 2.
0 commit comments