1 ========================
2 PMU Event Based Branches
3 ========================
4
5 Event Based Branches (EBBs) are a feature whic
6 branch directly to a specified user space addr
7
8 The full specification is available in Power I
9
10 https://www.power.org/documentation/power-is
11
12 One type of event for which EBBs can be config
13 document describes the API for configuring the
14 using the Linux perf_events API.
15
16
17 Terminology
18 -----------
19
20 Throughout this document we will refer to an "
21 just refers to a struct perf_event which has s
22 attr.config. All events which can be configure
23 possible "EBB events".
24
25
26 Background
27 ----------
28
29 When a PMU EBB occurs it is delivered to the c
30 EBBs can only sensibly be used by programs for
31
32 It is a feature of the perf_events API that ev
33 processes, subject to standard permission chec
34 events, however unless the target process enab
35 EBBs will ever be delivered.
36
37 This makes it possible for a process to enable
38 actually configure any events. At a later time
39 and attach an EBB event to the process, which
40 delivered to the first process. It's not clear
41
42
43 When the PMU is configured for EBBs, all PMU i
44 user process. This means once an EBB event is
45 events can be configured. This means that EBB
46 concurrently with regular 'perf' commands, or
47
48 It is however safe to run 'perf' commands on a
49 kernel will in general schedule the EBB event,
50 its events could not run.
51
52 The exclusion between EBB events and regular e
53 existing "pinned" and "exclusive" attributes o
54 events will be given priority over other event
55 If an EBB event and a regular event are both p
56 first will be scheduled and the other will be
57 section below titled "Enabling an EBB event" f
58
59
60 Creating an EBB event
61 ---------------------
62
63 To request that an event is counted using EBB,
64 63 set.
65
66 EBB events must be created with a particular,
67 attributes - this is so that they interoperate
68 perf_events subsystem.
69
70 An EBB event must be created with the "pinned"
71 Note that if you are creating a group of EBB e
72 these attributes set.
73
74 An EBB event must NOT set any of the "inherit"
75 "enable_on_exec" attributes.
76
77 An EBB event must be attached to a task. This
78 by passing a pid value, typically 0 indicating
79
80 All events in a group must agree on whether th
81 must request EBB, or none may request EBB.
82
83 EBB events must specify the PMC they are to be
84 userspace is able to reliably determine which
85
86
87 Enabling an EBB event
88 ---------------------
89
90 Once an EBB event has been successfully opened
91 perf_events API. This can be achieved either v
92 prctl() interface.
93
94 However, due to the design of the perf_events
95 guarantee that it has been scheduled on the PM
96 has been scheduled on the PMU, you must perfor
97 read() returns EOF, then the event has not bee
98 enabled.
99
100 This behaviour occurs because the EBB event is
101 EBB event is enabled it will force all other n
102 this case the enable will be successful. Howev
103 pinned on the PMU then the enable will not be
104
105
106 Reading an EBB event
107 --------------------
108
109 It is possible to read() from an EBB event. Ho
110 meaningless. Because interrupts are being deli
111 kernel is not able to count the event, and so
112
113
114 Closing an EBB event
115 --------------------
116
117 When an EBB event is finished with, you can cl
118 regular event. If this is the last EBB event t
119 no further PMU EBBs will be delivered.
120
121
122 EBB Handler
123 -----------
124
125 The EBB handler is just regular userspace code
126 the style of an interrupt handler. When the ha
127 are live (possibly) and so must be saved someh
128 other code.
129
130 It's up to the program how to handle this. For
131 option is to create an interrupt frame on the
132
133 Fork
134 ----
135
136 EBB events are not inherited across fork. If t
137 EBBs it should open a new event for itself. Si
138 BESCR/EBBHR/EBBRR is cleared across fork().
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.