pm_set_ebb_handler Subroutine
Purpose
Configures the Event-Based Branching (EBB) facility for the calling thread.
Library
Performance Monitor APIs Library (libpmapi.a)
Syntax
#include <pmapi.h>
int pm_set_ebb_handler (void * handler_address, void * data_area,)
Description
The pm_set_ebb_handler subroutine configures EBB and allows user to specify the effective address (EA) of the next instruction to be run based on the occurrence of specific events. Events and frequencies are configured by the thread before calling this subroutine.
Events can be configured by using the pm_set_program_mythread, pm_set_program_pthread, or pm_set_program_thread subroutine. One of these subroutines must be called before calling the pm_set_ebb_handler subroutine. The pm_set_program_* subroutines must be called with the no_inherit flag.
Counter frequencies can be configured by using the pm_set_counter_frequency_mythread, or pm_set_counter_frequency_pthread, or pm_set_counter_frequency_thread subroutine.
- The pm_set_ebb_handler subroutine can be called only by the thread that is profiling itself (self-profiling threads) and it cannot be called if the thread is part of a group.
- The pm_set_ebb_handler subroutine can only be called when the thread mode is 1:1 and when counting for the thread is not started.
Parameters
| Item | Description |
|---|---|
| handler_address | The effective address of the user handler. |
| data_area | The allocated data area. This data area is accessible from the EBB handler. |
Return Values
If unsuccessful, a value other than zero is returned and a positive error code is set. If successful, a value of zero is returned.
Error Codes
The subroutine is unsuccessful if the following error codes are returned:
| Item | Description |
|---|---|
| Pmapi_NoInit | The pm_initialize subroutine is not called. |
| Pmapi_Unsupported_EBBThreadMode | The thread is not running in the 1:1 mode. |
| Pmapi_NoSetProg | The pm_set_program subroutine is not called. |
| Pmapi_Invalid_EBB_handler_addr | The value of the handler_address is NULL. |
| Pmapi_Invalid_EBB_data_addr | The value of the data_area is NULL. |
| Pmapi_Malloc_Err | The malloc subroutine fails while allocating memory to the pthread_EBB_registration_t structure. |
| Pmapi_Invalid_EBB_Config | The PTHREAD_EBB_PMU_TYPE flag is not passed to the pthread subroutine. |
| Pmapi_EBB_Already_Exists | The EBB handler is already setup for the thread. |
| Other non-zero error codes | Returned by the call to the pmsvcs subroutine. |
Files
The pmapi.h file defines standard macros, data types, and subroutines.