MON_pubdefs.h File Reference

Public interface to the MON CPU monitor functions. More...

#include <PBS/TASK.h>

Classes
struct	_MON_Load_Stats
	CPU loading statistics. More...
struct	_MON_Perf_Config
	CPU performance monitor configuration. More...
struct	_MON_Perf_Stats
	CPU performance monitor statistics. More...
Typedefs
typedef enum _MON_Perf_Event_1	MON_Perf_Event_1
	Typedef for _MON_Perf_Event_1.
typedef enum _MON_Perf_Event_2	MON_Perf_Event_2
	Typedef for _MON_Perf_Event_2.
typedef enum _MON_Perf_Event_3	MON_Perf_Event_3
	Typedef for _MON_Perf_Event_3.
typedef enum _MON_Perf_Event_4	MON_Perf_Event_4
	Typedef for _MON_Perf_Event_4.
typedef enum _MON_Perf_RTC_Select	MON_Perf_RTC_Select
	Typedef for _MON_Perf_RTC_Select.
typedef struct _MON_Load_Stats	MON_Load_Stats
	Typedef for _MON_Load_Stats.
typedef struct _MON_Perf_Config	MON_Perf_Config
	Typedef for _MON_Perf_Config.
typedef struct _MON_Perf_Stats	MON_Perf_Stats
	Typedef for _MON_Perf_Stats.
typedef void(*	MON_Perf_Cb )(void *cb_parm)
	Signature for performance monitor collection callback function.
Enumerations
enum	_MON_Perf_Event_1 {   MON_EVENT_1_HOLD = 0,   MON_EVENT_1_CYCLE = 1,   MON_EVENT_1_INST_CMPLT = 2,   MON_EVENT_1_BIT_TRANS = 3,   MON_EVENT_1_INST_DISPATCH = 4,   MON_EVENT_1_EIEIO_CMPLT = 5,   MON_EVENT_1_ITLB_SEARCH = 6,   MON_EVENT_1_L2_HIT = 7,   MON_EVENT_1_INST_EA_DELIVER = 8,   MON_EVENT_1_IABR_MATCH = 9,   MON_EVENT_1_L1_MISS_LATENT = 10,   MON_EVENT_1_BR_UNRESOLVE = 11,   MON_EVENT_1_DISPATCH_STALL = 12 }
	Events from set 1 that can be counted. More...
enum	_MON_Perf_Event_2 {   MON_EVENT_2_HOLD = 0,   MON_EVENT_2_CYCLE = 1,   MON_EVENT_2_INST_CMPLT = 2,   MON_EVENT_2_BIT_TRANS = 3,   MON_EVENT_2_INST_DISPATCH = 4,   MON_EVENT_2_L1_INST_MISS = 5,   MON_EVENT_2_ITLB_MISS = 6,   MON_EVENT_2_L2_INST_MISS = 7,   MON_EVENT_2_BR_NOT_TAKEN = 8,   MON_EVENT_2_MSR_PR_TOG = 9,   MON_EVENT_2_RSV_LOAD_CMPLT = 10,   MON_EVENT_2_LD_ST_CMPLT = 11,   MON_EVENT_2_L1_L2_SNOOP = 12,   MON_EVENT_2_L1_CAST_OUT = 13,   MON_EVENT_2_SYS_INST_CMPLT = 14,   MON_EVENT_2_INST_FETCH_MISS = 15,   MON_EVENT_2_BR_RSLV_CORRECT = 16 }
	Events from set 2 that can be counted. More...
