pm_initialize 子例程

用途

初始化性能监视器 API 并返回有关处理器的信息。

库

性能监视器 API 库 (libpmapi.a)

语法

#include <pmapi.h>

int pm_initialize ( filter,  *pminfo, *pmgroups, proctype)
int filter;
pm_info2_t *pminfo;
pm_groups_info_t *pmgroups;
int proctype;

描述

pm_initialize 子例程初始化 Performance Monitor API 库并检索有关处理器类型的信息 (如果指定的 proctype 不是 PM_CURRENT)。 它会将事件状态的 过滤器 考虑在内，然后返回此处理器上可用的计数器数以及包含可用事件列表的每个计数器的一个表。 对于每个事件，它提供一个事件标识，一个状态，两个名称和一个描述。 状态包含一组标志，指示: 事件状态，事件是否可与阈值配合使用，事件是否为共享事件，以及事件是否为仅分组事件。

事件标识与所有 pm_set_program 接口配合使用，并且还由所有 pm_get_program 接口返回。 只能使用返回的表中存在的事件标识。 换言之， 过滤器 对所有 API 调用都有效。

状态描述事件是已验证，仍未验证，还是使用某些警告，如描述中所述。 此字段是必需的，因为过滤器可以是三个可用状态位的任意组合。 该标志指向可与阈值配合使用的事件。

只有归类为已验证的事件才已完全验证。 仅使用事件描述中记录的限制来验证分类为 caveat 的事件。 分类为 未验证 的事件具有未定义的准确性。 谨慎使用 未验证 事件; 性能监视器软件本质上提供了用于读取硬件寄存器的服务，这些硬件寄存器可能具有也可能没有有意义的内容。 用户可自行使用未经验证的事件计数器进行试验，以确定它们是否可用于特定调整情境。

为事件表中基于关键字的简单搜索提供了简短助记符名称 (请参阅样本程序 /usr/samples/pmapi/cpi.c 以获取使用助记符名称的代码)。 还提供了事件的完整名称，并且将返回每个事件的完整描述。

返回的结构还包含此处理器的阈值乘数，处理器名称及其特征。 在某些平台上，最多有三个阈值乘数可用。

在某些平台上，可以指定事件组而不是个别事件。 事件组是预定义的事件集。 指定单个组标识，而不是单独指定每个事件。 在某些平台 (例如 POWER4) 上，必须使用事件组，并且指定个别事件会返回错误。

pm_initialize 接口在其第三个参数中返回受支持事件组的列表。 如果 pm_initialize 返回的 pmgroups 参数为 NULL ，那么平台不支持任何事件组。 否则，将在 event_groups 字段中返回 pm_groups_t 结构的数组。 数组的长度由 max_groups 字段给出。

pm_groups_t 结构包含组标识，两个名称和描述，它们都与各个事件的组标识和描述相似。 此外，整数数组指定组中包含的事件。

如果 proctype 参数未设置为 PM_CURRENT，那么不会初始化性能监视器 API 库，并且子例程仅返回有关指定处理器以及其参数 (pminfo 和 pmgroups) 中可用的事件和组的信息，同时考虑过滤器。 如果 proctype 参数设置为 PM_CURRENT，那么除了返回描述的信息外，还会初始化 Performance Monitor API 库并准备接受其他调用。

参数

返回值

错误代码

请参阅 pm_error 子例程。

文件