pm_init 子例程

用途

初始化性能监视器 API。

库

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

语法

#include <pmapi.h>

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

描述

pm_init 子例程初始化性能监视器 API 库。 在考虑了事件状态的 过滤器 ，此处理器上可用的计数器数量以及每个具有可用事件列表的计数器的一个表之后，它将返回值。 对于每个事件，提供了事件标识，状态，指示事件是否可与阈值一起使用的标志，两个名称和描述。

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

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

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

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

返回的结构还具有此处理器的阈值乘数和处理器名称

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

已增强 pm_init 的接口，以在可选的第三个参数中返回受支持事件组的列表。 对于二进制兼容性，第三个参数必须由将位标志 PM_GET_GROUPS 显式地请求到 filter 参数中。

如果 pm_init 返回的 pm_groups_info 参数为 NULL ，那么平台不支持任何事件组。 否则，将在 event_groups 字段中返回 pm_groups_t 结构的数组。 数组的长度由 max_groups 字段给出。

pm_groups_t 结构包含与各个事件相似的组标识，两个名称和描述。 此外，还有一个整数数组，用于指定组中包含的事件。

参数

返回值

错误代码

请参阅 pm_error (pm_error Subroutine) 子例程。

文件