enum	_MON_Perf_Event_3 {   MON_EVENT_3_HOLD = 0,   MON_EVENT_3_CYCLE = 1,   MON_EVENT_3_INST_CMPLT = 2,   MON_EVENT_3_BIT_TRANS = 3,   MON_EVENT_3_INST_DISPATCH = 4,   MON_EVENT_3_L1_DATA_MISS = 5,   MON_EVENT_3_DTLB_MISS = 6,   MON_EVENT_3_L2_DATA_MISS = 7,   MON_EVENT_3_BR_TAKEN = 8,   MON_EVENT_3_USR_MSR_PM_TOG = 9,   MON_EVENT_3_ST_COND_CMPLT = 10,   MON_EVENT_3_FPU_INST_CMPLT = 11,   MON_EVENT_3_L2_CAST_OUT = 12,   MON_EVENT_3_L2_HIT = 13,   MON_EVENT_3_L1_MISS_CYCLE = 15,   MON_EVENT_3_SPEC_BR_RSLV = 16,   MON_EVENT_3_BPU_STALL_CYCLE = 17 }
	Events from set 3 that can be counted. More...
enum	_MON_Perf_Event_4 {   MON_EVENT_4_HOLD = 0,   MON_EVENT_4_CYCLE = 1,   MON_EVENT_4_INST_CMPLT = 2,   MON_EVENT_4_BIT_TRANS = 3,   MON_EVENT_4_INST_DISPATCH = 4,   MON_EVENT_4_L2_CAST_OUT = 5,   MON_EVENT_4_DTLB_SEARCH = 6,   MON_EVENT_4_BR_MISPREDICT = 8,   MON_EVENT_4_SPVR_MSR_PM_TOG = 9,   MON_EVENT_4_ST_COND_CMPLT = 10,   MON_EVENT_4_SYNC_CMPLT = 11,   MON_EVENT_4_SNOOP_RETRY = 12,   MON_EVENT_4_INT_OP_CMPLT = 13,   MON_EVENT_4_BPU_FAIL = 14 }
	Events from set 4 that can be counted. More...
enum	_MON_Perf_RTC_Select {   MON_RTC_63 = 0,   MON_RTC_55 = 1,   MON_RTC_51 = 2,   MON_RTC_47 = 3 }
	Time base register bit selections (for 0-to-1 bit transition events). More...
Functions
unsigned int	MON_initialize (void)
	Initialize the MON functions.
unsigned int	MON_shutdown (void)
	Shutdown the MON functions.
unsigned int	MON_start (TASK_attr *idle_attr_p, TASK_attr *poll_attr_p)
	Start the MON functions.
unsigned int	MON_start_with_db (void)
	Start the MON functions using the CPU_DB server.
unsigned int	MON_stop (void)
	Stop the MON functions.
unsigned int	MON_get_loading (MON_Load_Stats *stats_p)
	Get current CPU loading statistics.
unsigned int	MON_start_perf_mon (MON_Perf_Config *cfg_p)
	Start CPU performance monitoring.
unsigned int	MON_stop_perf_mon (MON_Perf_Stats *stats_p)
	Stop CPU performance monitoring.
unsigned int	MON_collect_perf_stats (MON_Perf_Config *cfg_p, unsigned int time_us, MON_Perf_Stats *stats_p, MON_Perf_Cb cb, void *cb_parm)
	Collect performance monitor stats for a specified period of time.
unsigned int	MON_set_watchdog (void)
	Set the hardware watchdog timer.

---

Detailed Description

Public interface to the MON CPU monitor functions.

**  CVS $Id: MON_pubdefs.h,v 1.5 2011/03/28 23:52:02 russell Exp $
**  

Defines the public interface to the functions found in the MON package.

---

Enumeration Type Documentation

enum _MON_Perf_Event_1

Events from set 1 that can be counted.

Enumerator:

