pm_get_program_thread_mx and pm_get_program_thread_mm Subroutines

Purpose

Retrieves the Performance Monitor settings in counter multiplexing mode and multi-mode for a target thread.

Library

Performance Monitor APIs Library (libpmapi.a)

Syntax

#include <pmapi.h>

int pm_get_program_thread_mx ( pid,  tid,  *prog)
pid_t pid;
tid_t tid;
pm_prog_mx_t *prog;

int pm_get_program_thread_mm (pid, tid, *prog_mm)
pid_t pid;
tid_t tid;
pm_prog_mm_t *prog_mm;

Description

These subroutines support only the 1:1 threading model. They have been superseded respectively by the pm_get_program_pthread_mx and the pm_get_program_pthread_mm subroutines, which support both the 1:1 and the M:N threading models. A call to the pm_get_program_thread_mx subroutine or to the pm_get_program_thread_mm subroutine is respectively equivalent to a call to the pm_get_program_pthread_mx subroutine or the pm_get_program_pthread_mm subroutine with a ptid parameter equal to 0.

The pm_get_program_thread_mx subroutine and the pm_get_program_thread_mm subroutine retrieve the Performance Monitor settings for a target kernel thread. The thread must be stopped and must be part of a debuggee process under the control of the calling process. This includes mode information and the events being counted, which are in an array of list of event identifiers. The event identifiers come from the lists returned by the pm_initialize subroutine.

When counting in multiplexing mode, the mode is global to all of the events lists. When counting in multi-mode, a mode is associated to each event list.

Counting mode includes the user mode, the kernel mode, and the current counting state.

If the list includes an event which can be used with a threshold (as indicated by the pm_init subroutine), a threshold value is also returned.

The user application must free the allocated array to store the event lists (the events_set field in the prog parameter).

Parameters

Item	Description
pid	Process identifier of the target thread. The target process must be an argument of a debug process.
tid	Thread identifier of the target thread.
*prog	Returns which Performance Monitor events and modes are set. It supports the following modes: PM_USER Counting processes running in User Mode. PM_KERNEL Counting processes running in Kernel Mode. PM_COUNT Counting is On.
*prog_mm	Returns which Performance Monitor events and associated modes are set. It supports the following modes: PM_USER Counting processes running in User Mode. PM_KERNEL Counting processes running in Kernel Mode. PM_COUNT Counting is On. PM_PROCTREE Counting that applies only to the calling process and its descendants. The PM_PROCTREE mode and the PM_COUNT mode are common to all modes set.

Return Values

Item	Description
0	No errors occurred.
Positive error code	See the pm_error Subroutine to decode the error code.

Error Codes

See the pm_error Subroutine.

Files

Item	Description
/usr/include/pmapi.h	Defines standard macros, data types, and subroutines.