Documentation/powerpc/pmu-ebb.rst

   1 ========================
   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().