MON_EVENT_1_HOLD	Hold current set-1 count value. Since the count value is cleared to zero before each collection period, selecting this event will result in a final count value of zero.
MON_EVENT_1_CYCLE	Count processor cycles.
MON_EVENT_1_INST_CMPLT	Count instructions that have completed.
MON_EVENT_1_BIT_TRANS	Count transitions from 0 to 1 of the time base register bit specified in rtc_select.
MON_EVENT_1_INST_DISPATCH	Count instructions dispatched.
MON_EVENT_1_EIEIO_CMPLT	Count eieio instructions completed.
MON_EVENT_1_ITLB_SEARCH	Count cycles spent performing table search operations for the ITLB.
MON_EVENT_1_L2_HIT	Count accesses that hit the L2.
MON_EVENT_1_INST_EA_DELIVER	Count valid instruction EAs delivered to the memory subsystem.
MON_EVENT_1_IABR_MATCH	Count number of times an instruction address matches the address in the IABR.
MON_EVENT_1_L1_MISS_LATENT	Count loads that miss the L1 with latencies that exceed the threshold value.
MON_EVENT_1_BR_UNRESOLVE	Count branches that are unresolved when processed.
MON_EVENT_1_DISPATCH_STALL	Count cycles the dispatcher stalls due to a second unresolved branch in the instruction stream.

enum _MON_Perf_Event_2

Events from set 2 that can be counted.

Enumerator:

MON_EVENT_2_HOLD	Hold current set-2 count value. Since the count value is cleared to zero before each collection period, selecting this event will result in a final count value of zero.
MON_EVENT_2_CYCLE	Count processor cycles.
MON_EVENT_2_INST_CMPLT	Count instructions that have completed.
MON_EVENT_2_BIT_TRANS	Count transitions from 0 to 1 of the time base register bit specified in rtc_select.
MON_EVENT_2_INST_DISPATCH	Count instructions dispatched.
MON_EVENT_2_L1_INST_MISS	Count L1 instruction cache misses.
MON_EVENT_2_ITLB_MISS	Count ITLB misses.
MON_EVENT_2_L2_INST_MISS	Count L2 instruction misses.
MON_EVENT_2_BR_NOT_TAKEN	Count branches predicted or resolved not taken.
MON_EVENT_2_MSR_PR_TOG	Count MSR[PR] bit toggles.
MON_EVENT_2_RSV_LOAD_CMPLT	Count reserved load operations completed.
MON_EVENT_2_LD_ST_CMPLT	Count completed load and store instructions.
MON_EVENT_2_L1_L2_SNOOP	Count snoops to the L1 and the L2.
MON_EVENT_2_L1_CAST_OUT	Count L1 cast-outs to the L2.
MON_EVENT_2_SYS_INST_CMPLT	Count completed system unit instructions.
MON_EVENT_2_INST_FETCH_MISS	Count instruction fetch misses in the L1.
MON_EVENT_2_BR_RSLV_CORRECT	Count branches allowing out-of-order execution that resolved correctly.

enum _MON_Perf_Event_3

Events from set 3 that can be counted.

Enumerator:

MON_EVENT_3_HOLD	Hold current set-3 count value. Since the count value is cleared to zero before each collection period, selecting this event will result in a final count value of zero.
MON_EVENT_3_CYCLE	Count processor cycles.
MON_EVENT_3_INST_CMPLT	Count instructions that have completed.
MON_EVENT_3_BIT_TRANS	Count transitions from 0 to 1 of the time base register bit specified in rtc_select.
MON_EVENT_3_INST_DISPATCH	Count instructions dispatched.
MON_EVENT_3_L1_DATA_MISS	Count L1 data cache misses.
MON_EVENT_3_DTLB_MISS	Count DTLB misses.
MON_EVENT_3_L2_DATA_MISS	Count L2 data misses.
MON_EVENT_3_BR_TAKEN	Count taken branches, including predicted branches.
MON_EVENT_3_USR_MSR_PM_TOG	Count transitions between marked and unmarked processes while in user mode (i.e. the number of MSR[PM] toggles while the processor is in user mode).
MON_EVENT_3_ST_COND_CMPLT	Count store conditional instructions completed.
MON_EVENT_3_FPU_INST_CMPLT	Count instructions completed from the FPU.
MON_EVENT_3_L2_CAST_OUT	Count L2 castouts caused by snoops to modified lines.
MON_EVENT_3_L2_HIT	Count cache operations that hit in the L2 cache.
MON_EVENT_3_L1_MISS_CYCLE	Count cycles generated by L1 load misses.
MON_EVENT_3_SPEC_BR_RSLV	Count branches in the second speculative stream that resolve correctly.
MON_EVENT_3_BPU_STALL_CYCLE	Count cycles the BPU stalls due to LR or CR unresolved dependencies.

