0001 ========================
0002 PMU Event Based Branches
0003 ========================
0004
0005 Event Based Branches (EBBs) are a feature which allows the hardware to
0006 branch directly to a specified user space address when certain events occur.
0007
0008 The full specification is available in Power ISA v2.07:
0009
0010 https://www.power.org/documentation/power-isa-version-2-07/
0011
0012 One type of event for which EBBs can be configured is PMU exceptions. This
0013 document describes the API for configuring the Power PMU to generate EBBs,
0014 using the Linux perf_events API.
0015
0016
0017 Terminology
0018 -----------
0019
0020 Throughout this document we will refer to an "EBB event" or "EBB events". This
0021 just refers to a struct perf_event which has set the "EBB" flag in its
0022 attr.config. All events which can be configured on the hardware PMU are
0023 possible "EBB events".
0024
0025
0026 Background
0027 ----------
0028
0029 When a PMU EBB occurs it is delivered to the currently running process. As such
0030 EBBs can only sensibly be used by programs for self-monitoring.
0031
0032 It is a feature of the perf_events API that events can be created on other
0033 processes, subject to standard permission checks. This is also true of EBB
0034 events, however unless the target process enables EBBs (via mtspr(BESCR)) no
0035 EBBs will ever be delivered.
0036
0037 This makes it possible for a process to enable EBBs for itself, but not
0038 actually configure any events. At a later time another process can come along
0039 and attach an EBB event to the process, which will then cause EBBs to be
0040 delivered to the first process. It's not clear if this is actually useful.
0041
0042
0043 When the PMU is configured for EBBs, all PMU interrupts are delivered to the
0044 user process. This means once an EBB event is scheduled on the PMU, no non-EBB
0045 events can be configured. This means that EBB events can not be run
0046 concurrently with regular 'perf' commands, or any other perf events.
0047
0048 It is however safe to run 'perf' commands on a process which is using EBBs. The
0049 kernel will in general schedule the EBB event, and perf will be notified that
0050 its events could not run.
0051
0052 The exclusion between EBB events and regular events is implemented using the
0053 existing "pinned" and "exclusive" attributes of perf_events. This means EBB
0054 events will be given priority over other events, unless they are also pinned.
0055 If an EBB event and a regular event are both pinned, then whichever is enabled
0056 first will be scheduled and the other will be put in error state. See the
0057 section below titled "Enabling an EBB event" for more information.
0058
0059
0060 Creating an EBB event
0061 ---------------------
0062
0063 To request that an event is counted using EBB, the event code should have bit
0064 63 set.
0065
0066 EBB events must be created with a particular, and restrictive, set of
0067 attributes - this is so that they interoperate correctly with the rest of the
0068 perf_events subsystem.
0069
0070 An EBB event must be created with the "pinned" and "exclusive" attributes set.
0071 Note that if you are creating a group of EBB events, only the leader can have
0072 these attributes set.
0073
0074 An EBB event must NOT set any of the "inherit", "sample_period", "freq" or
0075 "enable_on_exec" attributes.
0076
0077 An EBB event must be attached to a task. This is specified to perf_event_open()
0078 by passing a pid value, typically 0 indicating the current task.
0079
0080 All events in a group must agree on whether they want EBB. That is all events
0081 must request EBB, or none may request EBB.
0082
0083 EBB events must specify the PMC they are to be counted on. This ensures
0084 userspace is able to reliably determine which PMC the event is scheduled on.
0085
0086
0087 Enabling an EBB event
0088 ---------------------
0089
0090 Once an EBB event has been successfully opened, it must be enabled with the
0091 perf_events API. This can be achieved either via the ioctl() interface, or the
0092 prctl() interface.
0093
0094 However, due to the design of the perf_events API, enabling an event does not
0095 guarantee that it has been scheduled on the PMU. To ensure that the EBB event
0096 has been scheduled on the PMU, you must perform a read() on the event. If the
0097 read() returns EOF, then the event has not been scheduled and EBBs are not
0098 enabled.
0099
0100 This behaviour occurs because the EBB event is pinned and exclusive. When the
0101 EBB event is enabled it will force all other non-pinned events off the PMU. In
0102 this case the enable will be successful. However if there is already an event
0103 pinned on the PMU then the enable will not be successful.
0104
0105
0106 Reading an EBB event
0107 --------------------
0108
0109 It is possible to read() from an EBB event. However the results are
0110 meaningless. Because interrupts are being delivered to the user process the
0111 kernel is not able to count the event, and so will return a junk value.
0112
0113
0114 Closing an EBB event
0115 --------------------
0116
0117 When an EBB event is finished with, you can close it using close() as for any
0118 regular event. If this is the last EBB event the PMU will be deconfigured and
0119 no further PMU EBBs will be delivered.
0120
0121
0122 EBB Handler
0123 -----------
0124
0125 The EBB handler is just regular userspace code, however it must be written in
0126 the style of an interrupt handler. When the handler is entered all registers
0127 are live (possibly) and so must be saved somehow before the handler can invoke
0128 other code.
0129
0130 It's up to the program how to handle this. For C programs a relatively simple
0131 option is to create an interrupt frame on the stack and save registers there.
0132
0133 Fork
0134 ----
0135
0136 EBB events are not inherited across fork. If the child process wishes to use
0137 EBBs it should open a new event for itself. Similarly the EBB state in
0138 BESCR/EBBHR/EBBRR is cleared across fork().
