path: root/tools/perf/design.txt
diff options
authorIngo Molnar <>2009-09-21 12:02:48 +0200
committerIngo Molnar <>2009-09-21 14:28:04 +0200
commitcdd6c482c9ff9c55475ee7392ec8f672eddb7be6 (patch)
tree81f98a3ab46c589792057fe2392c1e10f8ad7893 /tools/perf/design.txt
parentdfc65094d0313cc48969fa60bcf33d693aeb05a7 (diff)
perf: Do the big rename: Performance Counters -> Performance Events
Bye-bye Performance Counters, welcome Performance Events! In the past few months the perfcounters subsystem has grown out its initial role of counting hardware events, and has become (and is becoming) a much broader generic event enumeration, reporting, logging, monitoring, analysis facility. Naming its core object 'perf_counter' and naming the subsystem 'perfcounters' has become more and more of a misnomer. With pending code like hw-breakpoints support the 'counter' name is less and less appropriate. All in one, we've decided to rename the subsystem to 'performance events' and to propagate this rename through all fields, variables and API names. (in an ABI compatible fashion) The word 'event' is also a bit shorter than 'counter' - which makes it slightly more convenient to write/handle as well. Thanks goes to Stephane Eranian who first observed this misnomer and suggested a rename. User-space tooling and ABI compatibility is not affected - this patch should be function-invariant. (Also, defconfigs were not touched to keep the size down.) This patch has been generated via the following script: FILES=$(find * -type f | grep -vE 'oprofile|[^K]config') sed -i \ -e 's/PERF_EVENT_/PERF_RECORD_/g' \ -e 's/PERF_COUNTER/PERF_EVENT/g' \ -e 's/perf_counter/perf_event/g' \ -e 's/nb_counters/nb_events/g' \ -e 's/swcounter/swevent/g' \ -e 's/tpcounter_event/tp_event/g' \ $FILES for N in $(find . -name perf_counter.[ch]); do M=$(echo $N | sed 's/perf_counter/perf_event/g') mv $N $M done FILES=$(find . -name perf_event.*) sed -i \ -e 's/COUNTER_MASK/REG_MASK/g' \ -e 's/COUNTER/EVENT/g' \ -e 's/\<event\>/event_id/g' \ -e 's/counter/event/g' \ -e 's/Counter/Event/g' \ $FILES ... to keep it as correct as possible. This script can also be used by anyone who has pending perfcounters patches - it converts a Linux kernel tree over to the new naming. We tried to time this change to the point in time where the amount of pending patches is the smallest: the end of the merge window. Namespace clashes were fixed up in a preparatory patch - and some stylistic fallout will be fixed up in a subsequent patch. ( NOTE: 'counters' are still the proper terminology when we deal with hardware registers - and these sed scripts are a bit over-eager in renaming them. I've undone some of that, but in case there's something left where 'counter' would be better than 'event' we can undo that on an individual basis instead of touching an otherwise nicely automated patch. ) Suggested-by: Stephane Eranian <> Acked-by: Peter Zijlstra <> Acked-by: Paul Mackerras <> Reviewed-by: Arjan van de Ven <> Cc: Mike Galbraith <> Cc: Arnaldo Carvalho de Melo <> Cc: Frederic Weisbecker <> Cc: Steven Rostedt <> Cc: Benjamin Herrenschmidt <> Cc: David Howells <> Cc: Kyle McMartin <> Cc: Martin Schwidefsky <> Cc: "David S. Miller" <> Cc: Thomas Gleixner <> Cc: "H. Peter Anvin" <> Cc: <> LKML-Reference: <new-submission> Signed-off-by: Ingo Molnar <>
Diffstat (limited to 'tools/perf/design.txt')
1 files changed, 29 insertions, 29 deletions
diff --git a/tools/perf/design.txt b/tools/perf/design.txt
index f71e0d245cba..f1946d107b10 100644
--- a/tools/perf/design.txt
+++ b/tools/perf/design.txt
@@ -18,10 +18,10 @@ underlying hardware counters.
Performance counters are accessed via special file descriptors.
There's one file descriptor per virtual counter used.
-The special file descriptor is opened via the perf_counter_open()
+The special file descriptor is opened via the perf_event_open()
system call:
- int sys_perf_counter_open(struct perf_counter_hw_event *hw_event_uptr,
+ int sys_perf_event_open(struct perf_event_hw_event *hw_event_uptr,
pid_t pid, int cpu, int group_fd,
unsigned long flags);
@@ -32,9 +32,9 @@ can be used to set the blocking mode, etc.
Multiple counters can be kept open at a time, and the counters
can be poll()ed.
-When creating a new counter fd, 'perf_counter_hw_event' is:
+When creating a new counter fd, 'perf_event_hw_event' is:
-struct perf_counter_hw_event {
+struct perf_event_hw_event {
* The MSB of the config word signifies if the rest contains cpu
* specific (raw) counter configuration data, if unset, the next
@@ -93,7 +93,7 @@ specified by 'event_id':
* Generalized performance counter event types, used by the hw_event.event_id
- * parameter of the sys_perf_counter_open() syscall:
+ * parameter of the sys_perf_event_open() syscall:
enum hw_event_ids {
@@ -159,7 +159,7 @@ in size.
* reads on the counter should return the indicated quantities,
* in increasing order of bit value, after the counter value.
-enum perf_counter_read_format {
+enum perf_event_read_format {
@@ -178,7 +178,7 @@ interrupt:
* Bits that can be set in hw_event.record_type to request information
* in the overflow packets.
-enum perf_counter_record_format {
+enum perf_event_record_format {
@@ -228,7 +228,7 @@ these events are recorded in the ring-buffer (see below).
The 'comm' bit allows tracking of process comm data on process creation.
This too is recorded in the ring-buffer (see below).
-The 'pid' parameter to the perf_counter_open() system call allows the
+The 'pid' parameter to the perf_event_open() system call allows the
counter to be specific to a task:
pid == 0: if the pid parameter is zero, the counter is attached to the
@@ -258,7 +258,7 @@ The 'flags' parameter is currently unused and must be zero.
The 'group_fd' parameter allows counter "groups" to be set up. A
counter group has one counter which is the group "leader". The leader
-is created first, with group_fd = -1 in the perf_counter_open call
+is created first, with group_fd = -1 in the perf_event_open call
that creates it. The rest of the group members are created
subsequently, with group_fd giving the fd of the group leader.
(A single counter on its own is created with group_fd = -1 and is
@@ -277,13 +277,13 @@ tracking are logged into a ring-buffer. This ring-buffer is created and
accessed through mmap().
The mmap size should be 1+2^n pages, where the first page is a meta-data page
-(struct perf_counter_mmap_page) that contains various bits of information such
+(struct perf_event_mmap_page) that contains various bits of information such
as where the ring-buffer head is.
* Structure of the page that can be mapped via mmap
-struct perf_counter_mmap_page {
+struct perf_event_mmap_page {
__u32 version; /* version number of this structure */
__u32 compat_version; /* lowest version this is compat with */
@@ -317,7 +317,7 @@ struct perf_counter_mmap_page {
* Control data for the mmap() data buffer.
* User-space reading this value should issue an rmb(), on SMP capable
- * platforms, after reading this value -- see perf_counter_wakeup().
+ * platforms, after reading this value -- see perf_event_wakeup().
__u32 data_head; /* head in the data section */
@@ -327,9 +327,9 @@ NOTE: the hw-counter userspace bits are arch specific and are currently only
The following 2^n pages are the ring-buffer which contains events of the form:
-#define PERF_EVENT_MISC_KERNEL (1 << 0)
-#define PERF_EVENT_MISC_USER (1 << 1)
-#define PERF_EVENT_MISC_OVERFLOW (1 << 2)
+#define PERF_RECORD_MISC_KERNEL (1 << 0)
+#define PERF_RECORD_MISC_USER (1 << 1)
struct perf_event_header {
__u32 type;
@@ -353,8 +353,8 @@ enum perf_event_type {
* char filename[];
* };
* struct {
@@ -364,10 +364,10 @@ enum perf_event_type {
* char comm[];
* };
- * When header.misc & PERF_EVENT_MISC_OVERFLOW the event_type field
+ * When header.misc & PERF_RECORD_MISC_OVERFLOW the event_type field
* will be PERF_RECORD_*
* struct {
@@ -397,7 +397,7 @@ Notification of new events is possible through poll()/select()/epoll() and
fcntl() managing signals.
Normally a notification is generated for every page filled, however one can
-additionally set perf_counter_hw_event.wakeup_events to generate one every
+additionally set perf_event_hw_event.wakeup_events to generate one every
so many counter overflow events.
Future work will include a splice() interface to the ring-buffer.
@@ -409,11 +409,11 @@ events but does continue to exist and maintain its count value.
An individual counter or counter group can be enabled with
or disabled with
Enabling or disabling the leader of a group enables or disables the
whole group; that is, while the group leader is disabled, none of the
@@ -424,16 +424,16 @@ other counter.
Additionally, non-inherited overflow counters can use
- ioctl(fd, PERF_COUNTER_IOC_REFRESH, nr);
+ ioctl(fd, PERF_EVENT_IOC_REFRESH, nr);
to enable a counter for 'nr' events, after which it gets disabled again.
A process can enable or disable all the counter groups that are
attached to it, using prctl:
This applies to all counters on the current process, whether created
by this process or by another, and doesn't affect any counters that
@@ -447,11 +447,11 @@ Arch requirements
If your architecture does not have hardware performance metrics, you can
still use the generic software counters based on hrtimers for sampling.
-So to start with, in order to add HAVE_PERF_COUNTERS to your Kconfig, you
+So to start with, in order to add HAVE_PERF_EVENTS to your Kconfig, you
will need at least this:
- - asm/perf_counter.h - a basic stub will suffice at first
+ - asm/perf_event.h - a basic stub will suffice at first
- support for atomic64 types (and associated helper functions)
- - set_perf_counter_pending() implemented
+ - set_perf_event_pending() implemented
If your architecture does have hardware capabilities, you can override the
-weak stub hw_perf_counter_init() to register hardware counters.
+weak stub hw_perf_event_init() to register hardware counters.