139 lines · plain
1========================2PMU Event Based Branches3========================4 5Event Based Branches (EBBs) are a feature which allows the hardware to6branch directly to a specified user space address when certain events occur.7 8The full specification is available in Power ISA v2.07:9 10 https://www.power.org/documentation/power-isa-version-2-07/11 12One type of event for which EBBs can be configured is PMU exceptions. This13document describes the API for configuring the Power PMU to generate EBBs,14using the Linux perf_events API.15 16 17Terminology18-----------19 20Throughout this document we will refer to an "EBB event" or "EBB events". This21just refers to a struct perf_event which has set the "EBB" flag in its22attr.config. All events which can be configured on the hardware PMU are23possible "EBB events".24 25 26Background27----------28 29When a PMU EBB occurs it is delivered to the currently running process. As such30EBBs can only sensibly be used by programs for self-monitoring.31 32It is a feature of the perf_events API that events can be created on other33processes, subject to standard permission checks. This is also true of EBB34events, however unless the target process enables EBBs (via mtspr(BESCR)) no35EBBs will ever be delivered.36 37This makes it possible for a process to enable EBBs for itself, but not38actually configure any events. At a later time another process can come along39and attach an EBB event to the process, which will then cause EBBs to be40delivered to the first process. It's not clear if this is actually useful.41 42 43When the PMU is configured for EBBs, all PMU interrupts are delivered to the44user process. This means once an EBB event is scheduled on the PMU, no non-EBB45events can be configured. This means that EBB events can not be run46concurrently with regular 'perf' commands, or any other perf events.47 48It is however safe to run 'perf' commands on a process which is using EBBs. The49kernel will in general schedule the EBB event, and perf will be notified that50its events could not run.51 52The exclusion between EBB events and regular events is implemented using the53existing "pinned" and "exclusive" attributes of perf_events. This means EBB54events will be given priority over other events, unless they are also pinned.55If an EBB event and a regular event are both pinned, then whichever is enabled56first will be scheduled and the other will be put in error state. See the57section below titled "Enabling an EBB event" for more information.58 59 60Creating an EBB event61---------------------62 63To request that an event is counted using EBB, the event code should have bit6463 set.65 66EBB events must be created with a particular, and restrictive, set of67attributes - this is so that they interoperate correctly with the rest of the68perf_events subsystem.69 70An EBB event must be created with the "pinned" and "exclusive" attributes set.71Note that if you are creating a group of EBB events, only the leader can have72these attributes set.73 74An EBB event must NOT set any of the "inherit", "sample_period", "freq" or75"enable_on_exec" attributes.76 77An EBB event must be attached to a task. This is specified to perf_event_open()78by passing a pid value, typically 0 indicating the current task.79 80All events in a group must agree on whether they want EBB. That is all events81must request EBB, or none may request EBB.82 83EBB events must specify the PMC they are to be counted on. This ensures84userspace is able to reliably determine which PMC the event is scheduled on.85 86 87Enabling an EBB event88---------------------89 90Once an EBB event has been successfully opened, it must be enabled with the91perf_events API. This can be achieved either via the ioctl() interface, or the92prctl() interface.93 94However, due to the design of the perf_events API, enabling an event does not95guarantee that it has been scheduled on the PMU. To ensure that the EBB event96has been scheduled on the PMU, you must perform a read() on the event. If the97read() returns EOF, then the event has not been scheduled and EBBs are not98enabled.99 100This behaviour occurs because the EBB event is pinned and exclusive. When the101EBB event is enabled it will force all other non-pinned events off the PMU. In102this case the enable will be successful. However if there is already an event103pinned on the PMU then the enable will not be successful.104 105 106Reading an EBB event107--------------------108 109It is possible to read() from an EBB event. However the results are110meaningless. Because interrupts are being delivered to the user process the111kernel is not able to count the event, and so will return a junk value.112 113 114Closing an EBB event115--------------------116 117When an EBB event is finished with, you can close it using close() as for any118regular event. If this is the last EBB event the PMU will be deconfigured and119no further PMU EBBs will be delivered.120 121 122EBB Handler123-----------124 125The EBB handler is just regular userspace code, however it must be written in126the style of an interrupt handler. When the handler is entered all registers127are live (possibly) and so must be saved somehow before the handler can invoke128other code.129 130It's up to the program how to handle this. For C programs a relatively simple131option is to create an interrupt frame on the stack and save registers there.132 133Fork134----135 136EBB events are not inherited across fork. If the child process wishes to use137EBBs it should open a new event for itself. Similarly the EBB state in138BESCR/EBBHR/EBBRR is cleared across fork().139