Commit | Line | Data |
---|---|---|
4d2e26a3 | 1 | ======================== |
330a1eb7 ME |
2 | PMU Event Based Branches |
3 | ======================== | |
4 | ||
5 | Event Based Branches (EBBs) are a feature which allows the hardware to | |
6 | branch directly to a specified user space address when certain events occur. | |
7 | ||
8 | The full specification is available in Power ISA v2.07: | |
9 | ||
10 | https://www.power.org/documentation/power-isa-version-2-07/ | |
11 | ||
12 | One type of event for which EBBs can be configured is PMU exceptions. This | |
13 | document describes the API for configuring the Power PMU to generate EBBs, | |
14 | using the Linux perf_events API. | |
15 | ||
16 | ||
17 | Terminology | |
18 | ----------- | |
19 | ||
20 | Throughout this document we will refer to an "EBB event" or "EBB events". This | |
21 | just refers to a struct perf_event which has set the "EBB" flag in its | |
22 | attr.config. All events which can be configured on the hardware PMU are | |
23 | possible "EBB events". | |
24 | ||
25 | ||
26 | Background | |
27 | ---------- | |
28 | ||
29 | When a PMU EBB occurs it is delivered to the currently running process. As such | |
30 | EBBs can only sensibly be used by programs for self-monitoring. | |
31 | ||
32 | It is a feature of the perf_events API that events can be created on other | |
33 | processes, subject to standard permission checks. This is also true of EBB | |
34 | events, however unless the target process enables EBBs (via mtspr(BESCR)) no | |
35 | EBBs will ever be delivered. | |
36 | ||
37 | This makes it possible for a process to enable EBBs for itself, but not | |
38 | actually configure any events. At a later time another process can come along | |
39 | and attach an EBB event to the process, which will then cause EBBs to be | |
40 | delivered to the first process. It's not clear if this is actually useful. | |
41 | ||
42 | ||
43 | When the PMU is configured for EBBs, all PMU interrupts are delivered to the | |
44 | user process. This means once an EBB event is scheduled on the PMU, no non-EBB | |
45 | events can be configured. This means that EBB events can not be run | |
46 | concurrently with regular 'perf' commands, or any other perf events. | |
47 | ||
48 | It is however safe to run 'perf' commands on a process which is using EBBs. The | |
49 | kernel will in general schedule the EBB event, and perf will be notified that | |
50 | its events could not run. | |
51 | ||
52 | The exclusion between EBB events and regular events is implemented using the | |
53 | existing "pinned" and "exclusive" attributes of perf_events. This means EBB | |
54 | events will be given priority over other events, unless they are also pinned. | |
55 | If an EBB event and a regular event are both pinned, then whichever is enabled | |
56 | first will be scheduled and the other will be put in error state. See the | |
57 | section below titled "Enabling an EBB event" for more information. | |
58 | ||
59 | ||
60 | Creating an EBB event | |
61 | --------------------- | |
62 | ||
63 | To request that an event is counted using EBB, the event code should have bit | |
64 | 63 set. | |
65 | ||
66 | EBB events must be created with a particular, and restrictive, set of | |
67 | attributes - this is so that they interoperate correctly with the rest of the | |
68 | perf_events subsystem. | |
69 | ||
70 | An EBB event must be created with the "pinned" and "exclusive" attributes set. | |
71 | Note that if you are creating a group of EBB events, only the leader can have | |
72 | these attributes set. | |
73 | ||
74 | An EBB event must NOT set any of the "inherit", "sample_period", "freq" or | |
75 | "enable_on_exec" attributes. | |
76 | ||
77 | An EBB event must be attached to a task. This is specified to perf_event_open() | |
78 | by passing a pid value, typically 0 indicating the current task. | |
79 | ||
80 | All events in a group must agree on whether they want EBB. That is all events | |
81 | must request EBB, or none may request EBB. | |
82 | ||
83 | EBB events must specify the PMC they are to be counted on. This ensures | |
84 | userspace is able to reliably determine which PMC the event is scheduled on. | |
85 | ||
86 | ||
87 | Enabling an EBB event | |
88 | --------------------- | |
89 | ||
90 | Once an EBB event has been successfully opened, it must be enabled with the | |
91 | perf_events API. This can be achieved either via the ioctl() interface, or the | |
92 | prctl() interface. | |
93 | ||
94 | However, due to the design of the perf_events API, enabling an event does not | |
95 | guarantee that it has been scheduled on the PMU. To ensure that the EBB event | |
96 | has been scheduled on the PMU, you must perform a read() on the event. If the | |
97 | read() returns EOF, then the event has not been scheduled and EBBs are not | |
98 | enabled. | |
99 | ||
100 | This behaviour occurs because the EBB event is pinned and exclusive. When the | |
101 | EBB event is enabled it will force all other non-pinned events off the PMU. In | |
102 | this case the enable will be successful. However if there is already an event | |
103 | pinned on the PMU then the enable will not be successful. | |
104 | ||
105 | ||
106 | Reading an EBB event | |
107 | -------------------- | |
108 | ||
109 | It is possible to read() from an EBB event. However the results are | |
110 | meaningless. Because interrupts are being delivered to the user process the | |
111 | kernel is not able to count the event, and so will return a junk value. | |
112 | ||
113 | ||
114 | Closing an EBB event | |
115 | -------------------- | |
116 | ||
117 | When an EBB event is finished with, you can close it using close() as for any | |
118 | regular event. If this is the last EBB event the PMU will be deconfigured and | |
119 | no further PMU EBBs will be delivered. | |
120 | ||
121 | ||
122 | EBB Handler | |
123 | ----------- | |
124 | ||
125 | The EBB handler is just regular userspace code, however it must be written in | |
126 | the style of an interrupt handler. When the handler is entered all registers | |
127 | are live (possibly) and so must be saved somehow before the handler can invoke | |
128 | other code. | |
129 | ||
130 | It's up to the program how to handle this. For C programs a relatively simple | |
131 | option is to create an interrupt frame on the stack and save registers there. | |
132 | ||
133 | Fork | |
134 | ---- | |
135 | ||
136 | EBB events are not inherited across fork. If the child process wishes to use | |
137 | EBBs it should open a new event for itself. Similarly the EBB state in | |
138 | BESCR/EBBHR/EBBRR is cleared across fork(). |