pm_set_program_thread_mx and pm_set_program_thread_mm Subroutines

Purpose

Sets Performance Monitor programmation in counter multiplexing mode and multi-mode for a target thread.

Library

Performance Monitor APIs Library (libpmapi.a)

Syntax

#include <pmapi.h>  

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

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

Description

The pm_set_program_thread_mx and the pm_set_program_thread_mm subroutines support only the 1:1 threading model. They have been superseded respectively by the pm_set_program_pthread_mx and the pm_set_program_pthread_mm subroutines, which support both the 1:1 and the M:N threading models. A call to the pm_set_program_thread_mx subroutine or the pm_set_program_thread_mm subroutine is respectively equivalent to a call to the pm_set_program_pthread_mx subroutine or the pm_set_program_pthread_mm subroutine with a ptid parameter equal to 0.

The pm_set_program_thread_mx and the pm_set_program_thread_mm subroutines set the Performance Monitor programmation respectively in counter multiplexing mode or multi-mode 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.

The pm_set_program_thread_mx setting includes the list of the event arrays to be counted and a mode in which to count. The mode is global to all of the event lists. The events to count are in an array of list of event identifiers.

The pm_set_program_thread_mm setting includes the list of the event arrays to be counted, and the associated mode in which to count each event array. A counting mode is defined for each event array.

The event identifiers must be selected from the lists returned by the pm_initialize subroutine.

The counting mode for both subroutines includes the User Mode, or the Kernel Mode, or both of them; and the Initial Counting State. The defaults are set to Off for the User Mode and the Kernel Mode, and the Initial Default State is set to delay counting until the pm_start_thread subroutine is called.

When you use the pm_set_program_thread_mm subroutine for the multi-mode counting, the Process Tree Mode and the Start Counting Mode are fixed by their values in the first programming set.

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

Parameters

Item	Description
pid	Process ID of target thread. Target process must be a debuggee of the caller process.
tid	Thread ID of target thread.
*prog	Specifies the events and the modes to use in the Performance Monitor setup. The prog parameter supports the following modes: PM_USER Counts processes running in the User Mode (default is set to Off). PM_KERNEL Counts processes running in the Kernel Mode (default is set to Off). PM_COUNT Starts counting immediately (default is set to Not to Start Counting).
*prog_mm	Specifies the events and the associated modes to use in the Performance Monitor setup. The prog_mm parameter supports the following modes: PM_USER Counts processes running in the User Mode (default is set to Off). PM_KERNEL Counts processes running in the Kernel Mode (default is set to Off). PM_COUNT Starts counting immediately (default is set to Not to start counting). PM_PROCTREE Sets counting to On only for the calling process and its descendants (default is set to Off). The PM_PROCTREE mode and the PM_COUNT mode defined in the first setting fix the value for the counting.

Return Values

Item	Description
0	Operation completed successfully.
Positive error code	Refer to the pm_error Subroutine to decode the error code.

Error Codes

Refer to the pm_error Subroutine.

Files

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