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