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