libpaf-ebb − The Power Architecture Facilities Event-Based Branch Library
typedef void (*ebbhandler_t)(void*);
int paf_ebb_pmu_init(uint64_t raw_event, int group);
void paf_ebb_pmu_set_period(uint32_t sample_period);
ebbhandler_t paf_ebb_register_handler(ebbhandler_t handler, void * context, paf_ebb_callback_type_t type, int flags);
Compile and link with −lpaf−ebb.
The Power Architecture® Facilities Event-Based Branch Library (libpaf-ebb) is a part of the Power Architecture Facilities Library (PAFLib)
The Event-Based Branch Library provides an easy-to-use framework for using the Power Architecture Event-Based Branch facility (EBB).
If enabled, the EBB facility generates an event-based exception when a user-specified event occurs, which causes the hardware to branch directly to a user-space address (EBB handler). The facility does not require any kernel handling besides initialization. Only Performance Monitor Unit (PMU) events are supported.
The Event-Based Branch Library framework registers a proxy-handler with the hardware, on behalf of a user program, so that the program doesn’t need to directly control the Power Architecture EBB facility (which would require assembly language instructions and an understanding of the EBB ELF ABI).
The EBB Library proxy-handler will properly stack an ELF ABI EBB exception frame on the user-stack, preserve the current register context in that stack frame, and then pass control to a user registered (thread specific) handler. When the user-space handler has completed its task and returned control to the EBB Library proxy-handler, the proxy-handler will perform the tasks necessary to restore the register context, pop the EBB exception frame, and return control to the code that was interrupted by the event-based exception.
paf_ebb_pmu_init() initializes the PMU event generation configuring the hardware counter raw_event with the specified group. The first call should use -1 to start a new group. Subsequent calls may create new groups or use the returned file descriptor from paf_ebb_pmu_init to associate events in a group. The file descriptor returned should be closed when done to prevent resource leak.
The event-based exception is triggered when the PMU counter overflows. To set the PMC to an initial value different from default (0) use paf_ebb_pmu_set_period To reset it to potentially trigger another event call paf_ebb_pmu_reset().
paf_ebb_register_handler() registers the user handler (ebbhandler_t) function to be called when the EBB is triggered with the argument context. Common state registers (LR, CR, CTR, XER) are always saved and type specifies which further set of registers will be saved and restored:
PPCEBB_CALLBACK_GPR_SAVE: save/restore all General Purpose Registers.
PPCEBB_CALLBACK_FPR_SAVE: save/restore all General Purpose Registers and all Floating-Point Register.
PPCEBB_CALLBACK_VR_SAVE: save/restore all General Purpose Registers, all Floating-Point Register, and all Vector Registers (VMX).
PPCEBB_CALLBACK_VSR_SAVE: save/restore all General Purpose Registers, all Floating-Point Register, all Vector Registers (VMX), and all Vector Scalar Registers (VSX).
The current support flags is either 0 or a multibyte mask of bits with one or more of the following options:
PAF_EBB_FLAGS_RESET_PMU after the callback activation the EBB machanism will be reset, similiar to a call to paf_ebb_pmu_reset
paf_ebb_handler() returns the registered handler previously issued by paf_ebb_register_handler().
paf_ebb_enable_branches() enables EBB triggering.
paf_ebb_disable_branches() disables EBB triggering.
paf_ebb_pmu_init() returns a file descriptor to be used in group association or -1 case of error.
paf_ebb_register_handler() returns the registered handler or EBB_REG_ERR on error. On error errno is set appropriately.
paf_ebb_handler() returns the previous registered handler or EBB_REG_ERR if no handler has been registered. On error errno is set appropriately.
paf_ebb_enable_branches() and paf_ebb_disable_branches() return 0 in case of success or -1 otherwise. On error errno is set appropriately.
system does not support EBB facility.
The EBB facility is part of Power ISA [category: Server] first appearing in Power ISA 2.07.
Linux support for the EBB facility first appeared in Linux kernel version 3.10.
Support for the ELF EBB ABI first appeared in glibc version 2.18 though the ABI is not runtime incompatible with backporting to earlier glibc versions.
The following example show how to setup a simple EBB handler to update a global counter.
#define PM_RUN_INST_CMPL 0x400FA
/* Set it
volatile to force memory read in loop below. */
static volatile int ebb_handler_triggered = 0;
int *trigger = (int*) (context);
*trigger += 1;
if (ebb_handler_triggered == 1000)
ebb_handler_triggered = 0;
ebb_fd = paf_ebb_pmu_init (PM_RUN_INST_CMPL, -1);
printf ("Done; %d EBB interrupts handled\n", ebb_handler_triggered);
int main (int
argc, char *argv)
return do_ebb ();
Power ISA™ Version 2.07
Email bug reports to Adhemerval Zanella <firstname.lastname@example.org>.
This manual page was written by Adhemerval Zanella <email@example.com> and Ryan S. Arnold.