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 only be called 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.

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.