Re: [PATCH v10 1/1] perf jevents: Check the keys of the JSON tables
From: James Clark
Date: Thu Nov 19 2026 - 09:20:21 EST
On 13/11/2026 03:29, TAKANO Mitsuhiro wrote:
jevents.py takes the fields it wants out of each JSON object by name and
ignores the rest, so a key that is spelled differently is dropped without
a word and the object is built without whatever that field held. Two of
those are in the tree: "PublicDescrition" in 16 entries of an Arm table,
and "BriefDescript6ion" in one entry each of three AMD tables.
I think the commit message can just be "... validate that the jsons only contain known keys so that the build fails when there is a typo in a key ..."
There's not much more to say than that.
A table may carry 51 keys; 47 of them jevents.py reads, one more metric.py
reads, and three are read by nothing although the tables hold them
(Counter, CountersNumFixed, CountersNumGeneric). A key outside that list
is reported with the file that carries it. There is no cut-off, no
similarity and nothing that depends on what a run of the generator
happened to read.
The check is not a JSON schema because perf's build would then require
jsonschema, which it does not use today and which is not in every
builder's python. It runs as a perf test, not as part of the build.
--check reads its directory before the parser asks for the three
Can we drop the --check argument and do it unconditionally? See below.
positional arguments, so it needs no dummy architecture and model, and it
takes "--check=DIR" as well as "--check DIR". A directory that is not
there is reported instead of passed, since nothing found under it would
otherwise read as a clean tree.
On the tree today it reports 19 keys in four tables.
There shouldn't be any errors when this patch is applied. If there are there needs to be a commit before adding the checker that fixes it.
Signed-off-by: TAKANO Mitsuhiro <takano32@xxxxxxxxx>
---
v10: the two fixes v9 described were missing from the diff v9 carried;
they are in this one. The check itself is unchanged.
tools/perf/pmu-events/jevents.py | 48 +++++++++++++++++++++++++
tools/perf/tests/shell/jevents_check.sh | 36 +++++++++++++++++++
2 files changed, 84 insertions(+)
create mode 100755 tools/perf/tests/shell/jevents_check.sh
diff --git a/tools/perf/pmu-events/jevents.py b/tools/perf/pmu-events/jevents.py
index 080e04b51b8c..4bbaba7086c5 100755
--- a/tools/perf/pmu-events/jevents.py
+++ b/tools/perf/pmu-events/jevents.py
@@ -7,6 +7,7 @@ import json
import metric
import os
import sys
+from pathlib import Path
from typing import (Callable, Dict, Optional, Sequence, Set, Tuple)
import collections
@@ -1450,9 +1451,56 @@ def _init_worker(std_events: dict) -> None:
global _arch_std_events
_arch_std_events = std_events
+# The keys a json object under arch/ may carry. jevents.py takes the fields it
+# wants by name and ignores the rest, so a key that is spelled differently is
+# dropped without a word; this is the list a table is allowed to contain.
+_TABLE_KEYS: Set[str] = {
Rename this to _valid_keys and move it to the top of the file where the other lists of attributes are.
+ 'AggregationMode', 'AnyThread', 'ArchStdEvent', 'BriefDescription',
+ 'Compat', 'ConfigCode', 'Counter', 'CounterMask',
+ 'CountersNumFixed', 'CountersNumGeneric', 'Data_LA', 'DefaultMetricgroupName',
+ 'DefaultShowEvents', 'Deprecated', 'EdgeDetect', 'EnAllCores',
+ 'EnAllSlices', 'Errata', 'EventCode', 'EventidCode',
+ 'EventName', 'Experimental', 'ExtSel', 'FCMask',
+ 'Filter', 'Invert', 'LegacyCacheCode', 'LegacyConfigCode',
+ 'MetricConstraint', 'MetricExpr', 'MetricGroup', 'MetricgroupNoGroup',
+ 'MetricName', 'MetricThreshold', 'MSRIndex', 'MSRValue',
+ 'NodeType', 'PEBS', 'PerPkg', 'PortMask',
+ 'PublicDescription', 'RdWrMask', 'RetirementLatencyMax', 'RetirementLatencyMean',
+ 'RetirementLatencyMin', 'SampleAfterValue', 'ScaleUnit', 'SliceId',
+ 'ThreadMask', 'UMask', 'Unit',
+}
+
+def _check_tables(root: str) -> int:
+ """Report the keys in the tables under root that a table may not carry."""
All you need to check them is this in the JsonEvent constructor:
class JsonEvent:
def __init__(self, jd: dict):
if extra := set(jd) - _valid_keys:
raise ValueError(f'Unknown keys ...')
+ if not os.path.isdir(root):
+ print(f'{root}: not a directory', file=sys.stderr)
+ return 2
+ bad = 0
+ for path in sorted(Path(root).rglob('*.json')):
+ if path.name.endswith('metricgroups.json'):
+ # A dictionary keyed by metric group name, not a list of events.
+ continue
+ for obj in json.loads(path.read_text(encoding='utf-8')):
+ if extra := set(obj) - _TABLE_KEYS:
+ print(f'{path}: {sorted(extra)}')
+ bad += 1
+ return 1 if bad else 0
+
def main() -> None:
global _args
+ # --check takes the directory to check and needs nothing else, so it is read
+ # before the parser below asks for the three positional arguments. Both
+ # "--check DIR" and "--check=DIR" are accepted.
+ for i, arg in enumerate(sys.argv[1:]):
+ if arg != '--check' and not arg.startswith('--check='):
Avoiding using argparse is pretty horrible, but that goes away if you remove the --check argument.
+ continue
+ if arg.startswith('--check='):
+ root = arg.split('=', 1)[1]
+ else:
+ root = sys.argv[i + 2] if len(sys.argv) > i + 2 else ''
+ sys.exit(_check_tables(root))
+
def dir_path(path: str) -> str:
"""Validate path is a directory for argparse."""
if os.path.isdir(path):
diff --git a/tools/perf/tests/shell/jevents_check.sh b/tools/perf/tests/shell/jevents_check.sh
new file mode 100755
index 000000000000..b596f8bc509d
--- /dev/null
+++ b/tools/perf/tests/shell/jevents_check.sh
@@ -0,0 +1,36 @@
+#!/bin/sh
+# SPDX-License-Identifier: GPL-2.0
+# jevents_check: an unknown key in a table is reported (no_mlock)
This has the potential to cause slight confusion about whether this is doing the validation for all json files or checking the checker itself. Some of that confusion goes away if you remove the --check argument, but the test should probably be called "jevents_bad_key.sh" and the description "Check jevents.py reports unknown keys as errors (no_mlock)".
+#
+# A key that is spelled differently is dropped without a word, so the keys of
+# the tables are checked against the list jevents.py reads.
+
+jevents=$(dirname "$0")/../../pmu-events/jevents.py
+python=${PYTHON:-python3}
+
+# An installed perf has the test but not the generator, and a python that
+# cannot run the generator is not a failure of the check.
+[ -r "${jevents}" ] || exit 2
+command -v "${python}" > /dev/null || exit 2
+
+tmp=$(mktemp -d)
+trap 'rm -rf "${tmp}"' EXIT
+tables="${tmp}/arch/x86/model"
+mkdir -p "${tables}"
+
+# Known keys pass.
+printf '[{"EventName": "a", "EventCode": "0x1"}]\n' > "${tables}/events.json"
+"${python}" "${jevents}" --check "${tmp}/arch" > /dev/null || exit 1
+
No need for the happy path to be tested if we always check as part of the build.
+# A key the generator does not read is reported.
+printf '[{"EventName": "a", "NotAKey": "x"}]\n' > "${tables}/events.json"
+"${python}" "${jevents}" --check "${tmp}/arch" > /dev/null && exit 1
+
So this one makes sense.
+# A directory that is not there is an error, not a clean tree.
+"${python}" "${jevents}" --check "${tmp}/nodir" > /dev/null 2>&1 && exit 1
+
+# The key is an option, so "--check=DIR" works the same as "--check DIR".
+printf '[{"EventName": "a", "EventCode": "0x1"}]\n' > "${tables}/events.json"
+"${python}" "${jevents}" "--check=${tmp}/arch" > /dev/null || exit 1
+
But these two can be dropped too.
+exit 0