Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Received-SPF: Pass (protection.outlook.com: domain of amd.com designates
 165.204.84.17 as permitted sender) receiver=protection.outlook.com;
 client-ip=165.204.84.17; helo=SATLEXMB04.amd.com;
From:   Meng Li <li.meng@amd.com>
To:     Shuah Khan <skhan@linuxfoundation.org>,
        "Rafael J . Wysocki" <rafael.j.wysocki@intel.com>,
        Huang Rui <ray.huang@amd.com>, <linux-pm@vger.kernel.org>
CC:     Nathan Fontenot <nathan.fontenot@amd.com>,
        Deepak Sharma <deepak.sharma@amd.com>,
        Alex Deucher <alexander.deucher@amd.com>,
        "Mario Limonciello" <mario.limonciello@amd.com>,
        Jinzhou Su <Jinzhou.Su@amd.com>,
        Perry Yuan <Perry.Yuan@amd.com>,
        Xiaojian Du <Xiaojian.Du@amd.com>,
        "Viresh Kumar" <viresh.kumar@linaro.org>,
        Borislav Petkov <bp@alien8.de>, <linux-kernel@vger.kernel.org>,
        Meng Li <li.meng@amd.com>
Subject: [PATCH 3/3] Documentation: amd-pstate: Add unit test introduction
Date:   Wed, 23 Mar 2022 15:15:02 +0800
Message-ID: <20220323071502.2674156-4-li.meng@amd.com>
In-Reply-To: <20220323071502.2674156-1-li.meng@amd.com>
References: <20220323071502.2674156-1-li.meng@amd.com>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Content-Type: text/plain
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 23 Mar 2022 07:15:52.8153
 (UTC)
X-MS-Exchange-CrossTenant-Network-Message-Id: 9f27ff9b-5c50-453f-9e42-08da0c9cf744
X-MS-Exchange-CrossTenant-Id: 3dd8961f-e488-4e60-8e11-a82d994e183d
X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=3dd8961f-e488-4e60-8e11-a82d994e183d;Ip=[165.204.84.17];Helo=[SATLEXMB04.amd.com]
X-MS-Exchange-CrossTenant-AuthSource: DM6NAM11FT010.eop-nam11.prod.protection.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Anonymous
X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem
X-MS-Exchange-Transport-CrossTenantHeadersStamped: CY4PR12MB1591
X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED,
        DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_NONE,
        RCVD_IN_MSPIKE_H2,SPF_HELO_PASS,SPF_PASS,T_SCC_BODY_TEXT_LINE
        autolearn=ham autolearn_force=no version=3.4.6
X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on
        lindbergh.monkeyblade.net
Precedence: bulk
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

Introduce the AMD P-State unit test module design and implementation.

Signed-off-by: Meng Li <li.meng@amd.com>
---
 Documentation/admin-guide/pm/amd-pstate.rst | 221 ++++++++++++++++++++
 1 file changed, 221 insertions(+)

diff --git a/Documentation/admin-guide/pm/amd-pstate.rst b/Documentation/admin-guide/pm/amd-pstate.rst
index 1923cb25073b..47ba6eeb2e38 100644
--- a/Documentation/admin-guide/pm/amd-pstate.rst
+++ b/Documentation/admin-guide/pm/amd-pstate.rst
@@ -182,6 +182,7 @@ according to the ``struct sugov_cpu`` that utilization update belongs to.
 Then ``amd-pstate`` updates the desired performance according to the CPU
 scheduler assigned.
 
+.. _processor_support:
 
 Processor Support
 =======================
@@ -283,6 +284,8 @@ efficiency frequency management method on AMD processors.
 Kernel Module Options for ``amd-pstate``
 =========================================
 
+.. _shared_mem:
+
 ``shared_mem``
 Use a module param (shared_mem) to enable related processors manually with
 **amd_pstate.shared_mem=1**.
@@ -395,6 +398,224 @@ about part of the output. ::
  CPU_006     712          116408        39        49        166       0.6769  8950227 1839034 37192089  24.06  11.272       470         2.496         kworker/6:0-1264
 
 
