[LTP] [PATCH] pmc_core: add test for pkgc_blocker_residency_show

[LTP] [PATCH] pmc_core: add test for pkgc_blocker_residency_show

[Piotr Kubaj]

Add a test for the /sys/kernel/debug/pmc_core/pkgc_blocker_residency_show
interface added in kernel commit d727eb1c3ede ("platform/x86/intel/pmc:
Enable Pkgc blocking residency counter"), first released in v7.2.

The debugfs file reports per-source counters tracking which sources kept
the platform out of package C-states. The driver prints one line per
counter as "%-30s %-30u", where the name is a PKGC_BLOCK_RESIDENCY_<SOURCE>
token and the value counts the 10us intervals during which that source
blocked a package C-state entry.

The counter set is platform specific, so rather than checking a hardcoded
list the test samples the file twice and verifies that every line names a
PKGC_BLOCK_RESIDENCY_ source with a numeric value, that the set of counters
is stable across the two reads, and that no counter advanced by more than
the elapsed wall clock time allows.

The last check is what catches real breakage. The values are u32 counting
10us intervals, so a busy source wraps in well under a day: on Nova Lake,
PKGC_BLOCK_RESIDENCY_PMC_LTR advances fast enough to wrap roughly every 15
hours. The delta is therefore computed modulo 2^32, which tolerates a
genuine wrap while turning a counter reset or backward jump into a large
advance that the elapsed-time bound rejects. A telemetry region read at the
wrong offset shows up the same way. At the 2s sample interval the bound
admits about 0.01% of the u32 value space.

An unchanged counter is not a failure. Most sources are idle and read 0
permanently; on the test system 21 of 28 counters never moved. The sample
interval is 2s because the PMT telemetry region refreshes at roughly 1s
granularity - no counter moved over a 200ms or 500ms interval, so a shorter
sample would make every counter look static. The plausibility bound allows
a factor of two over the theoretical maximum, since a busy source can run
close to it: PMC_LTR was observed at 76% of the ceiling.

The debugfs file is only created for a PMC exposing a package C-state
telemetry endpoint (pc_guid in the driver's pmc_dev_info), which currently
means Nova Lake only. Other platforms report TCONF.

Requires CONFIG_INTEL_PMC_CORE and CONFIG_DEBUG_FS, needs root, and is
restricted to x86/x86_64 on GenuineIntel. The vendor check is redundant
with the kconfig and debugfs checks, but it is evaluated first and so
reports the actual reason rather than a missing debugfs file.

Tested on Nova Lake running 7.2.0-rc7: 28 counters reported, TPASS.
Fault injection against a stub file confirms the test detects a counter
reset, an out-of-range jump, a malformed line, an unexpected counter name
and an empty file, while still accepting a genuine u32 wrap.

Signed-off-by: Piotr Kubaj <piotr.kubaj@intel.com>
---
 runtest/power_management_tests                |   1 +
 testcases/kernel/power_management/.gitignore  |   1 +
 .../pkgc_blocker_residency_show.c             | 211 ++++++++++++++++++
 3 files changed, 213 insertions(+)
 create mode 100644 testcases/kernel/power_management/pkgc_blocker_residency_show.c

diff --git a/runtest/power_management_tests b/runtest/power_management_tests
index 5a22283d6..a3c7cab5e 100644
--- a/runtest/power_management_tests
+++ b/runtest/power_management_tests
@@ -2,6 +2,7 @@
 cpufreq_intel cpufreq_intel
 rfim01 rfim01
 high_freq_hwp_cap_cppc high_freq_hwp_cap_cppc
+pkgc_blocker_residency_show pkgc_blocker_residency_show
 runpwtests03 runpwtests03.sh
 runpwtests04 runpwtests04.sh
 runpwtests06 runpwtests06.sh
diff --git a/testcases/kernel/power_management/.gitignore b/testcases/kernel/power_management/.gitignore
index 766f07901..a35ca3567 100644
--- a/testcases/kernel/power_management/.gitignore
+++ b/testcases/kernel/power_management/.gitignore
@@ -1,3 +1,4 @@
 high_freq_hwp_cap_cppc
 cpufreq_intel
 rfim01
+pkgc_blocker_residency_show
diff --git a/testcases/kernel/power_management/pkgc_blocker_residency_show.c b/testcases/kernel/power_management/pkgc_blocker_residency_show.c
new file mode 100644
index 000000000..37c752c9c
--- /dev/null
+++ b/testcases/kernel/power_management/pkgc_blocker_residency_show.c
@@ -0,0 +1,211 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+/*
+ * Copyright (C) 2026 Piotr Kubaj <piotr.kubaj@intel.com>
+ */
+
+/*\
+ * Verify that pkgc_blocker_residency_show reports well-formed package C-state
+ * blocker residency counters that advance at a plausible rate.
+ *
+ * The intel_pmc_core driver prints one line per counter as "%-30s %-30u",
+ * where the name is a PKGC_BLOCK_RESIDENCY_<SOURCE> token and the value counts
+ * the 10us intervals during which <SOURCE> blocked a package C-state entry.
+ *
+ * The counter set is platform specific, so instead of checking a hardcoded
+ * list the test samples the file twice and verifies that
+ *
+ * - every line names a PKGC_BLOCK_RESIDENCY_ source and carries a value,
+ * - the set of counters does not change between the two reads,
+ * - no counter advances by more than the elapsed wall clock time allows.
+ *
+ * The last check is the one that catches real regressions. The values are u32
+ * counting 10us intervals, so a busy source wraps in well under a day and a
+ * wrap is indistinguishable from a bogus read unless the delta is evaluated
+ * modulo 2^32 and bounded by the elapsed time. A telemetry region read at the
+ * wrong offset then shows up as an implausible jump.
+ *
+ * The debugfs file is only created for a PMC that exposes a package C-state
+ * telemetry endpoint (pc_guid in the driver's pmc_dev_info), so on platforms
+ * without one the test is not applicable.
+ */
+
+#include <time.h>
+#include "tst_clocks.h"
+#include "tst_safe_stdio.h"
+#include "tst_test.h"
+#include "tst_timer.h"
+
+#define DEBUGFS "/sys/kernel/debug"
+#define PATH DEBUGFS "/pmc_core/pkgc_blocker_residency_show"
+#define PREFIX "PKGC_BLOCK_RESIDENCY_"
+
+/* Nova Lake reports 28 counters, leave room for future platforms */
+#define MAX_COUNTERS 128
+#define NAME_LEN 64
+
+/* Each count stands for a 10us interval spent blocking package C-state entry */
+#define COUNTER_PERIOD_US 10
+
+/*
+ * Interval between the two samples. The PMT telemetry region behind these
+ * counters refreshes at roughly 1s granularity: measured on Nova Lake, no
+ * counter moved over 200ms or 500ms, while 5 of 28 moved over 1s. Sample well
+ * past that so a static counter means "idle source", not "not refreshed yet".
+ */
+#define SAMPLE_DELAY_US 2000000
+
+/*
+ * Slack over the theoretical maximum advance. The two reads bracket the
+ * measured interval, and a busy source can legitimately run close to the
+ * ceiling: PKGC_BLOCK_RESIDENCY_PMC_LTR was observed at 76% of it on Nova Lake.
+ * A factor of two keeps that clear of the limit while still rejecting a bogus
+ * telemetry read, which overshoots by orders of magnitude.
+ */
+#define SLACK 2
+
+struct snapshot {
+	char names[MAX_COUNTERS][NAME_LEN];
+	uint32_t values[MAX_COUNTERS];
+	int cnt;
+};
+
+static struct snapshot first, second;
+
+/*
+ * Decide whether a counter that read @old and then @new, @elapsed_us
+ * microseconds apart, advanced plausibly.
+ *
+ * The values are u32 and wrap, so the advance has to be computed with modular
+ * arithmetic rather than by comparing @new against @old. Each count stands for
+ * COUNTER_PERIOD_US of blocked time, which bounds how far a counter can move
+ * over a given interval.
+ *
+ * An unchanged counter is normal: it means that source did not block a package
+ * C-state entry during the interval. Most counters on an idle system read 0
+ * permanently.
+ */
+static int delta_plausible(uint32_t old, uint32_t new,
+			   unsigned long long elapsed_us)
+{
+	uint32_t delta = new - old;
+	unsigned long long max = elapsed_us / COUNTER_PERIOD_US;
+
+	return delta <= max * SLACK;
+}
+
+static void read_snapshot(struct snapshot *snap)
+{
+	char line[256];
+	FILE *fp;
+
+	snap->cnt = 0;
+	fp = SAFE_FOPEN(PATH, "r");
+
+	while (fgets(line, sizeof(line), fp)) {
+		char name[NAME_LEN];
+		unsigned int value;
+
+		line[strcspn(line, "\n")] = '\0';
+
+		if (sscanf(line, "%63s %u", name, &value) != 2) {
+			tst_res(TFAIL, "malformed counter line: '%s'", line);
+			continue;
+		}
+
+		if (strncmp(name, PREFIX, sizeof(PREFIX) - 1)) {
+			tst_res(TFAIL, "counter '%s' lacks the " PREFIX " prefix", name);
+			continue;
+		}
+
+		if (snap->cnt == MAX_COUNTERS)
+			tst_brk(TBROK, "more than %d counters reported", MAX_COUNTERS);
+
+		strcpy(snap->names[snap->cnt], name);
+		snap->values[snap->cnt] = value;
+		snap->cnt++;
+	}
+
+	SAFE_FCLOSE(fp);
+}
+
+static void setup(void)
+{
+	if (access(DEBUGFS, F_OK))
+		tst_brk(TCONF | TERRNO, "debugfs not mounted at " DEBUGFS);
+
+	if (access(PATH, R_OK))
+		tst_brk(TCONF | TERRNO, "%s not available", PATH);
+}
+
+static void run(void)
+{
+	struct timespec start, end;
+	unsigned long long elapsed_us;
+	int fails = 0;
+
+	tst_clock_gettime(CLOCK_MONOTONIC, &start);
+	read_snapshot(&first);
+
+	if (!first.cnt)
+		tst_brk(TFAIL, "no residency counters reported");
+
+	usleep(SAMPLE_DELAY_US);
+
+	read_snapshot(&second);
+	tst_clock_gettime(CLOCK_MONOTONIC, &end);
+
+	elapsed_us = tst_timespec_diff_us(end, start);
+
+	if (first.cnt != second.cnt) {
+		tst_brk(TFAIL, "counter count changed between reads: %d -> %d",
+			first.cnt, second.cnt);
+	}
+
+	for (int i = 0; i < first.cnt; i++) {
+		if (strcmp(first.names[i], second.names[i])) {
+			tst_res(TFAIL, "counter %d renamed between reads: %s -> %s",
+				i, first.names[i], second.names[i]);
+			fails++;
+			continue;
+		}
+
+		tst_res(TDEBUG, "%s: %u -> %u", first.names[i],
+			first.values[i], second.values[i]);
+
+		if (!delta_plausible(first.values[i], second.values[i], elapsed_us)) {
+			tst_res(TFAIL,
+				"%s advanced implausibly over %lluus: %u -> %u",
+				first.names[i], elapsed_us,
+				first.values[i], second.values[i]);
+			fails++;
+		}
+	}
+
+	if (!fails) {
+		tst_res(TPASS, "%d residency counters well-formed, advancing plausibly",
+			first.cnt);
+	}
+}
+
+static struct tst_test test = {
+	.min_kver = "7.2",
+	.needs_cpu_vendor = "GenuineIntel",
+	.needs_root = 1,
+	.needs_kconfigs = (const char *const []) {
+		"CONFIG_DEBUG_FS",
+		"CONFIG_INTEL_PMC_CORE",
+		NULL
+	},
+	.supported_archs = (const char *const []) {
+		"x86",
+		"x86_64",
+		NULL
+	},
+	.tags = (const struct tst_tag[]) {
+		{"linux-git", "d727eb1c3ede7c21f885ded1f1ad65b47434a9b9"},
+		{}
+	},
+	.setup = setup,
+	.test_all = run
+};
-- 
2.47.3

---------------------------------------------------------------------
Intel Technology Poland sp. z o.o.
ul. Slowackiego 173 | 80-298 Gdansk | Sad Rejonowy Gdansk Polnoc | VII Wydzial Gospodarczy Krajowego Rejestru Sadowego - KRS 101882 | NIP 957-07-52-316 | Kapital zakladowy 200.000 PLN.
Spolka oswiadcza, ze posiada status duzego przedsiebiorcy w rozumieniu ustawy z dnia 8 marca 2013 r. o przeciwdzialaniu nadmiernym opoznieniom w transakcjach handlowych.

Ta wiadomosc wraz z zalacznikami jest przeznaczona dla okreslonego adresata i moze zawierac informacje poufne. W razie przypadkowego otrzymania tej wiadomosci, prosimy o powiadomienie nadawcy oraz trwale jej usuniecie; jakiekolwiek przegladanie lub rozpowszechnianie jest zabronione.
This e-mail and any attachments may contain confidential material for the sole use of the intended recipient(s). If you are not the intended recipient, please contact the sender and delete all copies; any review or distribution by others is strictly prohibited.


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] pmc_core: add test for pkgc_blocker_residency_show

[linuxtestproject.agent]

Hi Piotr,

On August 11, 2026, Piotr Kubaj wrote:
> pmc_core: add test for pkgc_blocker_residency_show

> 	/*
> 	 * Interval between the two samples. The PMT telemetry region behind these
> 	 * counters refreshes at roughly 1s granularity: measured on Nova Lake, no
> 	 * counter moved over 200ms or 500ms, while 5 of 28 moved over 1s. Sample well
> 	 * past that so a static counter means "idle source", not "not refreshed yet".
> 	 */
> 	#define SAMPLE_DELAY_US 2000000
> 	...
> 	usleep(SAMPLE_DELAY_US);

Could this use bounded exponential-backoff polling instead? The fixed sleep is
being used to synchronize the second sample with the asynchronous telemetry
refresh, which violates the no sleep-based synchronization rule.

> 		if (sscanf(line, "%63s %u", name, &value) != 2) {
> 			tst_res(TFAIL, "malformed counter line: '%s'", line);
> 			continue;
> 		}
>
> 		if (strncmp(name, PREFIX, sizeof(PREFIX) - 1)) {

Could this validate the complete line and require a nonempty source suffix?
The current conversion accepts signed values, trailing tokens, and the bare
name "PKGC_BLOCK_RESIDENCY_". If both snapshots contain such a line, it is
recorded as a valid counter and the test can pass despite malformed output.

> 	.needs_root = 1,

Could the high-level description explain why root is required? Tests setting
needs_root must document the reason in the exported test description.

>  high_freq_hwp_cap_cppc
>  cpufreq_intel
>  rfim01
> +pkgc_blocker_residency_show

Could the new entry be inserted alphabetically? Leaf .gitignore entries are
required to remain sorted.

Verdict - Needs revision

---
Note:

The agent can sometimes produce false positives although often its
findings are genuine. If you find issues with the review, please
comment this email or ignore the suggestions.

Regards,
LTP AI Reviewer

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp