# @(#)62	1.1  src/bos/usr/sbin/perf/pmapi/libpmapi/README, pmapi, bos720 8/3/01 15:57:33
# IBM_PROLOG_BEGIN_TAG 
# This is an automatically generated prolog. 
#  
# bos720 src/bos/usr/sbin/perf/pmapi/libpmapi/README 1.1 
#  
# Licensed Materials - Property of IBM 
#  
# COPYRIGHT International Business Machines Corp. 2001 
# All Rights Reserved 
#  
# US Government Users Restricted Rights - Use, duplication or 
# disclosure restricted by GSA ADP Schedule Contract with IBM Corp. 
#  
# IBM_PROLOG_END_TAG 
-----------------------------------------

Performance Monitoring API - Event Groups

-----------------------------------------

The Performance Monitoring API Has been extended to enable the
specification of event groups instead of individual events.  Event 
groups are predefined sets of events. Rather than specify each event 
individually, a single group ID is specified.  On POWER4 platforms, 
use of the event groups is required, and attempts to specify individual 
events will return an error.

The interface to pm_init has been enhanced to return the list of 
supported event groups in a new, third parameter.  For binary 
compatibility, the third parameter must be explicitly requested by 
OR-ing the bitflag, PM_GET_GROUPS, into the filter.  The function is 
declared as follows:

int pm_init(int filter, pm_info_t *pm_info, pm_groups_info_t *pm_groups_info);

where pm_groups_info_t is defined in pmapi.h as:

typedef struct {
        int            maxgroups;      /* number of available groups */
        pm_groups_t    *event_groups;  /* list of event groups */
} pm_groups_info_t;

and pm_groups_t is defined as:

typedef struct {                        /* structure for available events */
        int             group_id;       /* group number */
        int             *events;        /* events in this group, by ID # */
        char            *short_name;    /* mnemonic name */
        char            *long_name;     /* long name */
        char            *description;   /* full description */
} pm_groups_t;

If the pm_groups_info parameter returned by pm_init is NULL, then there 
are no supported event groups for the platform. Otherwise an array of 
pm_groups_t structures are returned in the event_groups field.  The length
of the array is given by the max_groups field.

The pm_groups_t structure contains a short_name, long_name, and description
that are similar to those in the pm_events_t structure.  In addition, 
there are the group_id, which is the integer that refers to this event 
group, and the events, an array of integers that lists the individual 
events contained in that group.

With this information, pm_set_program can be used to specify an event 
group via the group_id.  A new bitfield in pm_mode_t, is_group, is set 
to indicate that an event group is being specified, and the group 
ID is placed into the first element of the events array in the pm_prog_t
structure passed to pm_set_program.

Similarly, in pm_get_program, the pm_mode_t structure that is returned 
will indicate whether or not an event_group was specified by way of the 
is_group bit, which, if set, indicates that the first element of the 
pm_prog_t's events array contains the group ID, and the rest of the 
events are don't-care.