1.. SPDX-License-Identifier: GPL-2.0
2.. include:: <isonum.txt>
3
4===============================================
5``amd-pstate`` CPU Performance Scaling Driver
6===============================================
7
8:Copyright: |copy| 2021 Advanced Micro Devices, Inc.
9
10:Author: Huang Rui <ray.huang@amd.com>
11
12
13Introduction
14===================
15
16``amd-pstate`` is the AMD CPU performance scaling driver that introduces a
17new CPU frequency control mechanism on modern AMD APU and CPU series in
18Linux kernel. The new mechanism is based on Collaborative Processor
19Performance Control (CPPC) which provides finer grain frequency management
20than legacy ACPI hardware P-States. Current AMD CPU/APU platforms are using
21the ACPI P-states driver to manage CPU frequency and clocks with switching
22only in 3 P-states. CPPC replaces the ACPI P-states controls and allows a
23flexible, low-latency interface for the Linux kernel to directly
24communicate the performance hints to hardware.
25
26``amd-pstate`` leverages the Linux kernel governors such as ``schedutil``,
27``ondemand``, etc. to manage the performance hints which are provided by
28CPPC hardware functionality that internally follows the hardware
29specification (for details refer to AMD64 Architecture Programmer's Manual
30Volume 2: System Programming [1]_). Currently, ``amd-pstate`` supports basic
31frequency control function according to kernel governors on some of the
32Zen2 and Zen3 processors, and we will implement more AMD specific functions
33in future after we verify them on the hardware and SBIOS.
34
35
36AMD CPPC Overview
37=======================
38
39Collaborative Processor Performance Control (CPPC) interface enumerates a
40continuous, abstract, and unit-less performance value in a scale that is
41not tied to a specific performance state / frequency. This is an ACPI
42standard [2]_ which software can specify application performance goals and
43hints as a relative target to the infrastructure limits. AMD processors
44provide the low latency register model (MSR) instead of an AML code
45interpreter for performance adjustments. ``amd-pstate`` will initialize a
46``struct cpufreq_driver`` instance, ``amd_pstate_driver``, with the callbacks
47to manage each performance update behavior. ::
48
49 Highest Perf ------>+-----------------------+                         +-----------------------+
50                     |                       |                         |                       |
51                     |                       |                         |                       |
52                     |                       |          Max Perf  ---->|                       |
53                     |                       |                         |                       |
54                     |                       |                         |                       |
55 Nominal Perf ------>+-----------------------+                         +-----------------------+
56                     |                       |                         |                       |
57                     |                       |                         |                       |
58                     |                       |                         |                       |
59                     |                       |                         |                       |
60                     |                       |                         |                       |
61                     |                       |                         |                       |
62                     |                       |      Desired Perf  ---->|                       |
63                     |                       |                         |                       |
64                     |                       |                         |                       |
65                     |                       |                         |                       |
66                     |                       |                         |                       |
67                     |                       |                         |                       |
68                     |                       |                         |                       |
69                     |                       |                         |                       |
70                     |                       |                         |                       |
71                     |                       |                         |                       |
72  Lowest non-        |                       |                         |                       |
73  linear perf ------>+-----------------------+                         +-----------------------+
74                     |                       |                         |                       |
75                     |                       |       Lowest perf  ---->|                       |
76                     |                       |                         |                       |
77  Lowest perf ------>+-----------------------+                         +-----------------------+
78                     |                       |                         |                       |
79                     |                       |                         |                       |
80                     |                       |                         |                       |
81          0   ------>+-----------------------+                         +-----------------------+
82
83                                     AMD P-States Performance Scale
84
85
86.. _perf_cap:
87
88AMD CPPC Performance Capability
89--------------------------------
90
91Highest Performance (RO)
92.........................
93
94This is the absolute maximum performance an individual processor may reach,
95assuming ideal conditions. This performance level may not be sustainable
96for long durations and may only be achievable if other platform components
97are in a specific state; for example, it may require other processors to be in
98an idle state. This would be equivalent to the highest frequencies
99supported by the processor.
100
101Nominal (Guaranteed) Performance (RO)
102......................................
103
104This is the maximum sustained performance level of the processor, assuming
105ideal operating conditions. In the absence of an external constraint (power,
106thermal, etc.), this is the performance level the processor is expected to
107be able to maintain continuously. All cores/processors are expected to be
108able to sustain their nominal performance state simultaneously.
109
110Lowest non-linear Performance (RO)
111...................................
112
113This is the lowest performance level at which nonlinear power savings are
114achieved, for example, due to the combined effects of voltage and frequency
115scaling. Above this threshold, lower performance levels should be generally
116more energy efficient than higher performance levels. This register
117effectively conveys the most efficient performance level to ``amd-pstate``.
118
119Lowest Performance (RO)
120........................
121
122This is the absolute lowest performance level of the processor. Selecting a
123performance level lower than the lowest nonlinear performance level may
124cause an efficiency penalty but should reduce the instantaneous power
125consumption of the processor.
126
127AMD CPPC Performance Control
128------------------------------
129
130``amd-pstate`` passes performance goals through these registers. The
131register drives the behavior of the desired performance target.
132
133Minimum requested performance (RW)
134...................................
135
136``amd-pstate`` specifies the minimum allowed performance level.
137
138Maximum requested performance (RW)
139...................................
140
141``amd-pstate`` specifies a limit the maximum performance that is expected
142to be supplied by the hardware.
143
144Desired performance target (RW)
145...................................
146
147``amd-pstate`` specifies a desired target in the CPPC performance scale as
148a relative number. This can be expressed as percentage of nominal
149performance (infrastructure max). Below the nominal sustained performance
150level, desired performance expresses the average performance level of the
151processor subject to hardware. Above the nominal performance level,
152the processor must provide at least nominal performance requested and go higher
153if current operating conditions allow.
154
155Energy Performance Preference (EPP) (RW)
156.........................................
157
158This attribute provides a hint to the hardware if software wants to bias
159toward performance (0x0) or energy efficiency (0xff).
160
161
162Key Governors Support
163=======================
164
165``amd-pstate`` can be used with all the (generic) scaling governors listed
166by the ``scaling_available_governors`` policy attribute in ``sysfs``. Then,
167it is responsible for the configuration of policy objects corresponding to
168CPUs and provides the ``CPUFreq`` core (and the scaling governors attached
169to the policy objects) with accurate information on the maximum and minimum
170operating frequencies supported by the hardware. Users can check the
171``scaling_cur_freq`` information comes from the ``CPUFreq`` core.
172
173``amd-pstate`` mainly supports ``schedutil`` and ``ondemand`` for dynamic
174frequency control. It is to fine tune the processor configuration on
175``amd-pstate`` to the ``schedutil`` with CPU CFS scheduler. ``amd-pstate``
176registers the adjust_perf callback to implement performance update behavior
177similar to CPPC. It is initialized by ``sugov_start`` and then populates the
178CPU's update_util_data pointer to assign ``sugov_update_single_perf`` as the
179utilization update callback function in the CPU scheduler. The CPU scheduler
180will call ``cpufreq_update_util`` and assigns the target performance according
181to the ``struct sugov_cpu`` that the utilization update belongs to.
182Then, ``amd-pstate`` updates the desired performance according to the CPU
183scheduler assigned.
184
185.. _processor_support:
186
187Processor Support
188=======================
189
190The ``amd-pstate`` initialization will fail if the ``_CPC`` entry in the ACPI
191SBIOS does not exist in the detected processor. It uses ``acpi_cpc_valid``
192to check the existence of ``_CPC``. All Zen based processors support the legacy
193ACPI hardware P-States function, so when ``amd-pstate`` fails initialization,
194the kernel will fall back to initialize the ``acpi-cpufreq`` driver.
195
196There are two types of hardware implementations for ``amd-pstate``: one is
197`Full MSR Support <perf_cap_>`_ and another is `Shared Memory Support
198<perf_cap_>`_. It can use the :c:macro:`X86_FEATURE_CPPC` feature flag to
199indicate the different types. (For details, refer to the Processor Programming
200Reference (PPR) for AMD Family 19h Model 51h, Revision A1 Processors [3]_.)
201``amd-pstate`` is to register different ``static_call`` instances for different
202hardware implementations.
203
204Currently, some of the Zen2 and Zen3 processors support ``amd-pstate``. In the
205future, it will be supported on more and more AMD processors.
206
207Full MSR Support
208-----------------
209
210Some new Zen3 processors such as Cezanne provide the MSR registers directly
211while the :c:macro:`X86_FEATURE_CPPC` CPU feature flag is set.
212``amd-pstate`` can handle the MSR register to implement the fast switch
213function in ``CPUFreq`` that can reduce the latency of frequency control in
214interrupt context. The functions with a ``pstate_xxx`` prefix represent the
215operations on MSR registers.
216
217Shared Memory Support
218----------------------
219
220If the :c:macro:`X86_FEATURE_CPPC` CPU feature flag is not set, the
221processor supports the shared memory solution. In this case, ``amd-pstate``
222uses the ``cppc_acpi`` helper methods to implement the callback functions
223that are defined on ``static_call``. The functions with the ``cppc_xxx`` prefix
224represent the operations of ACPI CPPC helpers for the shared memory solution.
225
226
227AMD P-States and ACPI hardware P-States always can be supported in one
228processor. But AMD P-States has the higher priority and if it is enabled
229with :c:macro:`MSR_AMD_CPPC_ENABLE` or ``cppc_set_enable``, it will respond
230to the request from AMD P-States.
231
232
233User Space Interface in ``sysfs`` - Per-policy control
234======================================================
235
236``amd-pstate`` exposes several global attributes (files) in ``sysfs`` to
237control its functionality at the system level. They are located in the
238``/sys/devices/system/cpu/cpufreq/policyX/`` directory and affect all CPUs. ::
239
240 root@hr-test1:/home/ray# ls /sys/devices/system/cpu/cpufreq/policy0/*amd*
241 /sys/devices/system/cpu/cpufreq/policy0/amd_pstate_highest_perf
242 /sys/devices/system/cpu/cpufreq/policy0/amd_pstate_lowest_nonlinear_freq
243 /sys/devices/system/cpu/cpufreq/policy0/amd_pstate_max_freq
244
245
246``amd_pstate_highest_perf / amd_pstate_max_freq``
247
248Maximum CPPC performance and CPU frequency that the driver is allowed to
249set, in percent of the maximum supported CPPC performance level (the highest
250performance supported in `AMD CPPC Performance Capability <perf_cap_>`_).
251In some ASICs, the highest CPPC performance is not the one in the ``_CPC``
252table, so we need to expose it to sysfs. If boost is not active, but
253still supported, this maximum frequency will be larger than the one in
254``cpuinfo``.
255This attribute is read-only.
256
257``amd_pstate_lowest_nonlinear_freq``
258
259The lowest non-linear CPPC CPU frequency that the driver is allowed to set,
260in percent of the maximum supported CPPC performance level. (Please see the
261lowest non-linear performance in `AMD CPPC Performance Capability
262<perf_cap_>`_.)
263This attribute is read-only.
264
265``energy_performance_available_preferences``
266
267A list of all the supported EPP preferences that could be used for
268``energy_performance_preference`` on this system.
269These profiles represent different hints that are provided
270to the low-level firmware about the user's desired energy vs efficiency
271tradeoff.  ``default`` represents the epp value is set by platform
272firmware. This attribute is read-only.
273
274``energy_performance_preference``
275
276The current energy performance preference can be read from this attribute.
277and user can change current preference according to energy or performance needs
278Please get all support profiles list from
279``energy_performance_available_preferences`` attribute, all the profiles are
280integer values defined between 0 to 255 when EPP feature is enabled by platform
281firmware, if EPP feature is disabled, driver will ignore the written value
282This attribute is read-write.
283
284Other performance and frequency values can be read back from
285``/sys/devices/system/cpu/cpuX/acpi_cppc/``, see :ref:`cppc_sysfs`.
286
287
288``amd-pstate`` vs ``acpi-cpufreq``
289======================================
290
291On the majority of AMD platforms supported by ``acpi-cpufreq``, the ACPI tables
292provided by the platform firmware are used for CPU performance scaling, but
293only provide 3 P-states on AMD processors.
294However, on modern AMD APU and CPU series, hardware provides the Collaborative
295Processor Performance Control according to the ACPI protocol and customizes this
296for AMD platforms. That is, fine-grained and continuous frequency ranges
297instead of the legacy hardware P-states. ``amd-pstate`` is the kernel
298module which supports the new AMD P-States mechanism on most of the future AMD
299platforms. The AMD P-States mechanism is the more performance and energy
300efficiency frequency management method on AMD processors.
301
302
303AMD Pstate Driver Operation Modes
304=================================
305
306``amd_pstate`` CPPC has two operation modes: CPPC Autonomous(active) mode and
307CPPC non-autonomous(passive) mode.
308active mode and passive mode can be chosen by different kernel parameters.
309When in Autonomous mode, CPPC ignores requests done in the Desired Performance
310Target register and takes into account only the values set to the Minimum requested
311performance, Maximum requested performance, and Energy Performance Preference
312registers. When Autonomous is disabled, it only considers the Desired Performance Target.
313
314Active Mode
315------------
316
317``amd_pstate=active``
318
319This is the low-level firmware control mode which is implemented by ``amd_pstate_epp``
320driver with ``amd_pstate=active`` passed to the kernel in the command line.
321In this mode, ``amd_pstate_epp`` driver provides a hint to the hardware if software
322wants to bias toward performance (0x0) or energy efficiency (0xff) to the CPPC firmware.
323then CPPC power algorithm will calculate the runtime workload and adjust the realtime
324cores frequency according to the power supply and thermal, core voltage and some other
325hardware conditions.
326
327Passive Mode
328------------
329
330``amd_pstate=passive``
331
332It will be enabled if the ``amd_pstate=passive`` is passed to the kernel in the command line.
333In this mode, ``amd_pstate`` driver software specifies a desired QoS target in the CPPC
334performance scale as a relative number. This can be expressed as percentage of nominal
335performance (infrastructure max). Below the nominal sustained performance level,
336desired performance expresses the average performance level of the processor subject
337to the Performance Reduction Tolerance register. Above the nominal performance level,
338processor must provide at least nominal performance requested and go higher if current
339operating conditions allow.
340
341
342User Space Interface in ``sysfs`` - General
343===========================================
344
345Global Attributes
346-----------------
347
348``amd-pstate`` exposes several global attributes (files) in ``sysfs`` to
349control its functionality at the system level.  They are located in the
350``/sys/devices/system/cpu/amd-pstate/`` directory and affect all CPUs.
351
352``status``
353	Operation mode of the driver: "active", "passive" or "disable".
354
355	"active"
356		The driver is functional and in the ``active mode``
357
358	"passive"
359		The driver is functional and in the ``passive mode``
360
361	"disable"
362		The driver is unregistered and not functional now.
363
364        This attribute can be written to in order to change the driver's
365        operation mode or to unregister it.  The string written to it must be
366        one of the possible values of it and, if successful, writing one of
367        these values to the sysfs file will cause the driver to switch over
368        to the operation mode represented by that string - or to be
369        unregistered in the "disable" case.
370
371``cpupower`` tool support for ``amd-pstate``
372===============================================
373
374``amd-pstate`` is supported by the ``cpupower`` tool, which can be used to dump
375frequency information. Development is in progress to support more and more
376operations for the new ``amd-pstate`` module with this tool. ::
377
378 root@hr-test1:/home/ray# cpupower frequency-info
379 analyzing CPU 0:
380   driver: amd-pstate
381   CPUs which run at the same hardware frequency: 0
382   CPUs which need to have their frequency coordinated by software: 0
383   maximum transition latency: 131 us
384   hardware limits: 400 MHz - 4.68 GHz
385   available cpufreq governors: ondemand conservative powersave userspace performance schedutil
386   current policy: frequency should be within 400 MHz and 4.68 GHz.
387                   The governor "schedutil" may decide which speed to use
388                   within this range.
389   current CPU frequency: Unable to call hardware
390   current CPU frequency: 4.02 GHz (asserted by call to kernel)
391   boost state support:
392     Supported: yes
393     Active: yes
394     AMD PSTATE Highest Performance: 166. Maximum Frequency: 4.68 GHz.
395     AMD PSTATE Nominal Performance: 117. Nominal Frequency: 3.30 GHz.
396     AMD PSTATE Lowest Non-linear Performance: 39. Lowest Non-linear Frequency: 1.10 GHz.
397     AMD PSTATE Lowest Performance: 15. Lowest Frequency: 400 MHz.
398
399
400Diagnostics and Tuning
401=======================
402
403Trace Events
404--------------
405
406There are two static trace events that can be used for ``amd-pstate``
407diagnostics. One of them is the ``cpu_frequency`` trace event generally used
408by ``CPUFreq``, and the other one is the ``amd_pstate_perf`` trace event
409specific to ``amd-pstate``.  The following sequence of shell commands can
410be used to enable them and see their output (if the kernel is
411configured to support event tracing). ::
412
413 root@hr-test1:/home/ray# cd /sys/kernel/tracing/
414 root@hr-test1:/sys/kernel/tracing# echo 1 > events/amd_cpu/enable
415 root@hr-test1:/sys/kernel/tracing# cat trace
416 # tracer: nop
417 #
418 # entries-in-buffer/entries-written: 47827/42233061   #P:2
419 #
420 #                                _-----=> irqs-off
421 #                               / _----=> need-resched
422 #                              | / _---=> hardirq/softirq
423 #                              || / _--=> preempt-depth
424 #                              ||| /     delay
425 #           TASK-PID     CPU#  ||||   TIMESTAMP  FUNCTION
426 #              | |         |   ||||      |         |
427          <idle>-0       [015] dN...  4995.979886: amd_pstate_perf: amd_min_perf=85 amd_des_perf=85 amd_max_perf=166 cpu_id=15 changed=false fast_switch=true
428          <idle>-0       [007] d.h..  4995.979893: amd_pstate_perf: amd_min_perf=85 amd_des_perf=85 amd_max_perf=166 cpu_id=7 changed=false fast_switch=true
429             cat-2161    [000] d....  4995.980841: amd_pstate_perf: amd_min_perf=85 amd_des_perf=85 amd_max_perf=166 cpu_id=0 changed=false fast_switch=true
430            sshd-2125    [004] d.s..  4995.980968: amd_pstate_perf: amd_min_perf=85 amd_des_perf=85 amd_max_perf=166 cpu_id=4 changed=false fast_switch=true
431          <idle>-0       [007] d.s..  4995.980968: amd_pstate_perf: amd_min_perf=85 amd_des_perf=85 amd_max_perf=166 cpu_id=7 changed=false fast_switch=true
432          <idle>-0       [003] d.s..  4995.980971: amd_pstate_perf: amd_min_perf=85 amd_des_perf=85 amd_max_perf=166 cpu_id=3 changed=false fast_switch=true
433          <idle>-0       [011] d.s..  4995.980996: amd_pstate_perf: amd_min_perf=85 amd_des_perf=85 amd_max_perf=166 cpu_id=11 changed=false fast_switch=true
434
435The ``cpu_frequency`` trace event will be triggered either by the ``schedutil`` scaling
436governor (for the policies it is attached to), or by the ``CPUFreq`` core (for the
437policies with other scaling governors).
438
439
440Tracer Tool
441-------------
442
443``amd_pstate_tracer.py`` can record and parse ``amd-pstate`` trace log, then
444generate performance plots. This utility can be used to debug and tune the
445performance of ``amd-pstate`` driver. The tracer tool needs to import intel
446pstate tracer.
447
448Tracer tool located in ``linux/tools/power/x86/amd_pstate_tracer``. It can be
449used in two ways. If trace file is available, then directly parse the file
450with command ::
451
452 ./amd_pstate_trace.py [-c cpus] -t <trace_file> -n <test_name>
453
454Or generate trace file with root privilege, then parse and plot with command ::
455
456 sudo ./amd_pstate_trace.py [-c cpus] -n <test_name> -i <interval> [-m kbytes]
457
458The test result can be found in ``results/test_name``. Following is the example
459about part of the output. ::
460
461 common_cpu  common_secs  common_usecs  min_perf  des_perf  max_perf  freq    mperf   apef    tsc       load   duration_ms  sample_num  elapsed_time  common_comm
462 CPU_005     712          116384        39        49        166       0.7565  9645075 2214891 38431470  25.1   11.646       469         2.496         kworker/5:0-40
463 CPU_006     712          116408        39        49        166       0.6769  8950227 1839034 37192089  24.06  11.272       470         2.496         kworker/6:0-1264
464
465Unit Tests for amd-pstate
466-------------------------
467
468``amd-pstate-ut`` is a test module for testing the ``amd-pstate`` driver.
469
470 * It can help all users to verify their processor support (SBIOS/Firmware or Hardware).
471
472 * Kernel can have a basic function test to avoid the kernel regression during the update.
473
474 * We can introduce more functional or performance tests to align the result together, it will benefit power and performance scale optimization.
475
4761. Test case descriptions
477
478    1). Basic tests
479
480        Test prerequisite and basic functions for the ``amd-pstate`` driver.
481
482        +---------+--------------------------------+------------------------------------------------------------------------------------+
483        | Index   | Functions                      | Description                                                                        |
484        +=========+================================+====================================================================================+
485        | 1       | amd_pstate_ut_acpi_cpc_valid   || Check whether the _CPC object is present in SBIOS.                                |
486        |         |                                ||                                                                                   |
487        |         |                                || The detail refer to `Processor Support <processor_support_>`_.                    |
488        +---------+--------------------------------+------------------------------------------------------------------------------------+
489        | 2       | amd_pstate_ut_check_enabled    || Check whether AMD P-State is enabled.                                             |
490        |         |                                ||                                                                                   |
491        |         |                                || AMD P-States and ACPI hardware P-States always can be supported in one processor. |
492        |         |                                | But AMD P-States has the higher priority and if it is enabled with                 |
493        |         |                                | :c:macro:`MSR_AMD_CPPC_ENABLE` or ``cppc_set_enable``, it will respond to the      |
494        |         |                                | request from AMD P-States.                                                         |
495        +---------+--------------------------------+------------------------------------------------------------------------------------+
496        | 3       | amd_pstate_ut_check_perf       || Check if the each performance values are reasonable.                              |
497        |         |                                || highest_perf >= nominal_perf > lowest_nonlinear_perf > lowest_perf > 0.           |
498        +---------+--------------------------------+------------------------------------------------------------------------------------+
499        | 4       | amd_pstate_ut_check_freq       || Check if the each frequency values and max freq when set support boost mode       |
500        |         |                                | are reasonable.                                                                    |
501        |         |                                || max_freq >= nominal_freq > lowest_nonlinear_freq > min_freq > 0                   |
502        |         |                                || If boost is not active but supported, this maximum frequency will be larger than  |
503        |         |                                | the one in ``cpuinfo``.                                                            |
504        +---------+--------------------------------+------------------------------------------------------------------------------------+
505
506    2). Tbench test
507
508        Test and monitor the cpu changes when running tbench benchmark under the specified governor.
509        These changes include desire performance, frequency, load, performance, energy etc.
510        The specified governor is ondemand or schedutil.
511        Tbench can also be tested on the ``acpi-cpufreq`` kernel driver for comparison.
512
513    3). Gitsource test
514
515        Test and monitor the cpu changes when running gitsource benchmark under the specified governor.
516        These changes include desire performance, frequency, load, time, energy etc.
517        The specified governor is ondemand or schedutil.
518        Gitsource can also be tested on the ``acpi-cpufreq`` kernel driver for comparison.
519
520#. How to execute the tests
521
522   We use test module in the kselftest frameworks to implement it.
523   We create ``amd-pstate-ut`` module and tie it into kselftest.(for
524   details refer to Linux Kernel Selftests [4]_).
525
526    1). Build
527
528        + open the :c:macro:`CONFIG_X86_AMD_PSTATE` configuration option.
529        + set the :c:macro:`CONFIG_X86_AMD_PSTATE_UT` configuration option to M.
530        + make project
531        + make selftest ::
532
533            $ cd linux
534            $ make -C tools/testing/selftests
535
536        + make perf ::
537
538            $ cd tools/perf/
539            $ make
540
541
542    2). Installation & Steps ::
543
544        $ make -C tools/testing/selftests install INSTALL_PATH=~/kselftest
545        $ cp tools/perf/perf /usr/bin/perf
546        $ sudo ./kselftest/run_kselftest.sh -c amd-pstate
547
548    3). Specified test case ::
549
550        $ cd ~/kselftest/amd-pstate
551        $ sudo ./run.sh -t basic
552        $ sudo ./run.sh -t tbench
553        $ sudo ./run.sh -t tbench -m acpi-cpufreq
554        $ sudo ./run.sh -t gitsource
555        $ sudo ./run.sh -t gitsource -m acpi-cpufreq
556        $ ./run.sh --help
557        ./run.sh: illegal option -- -
558        Usage: ./run.sh [OPTION...]
559                [-h <help>]
560                [-o <output-file-for-dump>]
561                [-c <all: All testing,
562                     basic: Basic testing,
563                     tbench: Tbench testing,
564                     gitsource: Gitsource testing.>]
565                [-t <tbench time limit>]
566                [-p <tbench process number>]
567                [-l <loop times for tbench>]
568                [-i <amd tracer interval>]
569                [-m <comparative test: acpi-cpufreq>]
570
571
572    4). Results
573
574        + basic
575
576         When you finish test, you will get the following log info ::
577
578          $ dmesg | grep "amd_pstate_ut" | tee log.txt
579          [12977.570663] amd_pstate_ut: 1    amd_pstate_ut_acpi_cpc_valid  success!
580          [12977.570673] amd_pstate_ut: 2    amd_pstate_ut_check_enabled   success!
581          [12977.571207] amd_pstate_ut: 3    amd_pstate_ut_check_perf      success!
582          [12977.571212] amd_pstate_ut: 4    amd_pstate_ut_check_freq      success!
583
584        + tbench
585
586         When you finish test, you will get selftest.tbench.csv and png images.
587         The selftest.tbench.csv file contains the raw data and the drop of the comparative test.
588         The png images shows the performance, energy and performan per watt of each test.
589         Open selftest.tbench.csv :
590
591         +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+
592         + Governor                                        | Round        | Des-perf | Freq    | Load     | Performance | Energy  | Performance Per Watt |
593         +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+
594         + Unit                                            |              |          | GHz     |          | MB/s        | J       | MB/J                 |
595         +=================================================+==============+==========+=========+==========+=============+=========+======================+
596         + amd-pstate-ondemand                             | 1            |          |         |          | 2504.05     | 1563.67 | 158.5378             |
597         +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+
598         + amd-pstate-ondemand                             | 2            |          |         |          | 2243.64     | 1430.32 | 155.2941             |
599         +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+
600         + amd-pstate-ondemand                             | 3            |          |         |          | 2183.88     | 1401.32 | 154.2860             |
601         +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+
602         + amd-pstate-ondemand                             | Average      |          |         |          | 2310.52     | 1465.1  | 156.1268             |
603         +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+
604         + amd-pstate-schedutil                            | 1            | 165.329  | 1.62257 | 99.798   | 2136.54     | 1395.26 | 151.5971             |
605         +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+
606         + amd-pstate-schedutil                            | 2            | 166      | 1.49761 | 99.9993  | 2100.56     | 1380.5  | 150.6377             |
607         +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+
608         + amd-pstate-schedutil                            | 3            | 166      | 1.47806 | 99.9993  | 2084.12     | 1375.76 | 149.9737             |
609         +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+
610         + amd-pstate-schedutil                            | Average      | 165.776  | 1.53275 | 99.9322  | 2107.07     | 1383.84 | 150.7399             |
611         +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+
612         + acpi-cpufreq-ondemand                           | 1            |          |         |          | 2529.9      | 1564.4  | 160.0997             |
613         +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+
614         + acpi-cpufreq-ondemand                           | 2            |          |         |          | 2249.76     | 1432.97 | 155.4297             |
615         +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+
616         + acpi-cpufreq-ondemand                           | 3            |          |         |          | 2181.46     | 1406.88 | 153.5060             |
617         +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+
618         + acpi-cpufreq-ondemand                           | Average      |          |         |          | 2320.37     | 1468.08 | 156.4741             |
619         +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+
620         + acpi-cpufreq-schedutil                          | 1            |          |         |          | 2137.64     | 1385.24 | 152.7723             |
621         +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+
622         + acpi-cpufreq-schedutil                          | 2            |          |         |          | 2107.05     | 1372.23 | 152.0138             |
623         +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+
624         + acpi-cpufreq-schedutil                          | 3            |          |         |          | 2085.86     | 1365.35 | 151.2433             |
625         +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+
626         + acpi-cpufreq-schedutil                          | Average      |          |         |          | 2110.18     | 1374.27 | 152.0136             |
627         +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+
628         + acpi-cpufreq-ondemand VS acpi-cpufreq-schedutil | Comprison(%) |          |         |          | -9.0584     | -6.3899 | -2.8506              |
629         +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+
630         + amd-pstate-ondemand VS amd-pstate-schedutil     | Comprison(%) |          |         |          | 8.8053      | -5.5463 | -3.4503              |
631         +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+
632         + acpi-cpufreq-ondemand VS amd-pstate-ondemand    | Comprison(%) |          |         |          | -0.4245     | -0.2029 | -0.2219              |
633         +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+
634         + acpi-cpufreq-schedutil VS amd-pstate-schedutil  | Comprison(%) |          |         |          | -0.1473     | 0.6963  | -0.8378              |
635         +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+
636
637        + gitsource
638
639         When you finish test, you will get selftest.gitsource.csv and png images.
640         The selftest.gitsource.csv file contains the raw data and the drop of the comparative test.
641         The png images shows the performance, energy and performan per watt of each test.
642         Open selftest.gitsource.csv :
643
644         +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+
645         + Governor                                        | Round        | Des-perf | Freq     | Load     | Time        | Energy  | Performance Per Watt |
646         +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+
647         + Unit                                            |              |          | GHz      |          | s           | J       | 1/J                  |
648         +=================================================+==============+==========+==========+==========+=============+=========+======================+
649         + amd-pstate-ondemand                             | 1            | 50.119   | 2.10509  | 23.3076  | 475.69      | 865.78  | 0.001155027          |
650         +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+
651         + amd-pstate-ondemand                             | 2            | 94.8006  | 1.98771  | 56.6533  | 467.1       | 839.67  | 0.001190944          |
652         +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+
653         + amd-pstate-ondemand                             | 3            | 76.6091  | 2.53251  | 43.7791  | 467.69      | 855.85  | 0.001168429          |
654         +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+
655         + amd-pstate-ondemand                             | Average      | 73.8429  | 2.20844  | 41.2467  | 470.16      | 853.767 | 0.001171279          |
656         +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+
657         + amd-pstate-schedutil                            | 1            | 165.919  | 1.62319  | 98.3868  | 464.17      | 866.8   | 0.001153668          |
658         +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+
659         + amd-pstate-schedutil                            | 2            | 165.97   | 1.31309  | 99.5712  | 480.15      | 880.4   | 0.001135847          |
660         +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+
661         + amd-pstate-schedutil                            | 3            | 165.973  | 1.28448  | 99.9252  | 481.79      | 867.02  | 0.001153375          |
662         +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+
663         + amd-pstate-schedutil                            | Average      | 165.954  | 1.40692  | 99.2944  | 475.37      | 871.407 | 0.001147569          |
664         +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+
665         + acpi-cpufreq-ondemand                           | 1            |          |          |          | 2379.62     | 742.96  | 0.001345967          |
666         +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+
667         + acpi-cpufreq-ondemand                           | 2            |          |          |          | 441.74      | 817.49  | 0.001223256          |
668         +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+
669         + acpi-cpufreq-ondemand                           | 3            |          |          |          | 455.48      | 820.01  | 0.001219497          |
670         +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+
671         + acpi-cpufreq-ondemand                           | Average      |          |          |          | 425.613     | 793.487 | 0.001260260          |
672         +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+
673         + acpi-cpufreq-schedutil                          | 1            |          |          |          | 459.69      | 838.54  | 0.001192548          |
674         +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+
675         + acpi-cpufreq-schedutil                          | 2            |          |          |          | 466.55      | 830.89  | 0.001203528          |
676         +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+
677         + acpi-cpufreq-schedutil                          | 3            |          |          |          | 470.38      | 837.32  | 0.001194286          |
678         +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+
679         + acpi-cpufreq-schedutil                          | Average      |          |          |          | 465.54      | 835.583 | 0.001196769          |
680         +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+
681         + acpi-cpufreq-ondemand VS acpi-cpufreq-schedutil | Comprison(%) |          |          |          | 9.3810      | 5.3051  | -5.0379              |
682         +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+
683         + amd-pstate-ondemand VS amd-pstate-schedutil     | Comprison(%) | 124.7392 | -36.2934 | 140.7329 | 1.1081      | 2.0661  | -2.0242              |
684         +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+
685         + acpi-cpufreq-ondemand VS amd-pstate-ondemand    | Comprison(%) |          |          |          | 10.4665     | 7.5968  | -7.0605              |
686         +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+
687         + acpi-cpufreq-schedutil VS amd-pstate-schedutil  | Comprison(%) |          |          |          | 2.1115      | 4.2873  | -4.1110              |
688         +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+
689
690Reference
691===========
692
693.. [1] AMD64 Architecture Programmer's Manual Volume 2: System Programming,
694       https://www.amd.com/system/files/TechDocs/24593.pdf
695
696.. [2] Advanced Configuration and Power Interface Specification,
697       https://uefi.org/sites/default/files/resources/ACPI_Spec_6_4_Jan22.pdf
698
699.. [3] Processor Programming Reference (PPR) for AMD Family 19h Model 51h, Revision A1 Processors
700       https://www.amd.com/system/files/TechDocs/56569-A1-PUB.zip
701
702.. [4] Linux Kernel Selftests,
703       https://www.kernel.org/doc/html/latest/dev-tools/kselftest.html
704