pm_enable_bhrb Subroutine

Edit online

Purpose

Enables all Branch History Rolling Buffer (BHRB) related instructions such as clrbhrb and mfbhrb in the problem state and configures the Branch History Rolling Buffer Enable (BHRBE) filtering modes.

Library

Performance Monitor APIs Library (libpmapi.a)

Syntax

#include <pmapi.h>
int pm_enable_bhrb (pm_bhrb_ifm_t ifm_mode)

Description

The pm_enable_bhrb subroutine enables the BHRB instructions such as clrbhrb and mfbhrb in the problem state and configures the BHRBE filtering modes.

Note: The pm_enable_bhrb subroutine can be called only when the thread mode is 1:1 and when counting for the thread is not started.

Parameters

Item Description
ifm_mode BHRBE filtering mode.

The ifm_mode parameter can take one of the following values as defined in the pm_bhrb_ifm_t structure:

typedef enum
{
	BHRB_IFM0 = 0,
	BHRB_IFM1,
	BHRB_IFM2,
	BHRB_IFM3
}pm_bhrb_ifm_t;
where,
  • BHRB_IFM0 - No filtering.
  • BHRB_IFM1 - Do not record any branch instructions unless the value of the LK field is set to 1.
  • BHRB_IFM2 - Do not record I-Form instructions. For the B-Form and XL-Form instructions for which the BO field indicates Branch always, do not record the instruction. If it is a B-Form instruction, do not record the instruction address but record only the branch target address. If it is a XL-Form, do not record the I-Form instructions.
  • BHRB_IFM3 - Filter and enter BHRB entries for the mode 10. For B-Form and XL-Form instructions for which the BO field is set to 1 or for which the a bit in the BO field is set to 1, do not record the instruction. If it is B-Form and do not record the instruction address but record only the branch target address if it is XL-Form.
For Power10 processor-based servers, the definition of the ifm_mode parameter is as follows:
00
All branch instructions that are taken by the processor are entered into the BHRB.
01
Only taken calls are entered into the BHRB. The calls include the following direct and indirect calls: bl, bla, bcl, bcla, bclrl, bcctrl, bctarl.
10
Only the following taken indirect branch instructions (excluding calls) are entered into BHRB: bclr, bcctr, bctar. This means that all XL-Form taken branch instructions with LK=0 are entered.
11
Only the following taken conditional branch instructions are entered into BHRB: bc, bca, bcl, bcla, bclr, bclrl, bcctr, bcctrl, bctar, bctarl. This means that all B-Form or XL-Form taken branch instructions are entered except those branch instructions with the BO field set to Branch Always (BO=0b1z1zz).

When the BHRB is written by the hardware, only the Branch instructions that meet the filtering criteria and for which the branch are included are termed as BHRB entries (BHRBE).

Return Values

If unsuccessful, a value other than zero is returned and 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_NoSetProg The pm_set_program subroutine is not called.
Pmapi_Invalid_IFMMode The value of an ifm_mode is not valid.
Other non-zero error codes Returned by the pmsvcs subroutine.

Files

The pmapi.h file defines standard macros, data types, and subroutines.