Skip to contentSkip to conversation

perf tools: Update JSON event description

RFC In review Namhyung Kim 2 participants 3 messages Oct 27, 2025 – Oct 31, 2025 perf events

lore
Share & tools
lore

Namhyung Kim

author maintainer
#0 lore raw

RFC 1/1 perf tools: Update JSON event description

Hi Ian,

I'm trying to make this change in the JSON description for hardware and software events. But I got a build failure in the empty-pmu-events.c even after I re-generated it like below.

cd pmu-events
./jevents.py none none $PWD empty-pmu-events.c

Did I miss something?

Thanks,
Namhyung

tools/perf/pmu-events/arch/common/common/legacy-hardware.json +8 -8
index 71700647f19b1866..c249bdef818688b2 100644
@@ -1,12 +1,12 @@
 [
   {
     "EventName": "cpu-cycles",
-    "BriefDescription": "Total cycles. Be wary of what happens during CPU frequency scaling [This event is an alias of cycles].",
+    "BriefDescription": "Total cycles. Be wary of what happens during CPU frequency scaling.",
     "LegacyConfigCode": "0"
   },
   {
     "EventName": "cycles",
-    "BriefDescription": "Total cycles. Be wary of what happens during CPU frequency scaling [This event is an alias of cpu-cycles].",
+    "BriefDescription": "This event is an alias of cpu-cycles.",
     "LegacyConfigCode": "0"
   },
   {
@@ -26,12 +26,12 @@
   },
   {
     "EventName": "branches",
-    "BriefDescription": "Retired branch instructions [This event is an alias of branch-instructions].",
+    "BriefDescription": "This event is an alias of branch-instructions.",
     "LegacyConfigCode": "4"
   },
   {
     "EventName": "branch-instructions",
-    "BriefDescription": "Retired branch instructions [This event is an alias of branches].",
+    "BriefDescription": "Retired branch instructions.",
     "LegacyConfigCode": "4"
   },
   {
@@ -46,22 +46,22 @@
   },
   {
     "EventName": "stalled-cycles-frontend",
-    "BriefDescription": "Stalled cycles during issue [This event is an alias of idle-cycles-frontend].",
+    "BriefDescription": "Stalled cycles during issue.",
     "LegacyConfigCode": "7"
   },
   {
     "EventName": "idle-cycles-frontend",
-    "BriefDescription": "Stalled cycles during issue [This event is an alias of stalled-cycles-fronted].",
+    "BriefDescription": "This event is an alias of stalled-cycles-fronted.",
     "LegacyConfigCode": "7"
   },
   {
     "EventName": "stalled-cycles-backend",
-    "BriefDescription": "Stalled cycles during retirement [This event is an alias of idle-cycles-backend].",
+    "BriefDescription": "Stalled cycles during retirement.",
     "LegacyConfigCode": "8"
   },
   {
     "EventName": "idle-cycles-backend",
-    "BriefDescription": "Stalled cycles during retirement [This event is an alias of stalled-cycles-backend].",
+    "BriefDescription": "This event is an alias of stalled-cycles-backend.",
     "LegacyConfigCode": "8"
   },
   {
tools/perf/pmu-events/arch/common/common/software.json +6 -6
index f2551f1107fd712c..48b31acf402ca325 100644
@@ -14,37 +14,37 @@
   {
     "Unit": "software",
     "EventName": "faults",
-    "BriefDescription": "Number of page faults [This event is an alias of page-faults]",
+    "BriefDescription": "This event is an alias of page-faults",
     "ConfigCode": "2"
   },
   {
     "Unit": "software",
     "EventName": "page-faults",
-    "BriefDescription": "Number of page faults [This event is an alias of faults]",
+    "BriefDescription": "Number of page faults",
     "ConfigCode": "2"
   },
   {
     "Unit": "software",
     "EventName": "context-switches",
-    "BriefDescription": "Number of context switches [This event is an alias of cs]",
+    "BriefDescription": "Number of context switches",
     "ConfigCode": "3"
   },
   {
     "Unit": "software",
     "EventName": "cs",
-    "BriefDescription": "Number of context switches [This event is an alias of context-switches]",
+    "BriefDescription": "This event is an alias of context-switches",
     "ConfigCode": "3"
   },
   {
     "Unit": "software",
     "EventName": "cpu-migrations",
-    "BriefDescription": "Number of times a process has migrated to a new CPU [This event is an alias of migrations]",
+    "BriefDescription": "Number of times a process has migrated to a new CPU",
     "ConfigCode": "4"
   },
   {
     "Unit": "software",
     "EventName": "migrations",
-    "BriefDescription": "Number of times a process has migrated to a new CPU [This event is an alias of cpu-migrations]",
+    "BriefDescription": "This event is an alias of cpu-migrations",
     "ConfigCode": "4"
   },
   {
reviewer
#1 lore raw
Quoted 11 lines · Namhyung Kim

Hi Ian,

I'm trying to make this change in the JSON description for hardware and software events. But I got a build failure in the empty-pmu-events.c even after I re-generated it like below.

cd pmu-events
./jevents.py none none $PWD empty-pmu-events.c

Did I miss something?

So the build failure/diff has the path to the generated empty-pmu-events.c. I'd copy that file rather than try to recreate the command line - although there should be no reason generating the command line fails it looks to me that you need to pass "$PWD/arch" rather than "$PWD":
https://web.git.kernel.org/pub/scm/linux/kernel/git/perf/perf-tools-next.git/tree/tools/perf/pmu-events/Build?h=tmp.perf-tools-next#n51
Fwiw, the formatting in legacy-hardware.json was based on Intel doing the same thing and not wanting to start new conventions:
https://web.git.kernel.org/pub/scm/linux/kernel/git/perf/perf-tools-next.git/tree/tools/perf/pmu-events/arch/x86/skylakex/pipeline.json?h=tmp.perf-tools-next#n32

```
    {
        "BriefDescription": "Conditional branch instructions retired.
[This event is alias to BR_INST_RETIRED.CONDITIONAL]",
        "Counter": "0,1,2,3",
        "Errata": "SKL091",
        "EventCode": "0xC4",
        "EventName": "BR_INST_RETIRED.COND",
        "PublicDescription": "This event counts conditional branch
instructions retired. [This event is alias to
BR_INST_RETIRED.CONDITIONAL]",
        "SampleAfterValue": "400009",
        "UMask": "0x1"
    },
    {
        "BriefDescription": "Conditional branch instructions retired.
[This event is alias to BR_INST_RETIRED.COND]",
        "Counter": "0,1,2,3",
        "Errata": "SKL091",
        "EventCode": "0xC4",
        "EventName": "BR_INST_RETIRED.CONDITIONAL",
        "PEBS": "1",
        "PublicDescription": "This event counts conditional branch
instructions retired. [This event is alias to BR_INST_RETIRED.COND]",
        "SampleAfterValue": "400009",
        "UMask": "0x1"
    },
```

As the order of seeing events isn't well defined, I'm not sure what we gain by shorter descriptions and it could be frustrating for a user to see that 'cycles' definition is in effect a redirection.

Thanks,
Ian

author maintainer
#2 lore raw
Quoted 8 lines · Ian Rogers
Quoted 7 lines · Namhyung Kim

Hi Ian,

I'm trying to make this change in the JSON description for hardware and software events. But I got a build failure in the empty-pmu-events.c even after I re-generated it like below.

Quoted 7 lines
Quoted 4 lines

cd pmu-events
./jevents.py none none $PWD empty-pmu-events.c

Did I miss something?

So the build failure/diff has the path to the generated empty-pmu-events.c. I'd copy that file rather than try to recreate the

I see.

Quoted 35 lines

command line - although there should be no reason generating the command line fails it looks to me that you need to pass "$PWD/arch" rather than "$PWD":
https://web.git.kernel.org/pub/scm/linux/kernel/git/perf/perf-tools-next.git/tree/tools/perf/pmu-events/Build?h=tmp.perf-tools-next#n51
Fwiw, the formatting in legacy-hardware.json was based on Intel doing the same thing and not wanting to start new conventions:
https://web.git.kernel.org/pub/scm/linux/kernel/git/perf/perf-tools-next.git/tree/tools/perf/pmu-events/arch/x86/skylakex/pipeline.json?h=tmp.perf-tools-next#n32

```
    {
        "BriefDescription": "Conditional branch instructions retired.
[This event is alias to BR_INST_RETIRED.CONDITIONAL]",
        "Counter": "0,1,2,3",
        "Errata": "SKL091",
        "EventCode": "0xC4",
        "EventName": "BR_INST_RETIRED.COND",
        "PublicDescription": "This event counts conditional branch
instructions retired. [This event is alias to
BR_INST_RETIRED.CONDITIONAL]",
        "SampleAfterValue": "400009",
        "UMask": "0x1"
    },
    {
        "BriefDescription": "Conditional branch instructions retired.
[This event is alias to BR_INST_RETIRED.COND]",
        "Counter": "0,1,2,3",
        "Errata": "SKL091",
        "EventCode": "0xC4",
        "EventName": "BR_INST_RETIRED.CONDITIONAL",
        "PEBS": "1",
        "PublicDescription": "This event counts conditional branch
instructions retired. [This event is alias to BR_INST_RETIRED.COND]",
        "SampleAfterValue": "400009",
        "UMask": "0x1"
    },
```
Quoted 3 lines

As the order of seeing events isn't well defined, I'm not sure what we gain by shorter descriptions and it could be frustrating for a user to see that 'cycles' definition is in effect a redirection.

I generally prefer short and clear descriptions and feel better to remove duplications. But I don't want to change the vendor JSON and this change is not important so I can drop it.

Thanks,
Namhyung