[linux-2.6-block.git] / tools / perf / pmu-events / README


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.

	- The CSV file that maps a specific CPU to its set of PMU events is to
	  be named 'mapfile.csv' (see below for mapfile format).

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

	- To reduce JSON event duplication per architecture, platform JSONs may
	  use "ArchStdEvent" keyword to dereference an "Architecture standard
	  events", defined in architecture standard JSONs.
	  Architecture standard JSONs must be located in the architecture root
	  folder. Matching is based on the "EventName" field.

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

The JSONs folder for a CPU model/family may be placed in the root arch
folder, or may be placed in a vendor sub-folder under the arch folder
for instances where the arch and vendor are not the same.

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'.
Commit	Line	Data
06d839b4 SB	1
	2	The contents of this directory allow users to specify PMU events in their
	3	CPUs by their symbolic names rather than raw event codes (see example below).
	4
	5	The main program in this directory, is the 'jevents', which is built and
	6	executed _BEFORE_ the perf binary itself is built.
	7
	8	The 'jevents' program tries to locate and process JSON files in the directory
	9	tree tools/perf/pmu-events/arch/foo.
	10
	11	- Regular files with '.json' extension in the name are assumed to be
	12	JSON files, each of which describes a set of PMU events.
	13
4c0ab160 JG	14	- The CSV file that maps a specific CPU to its set of PMU events is to
4c0ab160 JG	15	be named 'mapfile.csv' (see below for mapfile format).
06d839b4 SB	16
	17	- Directories are traversed, but all other files are ignored.
	18
e9d32c1b JG	19	- To reduce JSON event duplication per architecture, platform JSONs may
	20	use "ArchStdEvent" keyword to dereference an "Architecture standard
	21	events", defined in architecture standard JSONs.
	22	Architecture standard JSONs must be located in the architecture root
	23	folder. Matching is based on the "EventName" field.
	24
06d839b4 SB	25	The PMU events supported by a CPU model are expected to grouped into topics
	26	such as Pipelining, Cache, Memory, Floating-point etc. All events for a topic
	27	should be placed in a separate JSON file - where the file name identifies
	28	the topic. Eg: "Floating-point.json".
	29
	30	All the topic JSON files for a CPU model/family should be in a separate
	31	sub directory. Thus for the Silvermont X86 CPU:
	32
	33	$ ls tools/perf/pmu-events/arch/x86/Silvermont_core
	34	Cache.json Memory.json Virtual-Memory.json
	35	Frontend.json Pipeline.json
	36
51ce1dcc JG	37	The JSONs folder for a CPU model/family may be placed in the root arch
	38	folder, or may be placed in a vendor sub-folder under the arch folder
	39	for instances where the arch and vendor are not the same.
	40
06d839b4 SB	41	Using the JSON files and the mapfile, 'jevents' generates the C source file,
	42	'pmu-events.c', which encodes the two sets of tables:
	43
	44	- Set of 'PMU events tables' for all known CPUs in the architecture,
	45	(one table like the following, per JSON file; table name 'pme_power8'
	46	is derived from JSON file name, 'power8.json').
	47
	48	struct pmu_event pme_power8[] = {
	49
	50	...
	51
	52	{
	53	.name = "pm_1plus_ppc_cmpl",
	54	.event = "event=0x100f2",
	55	.desc = "1 or more ppc insts finished,",
	56	},
	57
	58	...
	59	}
	60
	61	- A 'mapping table' that maps each CPU of the architecture, to its
	62	'PMU events table'
	63
	64	struct pmu_events_map pmu_events_map[] = {
	65	{
	66	.cpuid = "004b0000",
	67	.version = "1",
	68	.type = "core",
	69	.table = pme_power8
	70	},
	71	...
	72
	73	};
	74
	75	After the 'pmu-events.c' is generated, it is compiled and the resulting
	76	'pmu-events.o' is added to 'libperf.a' which is then used to build perf.
	77
	78	NOTES:
	79	1. Several CPUs can support same set of events and hence use a common
	80	JSON file. Hence several entries in the pmu_events_map[] could map
	81	to a single 'PMU events table'.
	82
	83	2. The 'pmu-events.h' has an extern declaration for the mapping table
	84	and the generated 'pmu-events.c' defines this table.
	85
	86	3. _All_ known CPU tables for architecture are included in the perf
	87	binary.
	88
	89	At run time, perf determines the actual CPU it is running on, finds the
	90	matching events table and builds aliases for those events. This allows
	91	users to specify events by their name:
	92
	93	$ perf stat -e pm_1plus_ppc_cmpl sleep 1
	94
	95	where 'pm_1plus_ppc_cmpl' is a Power8 PMU event.
	96
06d839b4 SB	97	However some errors in processing may cause the perf build to fail.
	98
	99	Mapfile format
	100	===============
	101
	102	The mapfile enables multiple CPU models to share a single set of PMU events.
	103	It is required even if such mapping is 1:1.
	104
	105	The mapfile.csv format is expected to be:
	106
	107	Header line
	108	CPUID,Version,Dir/path/name,Type
	109
	110	where:
	111
	112	Comma:
	113	is the required field delimiter (i.e other fields cannot
	114	have commas within them).
	115
	116	Comments:
	117	Lines in which the first character is either '\n' or '#'
	118	are ignored.
	119
	120	Header line
	121	The header line is the first line in the file, which is
	122	always _IGNORED_. It can empty.
	123
	124	CPUID:
	125	CPUID is an arch-specific char string, that can be used
	126	to identify CPU (and associate it with a set of PMU events
	127	it supports). Multiple CPUIDS can point to the same
	128	File/path/name.json.
	129
	130	Example:
	131	CPUID == 'GenuineIntel-6-2E' (on x86).
	132	CPUID == '004b0100' (PVR value in Powerpc)
	133	Version:
	134	is the Version of the mapfile.
	135
	136	Dir/path/name:
	137	is the pathname to the directory containing the CPU's JSON
	138	files, relative to the directory containing the mapfile.csv
	139
	140	Type:
	141	indicates whether the events or "core" or "uncore" events.
	142
	143
	144	Eg:
	145
	146	$ grep Silvermont tools/perf/pmu-events/arch/x86/mapfile.csv
	147	GenuineIntel-6-37,V13,Silvermont_core,core
	148	GenuineIntel-6-4D,V13,Silvermont_core,core
	149	GenuineIntel-6-4C,V13,Silvermont_core,core
	150
	151	i.e the three CPU models use the JSON files (i.e PMU events) listed
	152	in the directory 'tools/perf/pmu-events/arch/x86/Silvermont_core'.