+Unit Tests for amd-pstate
+-------------------------
+
+``amd-pstate-ut`` is a kernel module for testing the functions of ``amd-pstate``.
+It can verify the required conditions and basic functions of ``amd-pstate`` before integration test.
+
+1. Test case decriptions
+
+        +---------+--------------------------------+------------------------------------------------------------------------------------+
+        | Index   | Functions                      | Description                                                                        |
+        +=========+================================+====================================================================================+
+        | 0       | stop                           || Stop the test currently in progress.                                              |
+        |         |                                ||                                                                                   |
+        |         |                                || For example: if the n test case is being executed, it needs to be completed and   |
+        |         |                                | the next test case will not be executed.                                           |
+        +---------+--------------------------------+------------------------------------------------------------------------------------+
+        | 1       | all                            || Start all test cases.                                                             |
+        |         |                                ||                                                                                   |
+        |         |                                || - Pass : all cases pass                                                           |
+        |         |                                || - Fail : only one case fail                                                       |
+        +---------+--------------------------------+------------------------------------------------------------------------------------+
+        | 2       | x86_vendor                     || Check whether the boot CPU x86_vendor is AMD.                                     |
+        |         |                                ||                                                                                   |
+        |         |                                || - Pass : yes                                                                      |
+        |         |                                || - Fail : no                                                                       |
+        +---------+--------------------------------+------------------------------------------------------------------------------------+
+        | 3       | acpi_cpc_valid                 || Check whether the _CPC object is present in SBIOS.                                |
+        |         |                                ||                                                                                   |
+        |         |                                || The detail refer to `Processor Support <processor_support_>`_.                    |
+        |         |                                ||                                                                                   |
+        |         |                                || - Pass : yes                                                                      |
+        |         |                                || - Fail : no                                                                       |
+        +---------+--------------------------------+------------------------------------------------------------------------------------+
+        | 4       | modprobed_driver               || Check whether cpufreq_driver module is load.                                      |
+        |         |                                ||                                                                                   |
+        |         |                                || - Pass : yes                                                                      |
+        |         |                                || - Fail : no                                                                       |
+        +---------+--------------------------------+------------------------------------------------------------------------------------+
+        | 5       | capability_check               || Full MSR Support: check whether cpu set feature flag :c:macro:`X86_FEATURE_CPPC`. |
+        |         |                                || The detail refer to `Processor Support <processor_support_>`_.                    |
+        |         |                                ||                                                                                   |
+        |         |                                || Shared Memory Support: check whether module param shared_mem enable               |
+        |         |                                || The detail refer to `Shared Memory <shared_mem_>`_.                               |
+        |         |                                ||                                                                                   |
+        |         |                                || - Pass : yes                                                                      |
+        |         |                                || - Fail : no                                                                       |
+        +---------+--------------------------------+------------------------------------------------------------------------------------+
+        | 6       | enable                         || Check whether AMD P-State is enabled.                                             |
+        |         |                                ||                                                                                   |
+        |         |                                || AMD P-States and ACPI hardware P-States always can be supported in one processor. |
+        |         |                                | But AMD P-States has the higher priority and if it is enabled with                 |
+        |         |                                | :c:macro:`MSR_AMD_CPPC_ENABLE` or ``cppc_set_enable``, it will respond to the      |
+        |         |                                | request from AMD P-States.                                                         |
+        |         |                                ||                                                                                   |
+        |         |                                || - Pass : yes                                                                      |
+        |         |                                || - Fail : no                                                                       |
+        +---------+--------------------------------+------------------------------------------------------------------------------------+
+        | 7       | init_perf                      || Check whether AMD P-State init perf sucessfully.                                  |
+        |         |                                | Include highest_perf, nominal_perf, lowest_nonlinear_perf and lowest_perf values.  |
+        |         |                                ||                                                                                   |
+        |         |                                || - Pass : yes                                                                      |
+        |         |                                || - Fail : no                                                                       |
+        +---------+--------------------------------+------------------------------------------------------------------------------------+
+        | 8       | support_boost                  || Check whether all cpus support boost.                                             |
+        |         |                                ||                                                                                   |
+        |         |                                || If boost is not active but supported, this maximum frequency will be larger than  |
+        |         |                                | the one in ``cpuinfo``.                                                            |
+        |         |                                ||                                                                                   |
+        |         |                                || - Pass : yes                                                                      |
+        |         |                                || - Fail : only one cpu not suppport boost                                          |
+        +---------+--------------------------------+------------------------------------------------------------------------------------+
+        | 9       | clear_status                   || Clear all test results.                                                           |
+        |         |                                ||                                                                                   |
+        |         |                                || **This test case is always at the end and cannot be changed.**                    |
+        +---------+--------------------------------+------------------------------------------------------------------------------------+
+
+#. How to execute the tests
+
+    a. Build ::
+
+        jasminemeng@jasmine-meng:~/amd-brahma$ cd linux
+        jasminemeng@jasmine-meng:~/amd-brahma/linux$ make modules M=tools/power/cpupower/debug/kernel/
+          CC [M]  tools/power/cpupower/debug/kernel/amd_pstate_ut.o
+          MODPOST tools/power/cpupower/debug/kernel/Module.symvers
+          CC [M]  tools/power/cpupower/debug/kernel/amd_pstate_ut.mod.o
+          LD [M]  tools/power/cpupower/debug/kernel/amd_pstate_ut.ko
+
+
+    #. Installation & Steps
+
+       Test all cases ::
+
+        jasmine@jasmine-MayanDAP-RMB:~$ sudo insmod amd_pstate_ut.ko
+        jasmine@jasmine-MayanDAP-RMB:~$ cd /sys/module/amd_pstate_ut/parameters/
+        jasmine@jasmine-MayanDAP-RMB:/sys/module/amd_pstate_ut/parameters$ sudo chmod 666 unit_test
+        jasmine@jasmine-MayanDAP-RMB:/sys/module/amd_pstate_ut/parameters$ cat unit_test
+        Index	 Test cases          	 Status
+        0    	 stop                	 [ ]
+        1    	 all                 	 [ ]
+        2    	 x86_vendor          	 [ ]
+        3    	 acpi_cpc_valid      	 [ ]
+        4    	 modprobed_driver    	 [ ]
+        5    	 capability_check    	 [ ]
+        6    	 enable              	 [ ]
+        7    	 init_perf           	 [ ]
+        8    	 support_boost       	 [ ]
+        9    	 clear_status        	 [ ]
+        ------------------------------------------
+        begin_index = 0 end_index= 0
+        jasmine@jasmine-MayanDAP-RMB:/sys/module/amd_pstate_ut/parameters$ echo 1 > unit_test
+        jasmine@jasmine-MayanDAP-RMB:/sys/module/amd_pstate_ut/parameters$ cat unit_test
+        Index	 Test cases          	 Status
+        0    	 stop                	 [ ]
+        1    	 all                 	 [P]
+        2    	 x86_vendor          	 [P]
+        3    	 acpi_cpc_valid      	 [P]
+        4    	 modprobed_driver    	 [P]
+        5    	 capability_check    	 [P]
+        6    	 enable              	 [P]
+        7    	 init_perf           	 [P]
+        8    	 support_boost       	 [P]
+        9    	 clear_status        	 [ ]
+        ------------------------------------------
+        begin_index = 1 end_index= 8
+
+       Clear test resut ::
+
+        jasmine@jasmine-MayanDAP-RMB:/sys/module/amd_pstate_ut/parameters$ echo 9 > unit_test
+        jasmine@jasmine-MayanDAP-RMB:/sys/module/amd_pstate_ut/parameters$ cat unit_test
+        Index	 Test cases          	 Status
+        0    	 stop                	 [ ]
+        1    	 all                 	 [ ]
+        2    	 x86_vendor          	 [ ]
+        3    	 acpi_cpc_valid      	 [ ]
+        4    	 modprobed_driver    	 [ ]
+        5    	 capability_check    	 [ ]
+        6    	 enable              	 [ ]
+        7    	 init_perf           	 [ ]
+        8    	 support_boost       	 [ ]
+        ------------------------------------------
+        begin_index = 0 end_index= 0
+
+       Test specific case ::
+
+        jasmine@jasmine-MayanDAP-RMB:/sys/module/amd_pstate_ut/parameters$ echo 3 > unit_test
+        jasmine@jasmine-MayanDAP-RMB:/sys/module/amd_pstate_ut/parameters$ cat unit_test
+        Index	 Test cases          	 Status
+        0    	 stop                	 [ ]
+        1    	 all                 	 [ ]
+        2    	 x86_vendor          	 [ ]
+        3    	 acpi_cpc_valid      	 [P]
+        4    	 modprobed_driver    	 [ ]
+        5    	 capability_check    	 [ ]
+        6    	 enable              	 [ ]
+        7    	 init_perf           	 [ ]
+        8    	 support_boost       	 [ ]
+        9    	 clear_status        	 [ ]
+        ------------------------------------------
+        begin_index = 3 end_index= 3
+
+       Test some cases ::
+
+        jasmine@jasmine-MayanDAP-RMB:/sys/module/amd_pstate_ut/parameters$ echo 5 8 > unit_test
+        jasmine@jasmine-MayanDAP-RMB:/sys/module/amd_pstate_ut/parameters$ cat unit_test
+        Index	 Test cases          	 Status
+        0    	 stop                	 [ ]
+        1    	 all                 	 [ ]
+        2    	 x86_vendor          	 [ ]
+        3    	 acpi_cpc_valid      	 [P]
+        4    	 modprobed_driver    	 [ ]
+        5    	 capability_check    	 [P]
+        6    	 enable              	 [P]
+        7    	 init_perf           	 [P]
+        8    	 support_boost       	 [P]
+        9    	 clear_status        	 [ ]
+        ------------------------------------------
+        begin_index = 5 end_index= 8
+
+
+    #. Results
+
+        +-----------+--------------------------------+
+        |  Status   | Description                    |
+        +===========+================================+
+        |   [ ]     | Not test.                      |
+        +-----------+--------------------------------+
+        |   [P]     | Test pass.                     |
+        +-----------+--------------------------------+
+        |   [F]     | Test fail.                     |
+        +-----------+--------------------------------+
+
+        Enable all the messages in the ``amd-pstate-ut`` module. ::
+
+         jasmine@jasmine-MayanDAP-RMB:~/3_Cr$ su
+         root@jasmine-MayanDAP-RMB:# echo -n "module amd_pstate_ut +p" > /sys/kernel/debug/dynamic_debug/control
+
+        When you start to test all cases, you will get the follow logs. ::
+
+         jasmine@jasmine-MayanDAP-RMB:~$ dmesg | grep "AMD P-state UT" | tee log.txt
+         [  732.084122] AMD P-state UT:param_set_index 1 0 result=0!
+         [  732.084140] AMD P-state UT:!====! Begin all unit test! !====!
+         [  732.084146] AMD P-state UT:****** Begin 2    	 x86_vendor          	 ******
+         [  732.084152] AMD P-state UT:****** End   2    	 x86_vendor          	 ******
+         [  732.084156] AMD P-state UT:****** Begin 3    	 acpi_cpc_valid      	 ******
+         [  732.084162] AMD P-state UT:****** End   3    	 acpi_cpc_valid      	 ******
+         [  732.084165] AMD P-state UT:****** Begin 4    	 modprobed_driver    	 ******
+         [  732.084168] AMD P-state UT:****** End   4    	 modprobed_driver    	 ******
+         [  732.084172] AMD P-state UT:****** Begin 5    	 capability_check    	 ******
+         [  732.084174] AMD P-state UT:****** End   5    	 capability_check    	 ******
+         [  732.084176] AMD P-state UT:****** Begin 6    	 enable              	 ******
+         [  732.084222] AMD P-state UT:****** End   6    	 enable              	 ******
+         [  732.084225] AMD P-state UT:****** Begin 7    	 init_perf           	 ******
+         [  732.085016] AMD P-state UT:****** End   7    	 init_perf           	 ******
+         [  732.085026] AMD P-state UT:****** Begin 8    	 support_boost       	 ******
+         [  732.085033] AMD P-state UT:****** End   8    	 support_boost       	 ******
+         [  732.085036] AMD P-state UT:!====! End   all unit test! !====!
+
+
 Reference
 ===========
 
-- 
2.25.1