enum _MON_Perf_Event_4

Events from set 4 that can be counted.

Enumerator:

MON_EVENT_4_HOLD	Hold current set-4 count value. Since the count value is cleared to zero before each collection period, selecting this event will result in a final count value of zero.
MON_EVENT_4_CYCLE	Count processor cycles.
MON_EVENT_4_INST_CMPLT	Count instructions that have completed.
MON_EVENT_4_BIT_TRANS	Count transitions from 0 to 1 of the time base register bit specified in rtc_select.
MON_EVENT_4_INST_DISPATCH	Count instructions dispatched.
MON_EVENT_4_L2_CAST_OUT	Count L2 castouts.
MON_EVENT_4_DTLB_SEARCH	Count cycles spent performing table searches for DTLB accesses.
MON_EVENT_4_BR_MISPREDICT	Count mispredicted branches.
MON_EVENT_4_SPVR_MSR_PM_TOG	Count transitions between marked and unmarked processes while in supervisor mode (i.e. the number of MSR[PM] toggles while the processor is in supervisor mode).
MON_EVENT_4_ST_COND_CMPLT	Count store conditional instructions completed with reservation intact.
MON_EVENT_4_SYNC_CMPLT	Count completed sync instructions.
MON_EVENT_4_SNOOP_RETRY	Count snoop request retries.
MON_EVENT_4_INT_OP_CMPLT	Count completed integer operations.
MON_EVENT_4_BPU_FAIL	Count cycles the BPU cannot process new branches due to having two unresolved branches.

enum _MON_Perf_RTC_Select

Time base register bit selections (for 0-to-1 bit transition events).

Enumerator:

MON_RTC_63	Select bit 63, which toggles from 0 to 1 at 1/2 the rate of the time base register.
MON_RTC_55	Select bit 55, which toggles from 0 to 1 at 1/512 the rate of the time base register.
MON_RTC_51	Select bit 51, which toggles from 0 to 1 at 1/8,192 the rate of the time base register.
MON_RTC_47	Select bit 47, which toggles from 0 to 1 at 1/131,072 the rate of the time base register.

---

Function Documentation

unsigned int MON_collect_perf_stats	(	MON_Perf_Config *	cfg_p,
		unsigned int	time_us,
		MON_Perf_Stats *	stats_p,
		MON_Perf_Cb	cb,
		void *	cb_parm
	)

Collect performance monitor stats for a specified period of time.

This function configures and starts the CPU performance monitor facility and establishes a wake-up timer that expires after the specified amount of time. The handler for the wake-up timer stops the CPU event counters and triggers a call to the specified callback function. The callback function is executed in the context of the MON polling task. See also the MON_start_perf_mon() and MON_stop_perf_mon() functions.

Note that all event counters are cleared to zero before counting is started. This means that if the MON_EVENT_x_HOLD event is selected for a counter, its value will be set to 0 and held at that value during the collection period.

Parameters:

	cfg_p	Pointer to performance monitor configuration (must not be NULL).
	time_us	Length of time, in microseconds, to collect statistics.
	stats_p	Pointer to location to return statistics.
	cb	Function to call when the collection is complete.
	cb_parm	Parameter to pass to cb function.

Returns:

Zero if successful.

An error MSG code if the MON package is not in the STARTED state, the CPU is already counting events, or an error occurs.

Referenced by mon_collect_perf_stats_wrap().

unsigned int MON_get_loading

(

MON_Load_Stats *

stats_p

)

Get current CPU loading statistics.

This function returns a snapshot of the CPU loading statistics for the previous minute of operation.

Parameters:

stats_p

Pointer to buffer to store loading statistics (must not be NULL).

Returns:

Zero if successful.

