Terminology¶

Throughout this document we will refer to an “EBB event” or “EBB events”. Thisjust refers to a struct perf_event which has set the “EBB” flag in itsattr.config. All events which can be configured on the hardware PMU arepossible “EBB events”.

Background¶

When a PMU EBB occurs it is delivered to the currently running process. As suchEBBs can only sensibly be used by programs for self-monitoring.

It is a feature of the perf_events API that events can be created on otherprocesses, subject to standard permission checks. This is also true of EBBevents, however unless the target process enables EBBs (via mtspr(BESCR)) noEBBs will ever be delivered.

This makes it possible for a process to enable EBBs for itself, but notactually configure any events. At a later time another process can come alongand attach an EBB event to the process, which will then cause EBBs to bedelivered to the first process. It’s not clear if this is actually useful.

When the PMU is configured for EBBs, all PMU interrupts are delivered to theuser process. This means once an EBB event is scheduled on the PMU, no non-EBBevents can be configured. This means that EBB events can not be runconcurrently with regular ‘perf’ commands, or any other perf events.

It is however safe to run ‘perf’ commands on a process which is using EBBs. Thekernel will in general schedule the EBB event, and perf will be notified thatits events could not run.

The exclusion between EBB events and regular events is implemented using theexisting “pinned” and “exclusive” attributes of perf_events. This means EBBevents will be given priority over other events, unless they are also pinned.If an EBB event and a regular event are both pinned, then whichever is enabledfirst will be scheduled and the other will be put in error state. See thesection below titled “Enabling an EBB event” for more information.

Creating an EBB event¶

To request that an event is counted using EBB, the event code should have bit63 set.

EBB events must be created with a particular, and restrictive, set ofattributes - this is so that they interoperate correctly with the rest of theperf_events subsystem.

An EBB event must be created with the “pinned” and “exclusive” attributes set.Note that if you are creating a group of EBB events, only the leader can havethese attributes set.

An EBB event must NOT set any of the “inherit”, “sample_period”, “freq” or“enable_on_exec” attributes.

An EBB event must be attached to a task. This is specified to perf_event_open()by passing a pid value, typically 0 indicating the current task.

All events in a group must agree on whether they want EBB. That is all eventsmust request EBB, or none may request EBB.

EBB events must specify the PMC they are to be counted on. This ensuresuserspace is able to reliably determine which PMC the event is scheduled on.

Enabling an EBB event¶

Once an EBB event has been successfully opened, it must be enabled with theperf_events API. This can be achieved either via the ioctl() interface, or theprctl() interface.

However, due to the design of the perf_events API, enabling an event does notguarantee that it has been scheduled on the PMU. To ensure that the EBB eventhas been scheduled on the PMU, you must perform a read() on the event. If theread() returns EOF, then the event has not been scheduled and EBBs are notenabled.

This behaviour occurs because the EBB event is pinned and exclusive. When theEBB event is enabled it will force all other non-pinned events off the PMU. Inthis case the enable will be successful. However if there is already an eventpinned on the PMU then the enable will not be successful.

Reading an EBB event¶

It is possible to read() from an EBB event. However the results aremeaningless. Because interrupts are being delivered to the user process thekernel is not able to count the event, and so will return a junk value.

Closing an EBB event¶

When an EBB event is finished with, you can close it using close() as for anyregular event. If this is the last EBB event the PMU will be deconfigured andno further PMU EBBs will be delivered.

EBB Handler¶

The EBB handler is just regular userspace code, however it must be written inthe style of an interrupt handler. When the handler is entered all registersare live (possibly) and so must be saved somehow before the handler can invokeother code.

It’s up to the program how to handle this. For C programs a relatively simpleoption is to create an interrupt frame on the stack and save registers there.

Fork¶

EBB events are not inherited across fork. If the child process wishes to useEBBs it should open a new event for itself. Similarly the EBB state inBESCR/EBBHR/EBBRR is cleared across fork().