diff options
Diffstat (limited to 'tools/perf/design.txt')
-rw-r--r-- | tools/perf/design.txt | 58 |
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. | |||
18 | Performance counters are accessed via special file descriptors. | 18 | Performance counters are accessed via special file descriptors. |
19 | There's one file descriptor per virtual counter used. | 19 | There's one file descriptor per virtual counter used. |
20 | 20 | ||
21 | The special file descriptor is opened via the perf_counter_open() | 21 | The special file descriptor is opened via the perf_event_open() |
22 | system call: | 22 | system call: |
23 | 23 | ||
24 | int sys_perf_counter_open(struct perf_counter_hw_event *hw_event_uptr, | 24 | int sys_perf_event_open(struct perf_event_hw_event *hw_event_uptr, |
25 | pid_t pid, int cpu, int group_fd, | 25 | pid_t pid, int cpu, int group_fd, |
26 | unsigned long flags); | 26 | unsigned long flags); |
27 | 27 | ||
@@ -32,9 +32,9 @@ can be used to set the blocking mode, etc. | |||
32 | Multiple counters can be kept open at a time, and the counters | 32 | Multiple counters can be kept open at a time, and the counters |
33 | can be poll()ed. | 33 | can be poll()ed. |
34 | 34 | ||
35 | When creating a new counter fd, 'perf_counter_hw_event' is: | 35 | When creating a new counter fd, 'perf_event_hw_event' is: |
36 | 36 | ||
37 | struct perf_counter_hw_event { | 37 | struct perf_event_hw_event { |
38 | /* | 38 | /* |
39 | * The MSB of the config word signifies if the rest contains cpu | 39 | * The MSB of the config word signifies if the rest contains cpu |
40 | * specific (raw) counter configuration data, if unset, the next | 40 | * specific (raw) counter configuration data, if unset, the next |
@@ -93,7 +93,7 @@ specified by 'event_id': | |||
93 | 93 | ||
94 | /* | 94 | /* |
95 | * Generalized performance counter event types, used by the hw_event.event_id | 95 | * Generalized performance counter event types, used by the hw_event.event_id |
96 | * parameter of the sys_perf_counter_open() syscall: | 96 | * parameter of the sys_perf_event_open() syscall: |
97 | */ | 97 | */ |
98 | enum hw_event_ids { | 98 | enum hw_event_ids { |
99 | /* | 99 | /* |
@@ -159,7 +159,7 @@ in size. | |||
159 | * reads on the counter should return the indicated quantities, | 159 | * reads on the counter should return the indicated quantities, |
160 | * in increasing order of bit value, after the counter value. | 160 | * in increasing order of bit value, after the counter value. |
161 | */ | 161 | */ |
162 | enum perf_counter_read_format { | 162 | enum perf_event_read_format { |
163 | PERF_FORMAT_TOTAL_TIME_ENABLED = 1, | 163 | PERF_FORMAT_TOTAL_TIME_ENABLED = 1, |
164 | PERF_FORMAT_TOTAL_TIME_RUNNING = 2, | 164 | PERF_FORMAT_TOTAL_TIME_RUNNING = 2, |
165 | }; | 165 | }; |
@@ -178,7 +178,7 @@ interrupt: | |||
178 | * Bits that can be set in hw_event.record_type to request information | 178 | * Bits that can be set in hw_event.record_type to request information |
179 | * in the overflow packets. | 179 | * in the overflow packets. |
180 | */ | 180 | */ |
181 | enum perf_counter_record_format { | 181 | enum perf_event_record_format { |
182 | PERF_RECORD_IP = 1U << 0, | 182 | PERF_RECORD_IP = 1U << 0, |
183 | PERF_RECORD_TID = 1U << 1, | 183 | PERF_RECORD_TID = 1U << 1, |
184 | PERF_RECORD_TIME = 1U << 2, | 184 | PERF_RECORD_TIME = 1U << 2, |
@@ -228,7 +228,7 @@ these events are recorded in the ring-buffer (see below). | |||
228 | The 'comm' bit allows tracking of process comm data on process creation. | 228 | The 'comm' bit allows tracking of process comm data on process creation. |
229 | This too is recorded in the ring-buffer (see below). | 229 | This too is recorded in the ring-buffer (see below). |
230 | 230 | ||
231 | The 'pid' parameter to the perf_counter_open() system call allows the | 231 | The 'pid' parameter to the perf_event_open() system call allows the |
232 | counter to be specific to a task: | 232 | counter to be specific to a task: |
233 | 233 | ||
234 | pid == 0: if the pid parameter is zero, the counter is attached to the | 234 | 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. | |||
258 | 258 | ||
259 | The 'group_fd' parameter allows counter "groups" to be set up. A | 259 | The 'group_fd' parameter allows counter "groups" to be set up. A |
260 | counter group has one counter which is the group "leader". The leader | 260 | counter group has one counter which is the group "leader". The leader |
261 | is created first, with group_fd = -1 in the perf_counter_open call | 261 | is created first, with group_fd = -1 in the perf_event_open call |
262 | that creates it. The rest of the group members are created | 262 | that creates it. The rest of the group members are created |
263 | subsequently, with group_fd giving the fd of the group leader. | 263 | subsequently, with group_fd giving the fd of the group leader. |
264 | (A single counter on its own is created with group_fd = -1 and is | 264 | (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 | |||
277 | accessed through mmap(). | 277 | accessed through mmap(). |
278 | 278 | ||
279 | The mmap size should be 1+2^n pages, where the first page is a meta-data page | 279 | The mmap size should be 1+2^n pages, where the first page is a meta-data page |
280 | (struct perf_counter_mmap_page) that contains various bits of information such | 280 | (struct perf_event_mmap_page) that contains various bits of information such |
281 | as where the ring-buffer head is. | 281 | as where the ring-buffer head is. |
282 | 282 | ||
283 | /* | 283 | /* |
284 | * Structure of the page that can be mapped via mmap | 284 | * Structure of the page that can be mapped via mmap |
285 | */ | 285 | */ |
286 | struct perf_counter_mmap_page { | 286 | struct perf_event_mmap_page { |
287 | __u32 version; /* version number of this structure */ | 287 | __u32 version; /* version number of this structure */ |
288 | __u32 compat_version; /* lowest version this is compat with */ | 288 | __u32 compat_version; /* lowest version this is compat with */ |
289 | 289 | ||
@@ -317,7 +317,7 @@ struct perf_counter_mmap_page { | |||
317 | * Control data for the mmap() data buffer. | 317 | * Control data for the mmap() data buffer. |
318 | * | 318 | * |
319 | * User-space reading this value should issue an rmb(), on SMP capable | 319 | * User-space reading this value should issue an rmb(), on SMP capable |
320 | * platforms, after reading this value -- see perf_counter_wakeup(). | 320 | * platforms, after reading this value -- see perf_event_wakeup(). |
321 | */ | 321 | */ |
322 | __u32 data_head; /* head in the data section */ | 322 | __u32 data_head; /* head in the data section */ |
323 | }; | 323 | }; |
@@ -327,9 +327,9 @@ NOTE: the hw-counter userspace bits are arch specific and are currently only | |||
327 | 327 | ||
328 | The following 2^n pages are the ring-buffer which contains events of the form: | 328 | The following 2^n pages are the ring-buffer which contains events of the form: |
329 | 329 | ||
330 | #define PERF_EVENT_MISC_KERNEL (1 << 0) | 330 | #define PERF_RECORD_MISC_KERNEL (1 << 0) |
331 | #define PERF_EVENT_MISC_USER (1 << 1) | 331 | #define PERF_RECORD_MISC_USER (1 << 1) |
332 | #define PERF_EVENT_MISC_OVERFLOW (1 << 2) | 332 | #define PERF_RECORD_MISC_OVERFLOW (1 << 2) |
333 | 333 | ||
334 | struct perf_event_header { | 334 | struct perf_event_header { |
335 | __u32 type; | 335 | __u32 type; |
@@ -353,8 +353,8 @@ enum perf_event_type { | |||
353 | * char filename[]; | 353 | * char filename[]; |
354 | * }; | 354 | * }; |
355 | */ | 355 | */ |
356 | PERF_EVENT_MMAP = 1, | 356 | PERF_RECORD_MMAP = 1, |
357 | PERF_EVENT_MUNMAP = 2, | 357 | PERF_RECORD_MUNMAP = 2, |
358 | 358 | ||
359 | /* | 359 | /* |
360 | * struct { | 360 | * struct { |
@@ -364,10 +364,10 @@ enum perf_event_type { | |||
364 | * char comm[]; | 364 | * char comm[]; |
365 | * }; | 365 | * }; |
366 | */ | 366 | */ |
367 | PERF_EVENT_COMM = 3, | 367 | PERF_RECORD_COMM = 3, |
368 | 368 | ||
369 | /* | 369 | /* |
370 | * When header.misc & PERF_EVENT_MISC_OVERFLOW the event_type field | 370 | * When header.misc & PERF_RECORD_MISC_OVERFLOW the event_type field |
371 | * will be PERF_RECORD_* | 371 | * will be PERF_RECORD_* |
372 | * | 372 | * |
373 | * struct { | 373 | * struct { |
@@ -397,7 +397,7 @@ Notification of new events is possible through poll()/select()/epoll() and | |||
397 | fcntl() managing signals. | 397 | fcntl() managing signals. |
398 | 398 | ||
399 | Normally a notification is generated for every page filled, however one can | 399 | Normally a notification is generated for every page filled, however one can |
400 | additionally set perf_counter_hw_event.wakeup_events to generate one every | 400 | additionally set perf_event_hw_event.wakeup_events to generate one every |
401 | so many counter overflow events. | 401 | so many counter overflow events. |
402 | 402 | ||
403 | Future work will include a splice() interface to the ring-buffer. | 403 | 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. | |||
409 | 409 | ||
410 | An individual counter or counter group can be enabled with | 410 | An individual counter or counter group can be enabled with |
411 | 411 | ||
412 | ioctl(fd, PERF_COUNTER_IOC_ENABLE); | 412 | ioctl(fd, PERF_EVENT_IOC_ENABLE); |
413 | 413 | ||
414 | or disabled with | 414 | or disabled with |
415 | 415 | ||
416 | ioctl(fd, PERF_COUNTER_IOC_DISABLE); | 416 | ioctl(fd, PERF_EVENT_IOC_DISABLE); |
417 | 417 | ||
418 | Enabling or disabling the leader of a group enables or disables the | 418 | Enabling or disabling the leader of a group enables or disables the |
419 | whole group; that is, while the group leader is disabled, none of the | 419 | whole group; that is, while the group leader is disabled, none of the |
@@ -424,16 +424,16 @@ other counter. | |||
424 | 424 | ||
425 | Additionally, non-inherited overflow counters can use | 425 | Additionally, non-inherited overflow counters can use |
426 | 426 | ||
427 | ioctl(fd, PERF_COUNTER_IOC_REFRESH, nr); | 427 | ioctl(fd, PERF_EVENT_IOC_REFRESH, nr); |
428 | 428 | ||
429 | to enable a counter for 'nr' events, after which it gets disabled again. | 429 | to enable a counter for 'nr' events, after which it gets disabled again. |
430 | 430 | ||
431 | A process can enable or disable all the counter groups that are | 431 | A process can enable or disable all the counter groups that are |
432 | attached to it, using prctl: | 432 | attached to it, using prctl: |
433 | 433 | ||
434 | prctl(PR_TASK_PERF_COUNTERS_ENABLE); | 434 | prctl(PR_TASK_PERF_EVENTS_ENABLE); |
435 | 435 | ||
436 | prctl(PR_TASK_PERF_COUNTERS_DISABLE); | 436 | prctl(PR_TASK_PERF_EVENTS_DISABLE); |
437 | 437 | ||
438 | This applies to all counters on the current process, whether created | 438 | This applies to all counters on the current process, whether created |
439 | by this process or by another, and doesn't affect any counters that | 439 | by this process or by another, and doesn't affect any counters that |
@@ -447,11 +447,11 @@ Arch requirements | |||
447 | If your architecture does not have hardware performance metrics, you can | 447 | If your architecture does not have hardware performance metrics, you can |
448 | still use the generic software counters based on hrtimers for sampling. | 448 | still use the generic software counters based on hrtimers for sampling. |
449 | 449 | ||
450 | So to start with, in order to add HAVE_PERF_COUNTERS to your Kconfig, you | 450 | So to start with, in order to add HAVE_PERF_EVENTS to your Kconfig, you |
451 | will need at least this: | 451 | will need at least this: |
452 | - asm/perf_counter.h - a basic stub will suffice at first | 452 | - asm/perf_event.h - a basic stub will suffice at first |
453 | - support for atomic64 types (and associated helper functions) | 453 | - support for atomic64 types (and associated helper functions) |
454 | - set_perf_counter_pending() implemented | 454 | - set_perf_event_pending() implemented |
455 | 455 | ||
456 | If your architecture does have hardware capabilities, you can override the | 456 | If your architecture does have hardware capabilities, you can override the |
457 | weak stub hw_perf_counter_init() to register hardware counters. | 457 | weak stub hw_perf_event_init() to register hardware counters. |