An error MSG code if the MON package is not in the STARTED state or an error occurs.

Referenced by mon_get_loading_wrap().

unsigned int MON_initialize

(

void

)

Initialize the MON functions.

This function initializes the MON package and transitions it to the INITIALIZED state. It should be the first MON function called when using the MON package.

Returns:

Zero if successful.

An error MSG code if the MON package has already been initialized or an error occurs.

Referenced by mon_initialize_wrap().

unsigned int MON_set_watchdog

(

void

)

Set the hardware watchdog timer.

Returns:

Zero if successful.

An error MSG code if an error occurs.

Referenced by mon_set_watchdog_wrap().

unsigned int MON_shutdown

(

void

)

Shutdown the MON functions.

This function shuts down the MON package and transitions it back to the UNINITIALIZED state. It can be called only if the current MON state is INITIALIZED, INIT_FAIL, or SHUTDOWN_FAIL. This function should be called after MON_stop() when the MON package is no longer needed.

Returns:

Zero if successful.

An error MSG code if the MON package is in an invalid state or an error occurs.

Referenced by mon_shutdown_wrap().

unsigned int MON_start	(	TASK_attr *	idle_attr_p,
		TASK_attr *	poll_attr_p
	)

Start the MON functions.

This function starts the various MON tasks and transitions MON to the STARTED state. It can be called only if the current MON state is INITIALIZED. This function should be called after MON_initialize() when using the MON package.

Parameters:

	idle_attr_p	IDLE task attributes. Default task attributes (with a name of 'IDLE' and a priority of 255) will be used if this value is NULL.
	poll_attr_p	POLL task attributes. Default task attributes (with a name of 'POLL' and a priority of 90) will be used if this value is NULL.

Returns:

Zero if successful.

An error MSG code if the MON package is not in the INITIALIZED state or an error occurs.

Referenced by mon_start_wrap().

unsigned int MON_start_perf_mon

(

MON_Perf_Config *

cfg_p

)

Start CPU performance monitoring.

This function configures and starts the CPU performance monitor facility, which counts various CPU events. If started with this function, the CPU will count events until MON_stop_perf_mon() is called. See also the MON_collect_perf_stats() function, which counts CPU events for a specified period of time.

Note that all event counters are cleared to zero before counting is started. This means that if the MON_EVENT_x_HOLD event is selected for a counter, its value will be set to 0 and held at that value during the collection period.

Parameters:

cfg_p

Pointer to performance monitor configuration (must not be NULL).

Returns:

Zero if successful.

An error MSG code if the MON package is not in the STARTED state, the CPU is already counting events, or an error occurs.

Referenced by mon_start_perf_mon_wrap().

unsigned int MON_start_with_db

(

void

)

Start the MON functions using the CPU_DB server.

This function is a wrapper for MON_start. It forces MON_start to use the CPU_DB server to determine the attributes for the POLL and IDLE tasks.

Returns:

Zero if successful.

A MSG code if an error occurs.

Referenced by mon_start_db_wrap().

unsigned int MON_stop

(

void

)

Stop the MON functions.

This function stops the various MON tasks and transitions MON back to the INITIALIZED state. It can be called only if the current MON state is STARTED, START_FAIL, or STOP_FAIL. This function should be called before MON_shutdown() when the MON package is no longer needed.

Returns:

Zero if successful.

An error MSG code if the MON package is in an invalid state or an error occurs.

Referenced by mon_stop_wrap().

unsigned int MON_stop_perf_mon

(

MON_Perf_Stats *

stats_p

)

Stop CPU performance monitoring.

This function stops the CPU from counting events and returns the current counter values. If the CPU is not actively counting events, the most recent event counter values are returned.

Parameters:

stats_p

Pointer to location to store monitor statistics. If this value is NULL, event counting is stopped without returning the event counter values.

Returns:

Zero if successful.

An error MSG code if the MON package is not in the STARTED state or an error occurs.

Referenced by mon_stop_perf_mon_wrap().