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