[RFC] perf tools: Update JSON event description

[RFC] perf tools: Update JSON event description

[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?

Thanks,
Namhyung


diff --git a/tools/perf/pmu-events/arch/common/common/legacy-hardware.json b/tools/perf/pmu-events/arch/common/common/legacy-hardware.json
index 71700647f19b1866..c249bdef818688b2 100644
--- a/tools/perf/pmu-events/arch/common/common/legacy-hardware.json
+++ b/tools/perf/pmu-events/arch/common/common/legacy-hardware.json
@@ -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"
   },
   {
diff --git a/tools/perf/pmu-events/arch/common/common/software.json b/tools/perf/pmu-events/arch/common/common/software.json
index f2551f1107fd712c..48b31acf402ca325 100644
--- a/tools/perf/pmu-events/arch/common/common/software.json
+++ b/tools/perf/pmu-events/arch/common/common/software.json
@@ -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"
   },
   {

Re: [RFC] perf tools: Update JSON event description

[Ian Rogers]

On Mon, Oct 27, 2025 at 11:58 AM Namhyung Kim <namhyung@kernel.org> wrote:
>
> 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

Re: [RFC] perf tools: Update JSON event description

[Namhyung Kim]

On Wed, Oct 29, 2025 at 08:28:34AM -0700, Ian Rogers wrote:
> On Mon, Oct 27, 2025 at 11:58 AM Namhyung Kim <namhyung@kernel.org> wrote:
> >
> > 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

I see.

> 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.

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