design.txt 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463
  1. Performance Counters for Linux
  2. ------------------------------
  3. Performance counters are special hardware registers available on most modern
  4. CPUs. These registers count the number of certain types of hw events: such
  5. as instructions executed, cachemisses suffered, or branches mis-predicted -
  6. without slowing down the kernel or applications. These registers can also
  7. trigger interrupts when a threshold number of events have passed - and can
  8. thus be used to profile the code that runs on that CPU.
  9. The Linux Performance Counter subsystem provides an abstraction of these
  10. hardware capabilities. It provides per task and per CPU counters, counter
  11. groups, and it provides event capabilities on top of those. It
  12. provides "virtual" 64-bit counters, regardless of the width of the
  13. underlying hardware counters.
  14. Performance counters are accessed via special file descriptors.
  15. There's one file descriptor per virtual counter used.
  16. The special file descriptor is opened via the sys_perf_event_open()
  17. system call:
  18. int sys_perf_event_open(struct perf_event_attr *hw_event_uptr,
  19. pid_t pid, int cpu, int group_fd,
  20. unsigned long flags);
  21. The syscall returns the new fd. The fd can be used via the normal
  22. VFS system calls: read() can be used to read the counter, fcntl()
  23. can be used to set the blocking mode, etc.
  24. Multiple counters can be kept open at a time, and the counters
  25. can be poll()ed.
  26. When creating a new counter fd, 'perf_event_attr' is:
  27. struct perf_event_attr {
  28. /*
  29. * The MSB of the config word signifies if the rest contains cpu
  30. * specific (raw) counter configuration data, if unset, the next
  31. * 7 bits are an event type and the rest of the bits are the event
  32. * identifier.
  33. */
  34. __u64 config;
  35. __u64 irq_period;
  36. __u32 record_type;
  37. __u32 read_format;
  38. __u64 disabled : 1, /* off by default */
  39. inherit : 1, /* children inherit it */
  40. pinned : 1, /* must always be on PMU */
  41. exclusive : 1, /* only group on PMU */
  42. exclude_user : 1, /* don't count user */
  43. exclude_kernel : 1, /* ditto kernel */
  44. exclude_hv : 1, /* ditto hypervisor */
  45. exclude_idle : 1, /* don't count when idle */
  46. mmap : 1, /* include mmap data */
  47. munmap : 1, /* include munmap data */
  48. comm : 1, /* include comm data */
  49. __reserved_1 : 52;
  50. __u32 extra_config_len;
  51. __u32 wakeup_events; /* wakeup every n events */
  52. __u64 __reserved_2;
  53. __u64 __reserved_3;
  54. };
  55. The 'config' field specifies what the counter should count. It
  56. is divided into 3 bit-fields:
  57. raw_type: 1 bit (most significant bit) 0x8000_0000_0000_0000
  58. type: 7 bits (next most significant) 0x7f00_0000_0000_0000
  59. event_id: 56 bits (least significant) 0x00ff_ffff_ffff_ffff
  60. If 'raw_type' is 1, then the counter will count a hardware event
  61. specified by the remaining 63 bits of event_config. The encoding is
  62. machine-specific.
  63. If 'raw_type' is 0, then the 'type' field says what kind of counter
  64. this is, with the following encoding:
  65. enum perf_type_id {
  66. PERF_TYPE_HARDWARE = 0,
  67. PERF_TYPE_SOFTWARE = 1,
  68. PERF_TYPE_TRACEPOINT = 2,
  69. };
  70. A counter of PERF_TYPE_HARDWARE will count the hardware event
  71. specified by 'event_id':
  72. /*
  73. * Generalized performance counter event types, used by the hw_event.event_id
  74. * parameter of the sys_perf_event_open() syscall:
  75. */
  76. enum perf_hw_id {
  77. /*
  78. * Common hardware events, generalized by the kernel:
  79. */
  80. PERF_COUNT_HW_CPU_CYCLES = 0,
  81. PERF_COUNT_HW_INSTRUCTIONS = 1,
  82. PERF_COUNT_HW_CACHE_REFERENCES = 2,
  83. PERF_COUNT_HW_CACHE_MISSES = 3,
  84. PERF_COUNT_HW_BRANCH_INSTRUCTIONS = 4,
  85. PERF_COUNT_HW_BRANCH_MISSES = 5,
  86. PERF_COUNT_HW_BUS_CYCLES = 6,
  87. };
  88. These are standardized types of events that work relatively uniformly
  89. on all CPUs that implement Performance Counters support under Linux,
  90. although there may be variations (e.g., different CPUs might count
  91. cache references and misses at different levels of the cache hierarchy).
  92. If a CPU is not able to count the selected event, then the system call
  93. will return -EINVAL.
  94. More hw_event_types are supported as well, but they are CPU-specific
  95. and accessed as raw events. For example, to count "External bus
  96. cycles while bus lock signal asserted" events on Intel Core CPUs, pass
  97. in a 0x4064 event_id value and set hw_event.raw_type to 1.
  98. A counter of type PERF_TYPE_SOFTWARE will count one of the available
  99. software events, selected by 'event_id':
  100. /*
  101. * Special "software" counters provided by the kernel, even if the hardware
  102. * does not support performance counters. These counters measure various
  103. * physical and sw events of the kernel (and allow the profiling of them as
  104. * well):
  105. */
  106. enum perf_sw_ids {
  107. PERF_COUNT_SW_CPU_CLOCK = 0,
  108. PERF_COUNT_SW_TASK_CLOCK = 1,
  109. PERF_COUNT_SW_PAGE_FAULTS = 2,
  110. PERF_COUNT_SW_CONTEXT_SWITCHES = 3,
  111. PERF_COUNT_SW_CPU_MIGRATIONS = 4,
  112. PERF_COUNT_SW_PAGE_FAULTS_MIN = 5,
  113. PERF_COUNT_SW_PAGE_FAULTS_MAJ = 6,
  114. PERF_COUNT_SW_ALIGNMENT_FAULTS = 7,
  115. PERF_COUNT_SW_EMULATION_FAULTS = 8,
  116. };
  117. Counters of the type PERF_TYPE_TRACEPOINT are available when the ftrace event
  118. tracer is available, and event_id values can be obtained from
  119. /debug/tracing/events/*/*/id
  120. Counters come in two flavours: counting counters and sampling
  121. counters. A "counting" counter is one that is used for counting the
  122. number of events that occur, and is characterised by having
  123. irq_period = 0.
  124. A read() on a counter returns the current value of the counter and possible
  125. additional values as specified by 'read_format', each value is a u64 (8 bytes)
  126. in size.
  127. /*
  128. * Bits that can be set in hw_event.read_format to request that
  129. * reads on the counter should return the indicated quantities,
  130. * in increasing order of bit value, after the counter value.
  131. */
  132. enum perf_event_read_format {
  133. PERF_FORMAT_TOTAL_TIME_ENABLED = 1,
  134. PERF_FORMAT_TOTAL_TIME_RUNNING = 2,
  135. };
  136. Using these additional values one can establish the overcommit ratio for a
  137. particular counter allowing one to take the round-robin scheduling effect
  138. into account.
  139. A "sampling" counter is one that is set up to generate an interrupt
  140. every N events, where N is given by 'irq_period'. A sampling counter
  141. has irq_period > 0. The record_type controls what data is recorded on each
  142. interrupt:
  143. /*
  144. * Bits that can be set in hw_event.record_type to request information
  145. * in the overflow packets.
  146. */
  147. enum perf_event_record_format {
  148. PERF_RECORD_IP = 1U << 0,
  149. PERF_RECORD_TID = 1U << 1,
  150. PERF_RECORD_TIME = 1U << 2,
  151. PERF_RECORD_ADDR = 1U << 3,
  152. PERF_RECORD_GROUP = 1U << 4,
  153. PERF_RECORD_CALLCHAIN = 1U << 5,
  154. };
  155. Such (and other) events will be recorded in a ring-buffer, which is
  156. available to user-space using mmap() (see below).
  157. The 'disabled' bit specifies whether the counter starts out disabled
  158. or enabled. If it is initially disabled, it can be enabled by ioctl
  159. or prctl (see below).
  160. The 'inherit' bit, if set, specifies that this counter should count
  161. events on descendant tasks as well as the task specified. This only
  162. applies to new descendents, not to any existing descendents at the
  163. time the counter is created (nor to any new descendents of existing
  164. descendents).
  165. The 'pinned' bit, if set, specifies that the counter should always be
  166. on the CPU if at all possible. It only applies to hardware counters
  167. and only to group leaders. If a pinned counter cannot be put onto the
  168. CPU (e.g. because there are not enough hardware counters or because of
  169. a conflict with some other event), then the counter goes into an
  170. 'error' state, where reads return end-of-file (i.e. read() returns 0)
  171. until the counter is subsequently enabled or disabled.
  172. The 'exclusive' bit, if set, specifies that when this counter's group
  173. is on the CPU, it should be the only group using the CPU's counters.
  174. In future, this will allow sophisticated monitoring programs to supply
  175. extra configuration information via 'extra_config_len' to exploit
  176. advanced features of the CPU's Performance Monitor Unit (PMU) that are
  177. not otherwise accessible and that might disrupt other hardware
  178. counters.
  179. The 'exclude_user', 'exclude_kernel' and 'exclude_hv' bits provide a
  180. way to request that counting of events be restricted to times when the
  181. CPU is in user, kernel and/or hypervisor mode.
  182. The 'mmap' and 'munmap' bits allow recording of PROT_EXEC mmap/munmap
  183. operations, these can be used to relate userspace IP addresses to actual
  184. code, even after the mapping (or even the whole process) is gone,
  185. these events are recorded in the ring-buffer (see below).
  186. The 'comm' bit allows tracking of process comm data on process creation.
  187. This too is recorded in the ring-buffer (see below).
  188. The 'pid' parameter to the sys_perf_event_open() system call allows the
  189. counter to be specific to a task:
  190. pid == 0: if the pid parameter is zero, the counter is attached to the
  191. current task.
  192. pid > 0: the counter is attached to a specific task (if the current task
  193. has sufficient privilege to do so)
  194. pid < 0: all tasks are counted (per cpu counters)
  195. The 'cpu' parameter allows a counter to be made specific to a CPU:
  196. cpu >= 0: the counter is restricted to a specific CPU
  197. cpu == -1: the counter counts on all CPUs
  198. (Note: the combination of 'pid == -1' and 'cpu == -1' is not valid.)
  199. A 'pid > 0' and 'cpu == -1' counter is a per task counter that counts
  200. events of that task and 'follows' that task to whatever CPU the task
  201. gets schedule to. Per task counters can be created by any user, for
  202. their own tasks.
  203. A 'pid == -1' and 'cpu == x' counter is a per CPU counter that counts
  204. all events on CPU-x. Per CPU counters need CAP_SYS_ADMIN privilege.
  205. The 'flags' parameter is currently unused and must be zero.
  206. The 'group_fd' parameter allows counter "groups" to be set up. A
  207. counter group has one counter which is the group "leader". The leader
  208. is created first, with group_fd = -1 in the sys_perf_event_open call
  209. that creates it. The rest of the group members are created
  210. subsequently, with group_fd giving the fd of the group leader.
  211. (A single counter on its own is created with group_fd = -1 and is
  212. considered to be a group with only 1 member.)
  213. A counter group is scheduled onto the CPU as a unit, that is, it will
  214. only be put onto the CPU if all of the counters in the group can be
  215. put onto the CPU. This means that the values of the member counters
  216. can be meaningfully compared, added, divided (to get ratios), etc.,
  217. with each other, since they have counted events for the same set of
  218. executed instructions.
  219. Like stated, asynchronous events, like counter overflow or PROT_EXEC mmap
  220. tracking are logged into a ring-buffer. This ring-buffer is created and
  221. accessed through mmap().
  222. The mmap size should be 1+2^n pages, where the first page is a meta-data page
  223. (struct perf_event_mmap_page) that contains various bits of information such
  224. as where the ring-buffer head is.
  225. /*
  226. * Structure of the page that can be mapped via mmap
  227. */
  228. struct perf_event_mmap_page {
  229. __u32 version; /* version number of this structure */
  230. __u32 compat_version; /* lowest version this is compat with */
  231. /*
  232. * Bits needed to read the hw counters in user-space.
  233. *
  234. * u32 seq;
  235. * s64 count;
  236. *
  237. * do {
  238. * seq = pc->lock;
  239. *
  240. * barrier()
  241. * if (pc->index) {
  242. * count = pmc_read(pc->index - 1);
  243. * count += pc->offset;
  244. * } else
  245. * goto regular_read;
  246. *
  247. * barrier();
  248. * } while (pc->lock != seq);
  249. *
  250. * NOTE: for obvious reason this only works on self-monitoring
  251. * processes.
  252. */
  253. __u32 lock; /* seqlock for synchronization */
  254. __u32 index; /* hardware counter identifier */
  255. __s64 offset; /* add to hardware counter value */
  256. /*
  257. * Control data for the mmap() data buffer.
  258. *
  259. * User-space reading this value should issue an rmb(), on SMP capable
  260. * platforms, after reading this value -- see perf_event_wakeup().
  261. */
  262. __u32 data_head; /* head in the data section */
  263. };
  264. NOTE: the hw-counter userspace bits are arch specific and are currently only
  265. implemented on powerpc.
  266. The following 2^n pages are the ring-buffer which contains events of the form:
  267. #define PERF_RECORD_MISC_KERNEL (1 << 0)
  268. #define PERF_RECORD_MISC_USER (1 << 1)
  269. #define PERF_RECORD_MISC_OVERFLOW (1 << 2)
  270. struct perf_event_header {
  271. __u32 type;
  272. __u16 misc;
  273. __u16 size;
  274. };
  275. enum perf_event_type {
  276. /*
  277. * The MMAP events record the PROT_EXEC mappings so that we can
  278. * correlate userspace IPs to code. They have the following structure:
  279. *
  280. * struct {
  281. * struct perf_event_header header;
  282. *
  283. * u32 pid, tid;
  284. * u64 addr;
  285. * u64 len;
  286. * u64 pgoff;
  287. * char filename[];
  288. * };
  289. */
  290. PERF_RECORD_MMAP = 1,
  291. PERF_RECORD_MUNMAP = 2,
  292. /*
  293. * struct {
  294. * struct perf_event_header header;
  295. *
  296. * u32 pid, tid;
  297. * char comm[];
  298. * };
  299. */
  300. PERF_RECORD_COMM = 3,
  301. /*
  302. * When header.misc & PERF_RECORD_MISC_OVERFLOW the event_type field
  303. * will be PERF_RECORD_*
  304. *
  305. * struct {
  306. * struct perf_event_header header;
  307. *
  308. * { u64 ip; } && PERF_RECORD_IP
  309. * { u32 pid, tid; } && PERF_RECORD_TID
  310. * { u64 time; } && PERF_RECORD_TIME
  311. * { u64 addr; } && PERF_RECORD_ADDR
  312. *
  313. * { u64 nr;
  314. * { u64 event, val; } cnt[nr]; } && PERF_RECORD_GROUP
  315. *
  316. * { u16 nr,
  317. * hv,
  318. * kernel,
  319. * user;
  320. * u64 ips[nr]; } && PERF_RECORD_CALLCHAIN
  321. * };
  322. */
  323. };
  324. NOTE: PERF_RECORD_CALLCHAIN is arch specific and currently only implemented
  325. on x86.
  326. Notification of new events is possible through poll()/select()/epoll() and
  327. fcntl() managing signals.
  328. Normally a notification is generated for every page filled, however one can
  329. additionally set perf_event_attr.wakeup_events to generate one every
  330. so many counter overflow events.
  331. Future work will include a splice() interface to the ring-buffer.
  332. Counters can be enabled and disabled in two ways: via ioctl and via
  333. prctl. When a counter is disabled, it doesn't count or generate
  334. events but does continue to exist and maintain its count value.
  335. An individual counter can be enabled with
  336. ioctl(fd, PERF_EVENT_IOC_ENABLE, 0);
  337. or disabled with
  338. ioctl(fd, PERF_EVENT_IOC_DISABLE, 0);
  339. For a counter group, pass PERF_IOC_FLAG_GROUP as the third argument.
  340. Enabling or disabling the leader of a group enables or disables the
  341. whole group; that is, while the group leader is disabled, none of the
  342. counters in the group will count. Enabling or disabling a member of a
  343. group other than the leader only affects that counter - disabling an
  344. non-leader stops that counter from counting but doesn't affect any
  345. other counter.
  346. Additionally, non-inherited overflow counters can use
  347. ioctl(fd, PERF_EVENT_IOC_REFRESH, nr);
  348. to enable a counter for 'nr' events, after which it gets disabled again.
  349. A process can enable or disable all the counter groups that are
  350. attached to it, using prctl:
  351. prctl(PR_TASK_PERF_EVENTS_ENABLE);
  352. prctl(PR_TASK_PERF_EVENTS_DISABLE);
  353. This applies to all counters on the current process, whether created
  354. by this process or by another, and doesn't affect any counters that
  355. this process has created on other processes. It only enables or
  356. disables the group leaders, not any other members in the groups.
  357. Arch requirements
  358. -----------------
  359. If your architecture does not have hardware performance metrics, you can
  360. still use the generic software counters based on hrtimers for sampling.
  361. So to start with, in order to add HAVE_PERF_EVENTS to your Kconfig, you
  362. will need at least this:
  363. - asm/perf_event.h - a basic stub will suffice at first
  364. - support for atomic64 types (and associated helper functions)
  365. If your architecture does have hardware capabilities, you can override the
  366. weak stub hw_perf_event_init() to register hardware counters.
  367. Architectures that have d-cache aliassing issues, such as Sparc and ARM,
  368. should select PERF_USE_VMALLOC in order to avoid these for perf mmap().