linux/tools/perf/pmu-events
William Cohen 0b7c1528fb perf vendor events aarch64: Add JSON metrics for ARM Cortex-A53 Processor
Add JSON metrics for ARM Cortex-A53 Processor.

Unlike the Intel processors there isn't a script that automatically
generated these files. The patch was manually generated from the
documentation and the previous oprofile ARM Cortex ac53 event file patch
I made.

The relevant documentation is in the "12.9 Events" section of the ARM
Cortex A53 MPCore Processor Revision: r0p4 Technical Reference Manual.

The ARM Cortex A53 manual is available at:

  http://infocenter.arm.com/help/topic/com.arm.doc.ddi0500g/DDI0500G_cortex_a53_trm.pdf

Use that to look for additional information about the events.

Signed-off-by: William Cohen <wcohen@redhat.com>
Cc: Alexander Shishkin <alexander.shishkin@linux.intel.com>
Cc: Jiri Olsa <jolsa@redhat.com>
Cc: Namhyung Kim <namhyung@kernel.org>
Cc: Peter Zijlstra <peterz@infradead.org>
Link: http://lkml.kernel.org/r/20180131032813.9564-1-wcohen@redhat.com
[ Added references provided by William Cohen ]
Signed-off-by: Arnaldo Carvalho de Melo <acme@redhat.com>
2018-02-15 09:49:44 -03:00
..
arch perf vendor events aarch64: Add JSON metrics for ARM Cortex-A53 Processor 2018-02-15 09:49:44 -03:00
Build perf tools: Fix build with ARCH=x86_64 2017-06-14 15:44:29 -03:00
jevents.c perf vendor events: Use more flexible pattern matching for CPU identification for mapfile.csv 2017-12-05 15:43:55 -03:00
jevents.h Merge branch 'linus' into perf/core, to fix conflicts 2017-11-07 10:30:18 +01:00
jsmn.c perf tools: Add jsmn `jasmine' JSON parser 2016-10-03 11:40:36 -03:00
jsmn.h License cleanup: add SPDX GPL-2.0 license identifier to files with no license 2017-11-02 11:10:55 +01:00
json.c perf utils: Check verbose flag properly 2017-02-20 11:35:54 -03:00
json.h License cleanup: add SPDX GPL-2.0 license identifier to files with no license 2017-11-02 11:10:55 +01:00
pmu-events.h Merge branch 'linus' into perf/core, to fix conflicts 2017-11-07 10:30:18 +01:00
README perf jevents: Make build fail on JSON parse error 2017-07-25 22:46:36 -03:00

The contents of this directory allow users to specify PMU events in their
CPUs by their symbolic names rather than raw event codes (see example below).

The main program in this directory, is the 'jevents', which is built and
executed _BEFORE_ the perf binary itself is built.

The 'jevents' program tries to locate and process JSON files in the directory
tree tools/perf/pmu-events/arch/foo.

	- Regular files with '.json' extension in the name are assumed to be
	  JSON files, each of which describes a set of PMU events.

	- Regular files with basename starting with 'mapfile.csv' are assumed
	  to be a CSV file that maps a specific CPU to its set of PMU events.
	  (see below for mapfile format)

	- Directories are traversed, but all other files are ignored.

The PMU events supported by a CPU model are expected to grouped into topics
such as Pipelining, Cache, Memory, Floating-point etc. All events for a topic
should be placed in a separate JSON file - where the file name identifies
the topic. Eg: "Floating-point.json".

All the topic JSON files for a CPU model/family should be in a separate
sub directory. Thus for the Silvermont X86 CPU:

	$ ls tools/perf/pmu-events/arch/x86/Silvermont_core
	Cache.json 	Memory.json 	Virtual-Memory.json
	Frontend.json 	Pipeline.json

Using the JSON files and the mapfile, 'jevents' generates the C source file,
'pmu-events.c', which encodes the two sets of tables:

	- Set of 'PMU events tables' for all known CPUs in the architecture,
	  (one table like the following, per JSON file; table name 'pme_power8'
	  is derived from JSON file name, 'power8.json').

		struct pmu_event pme_power8[] = {

			...

			{
				.name = "pm_1plus_ppc_cmpl",
				.event = "event=0x100f2",
				.desc = "1 or more ppc insts finished,",
			},

			...
		}

	- A 'mapping table' that maps each CPU of the architecture, to its
	  'PMU events table'

		struct pmu_events_map pmu_events_map[] = {
		{
			.cpuid = "004b0000",
			.version = "1",
			.type = "core",
			.table = pme_power8
		},
			...

		};

After the 'pmu-events.c' is generated, it is compiled and the resulting
'pmu-events.o' is added to 'libperf.a' which is then used to build perf.

NOTES:
	1. Several CPUs can support same set of events and hence use a common
	   JSON file. Hence several entries in the pmu_events_map[] could map
	   to a single 'PMU events table'.

	2. The 'pmu-events.h' has an extern declaration for the mapping table
	   and the generated 'pmu-events.c' defines this table.

	3. _All_ known CPU tables for architecture are included in the perf
	   binary.

At run time, perf determines the actual CPU it is running on, finds the
matching events table and builds aliases for those events. This allows
users to specify events by their name:

	$ perf stat -e pm_1plus_ppc_cmpl sleep 1

where 'pm_1plus_ppc_cmpl' is a Power8 PMU event.

However some errors in processing may cause the perf build to fail.

Mapfile format
===============

The mapfile enables multiple CPU models to share a single set of PMU events.
It is required even if such mapping is 1:1.

The mapfile.csv format is expected to be:

	Header line
	CPUID,Version,Dir/path/name,Type

where:

	Comma:
		is the required field delimiter (i.e other fields cannot
		have commas within them).

	Comments:
		Lines in which the first character is either '\n' or '#'
		are ignored.

	Header line
		The header line is the first line in the file, which is
		always _IGNORED_. It can empty.

	CPUID:
		CPUID is an arch-specific char string, that can be used
		to identify CPU (and associate it with a set of PMU events
		it supports). Multiple CPUIDS can point to the same
		File/path/name.json.

		Example:
			CPUID == 'GenuineIntel-6-2E' (on x86).
			CPUID == '004b0100' (PVR value in Powerpc)
	Version:
		is the Version of the mapfile.

	Dir/path/name:
		is the pathname to the directory containing the CPU's JSON
		files, relative to the directory containing the mapfile.csv

	Type:
		indicates whether the events or "core" or "uncore" events.


	Eg:

	$ grep Silvermont tools/perf/pmu-events/arch/x86/mapfile.csv
	GenuineIntel-6-37,V13,Silvermont_core,core
	GenuineIntel-6-4D,V13,Silvermont_core,core
	GenuineIntel-6-4C,V13,Silvermont_core,core

	i.e the three CPU models use the JSON files (i.e PMU events) listed
	in the directory 'tools/perf/pmu-events/arch/x86/Silvermont_core'.