用于读取 z/VM 监视器记录的 Linux API

日期：2004 年 11 月 26 日

作者：Gerald Schaefer (geraldsc@de.ibm.com)

描述

此项提供了一个新的 Linux API，以杂项字符设备的形式存在，可以从用户空间使用，并允许读取 z/VM 的 *MONITOR 系统服务收集的 z/VM 监视器记录。

用户要求

您要访问此 API 的 z/VM 客户机需要配置为允许 IUCV 连接到 *MONITOR 服务，即，它需要在其用户条目中包含 IUCV *MONITOR 语句。如果要使用的监视器 DCSS 受限制（很可能），您还需要 NAMESAVE <DCSS NAME> 语句。此项将使用 IUCV 设备驱动程序来访问 z/VM 服务，因此您需要一个支持 IUCV 的内核。您还需要 z/VM 4.4 或 5.1 版本。

有两种选项可以加载监视器 DCSS（示例假设监视器 DCSS 从 144 MB 开始，到 152 MB 结束）。您可以使用 Class E 特权 CP 命令 Q NSS MAP 查询监视器 DCSS 的位置（BEGPAG 和 ENDPAG 的值以 4K 页为单位）。

有关 DEF STOR 和 Q NSS MAP 命令的更多信息，请参阅“CP 命令和实用程序参考”（SC24-6081-00），有关 DCSS 的更多信息，请参阅“已保存段规划和管理”（SC24-6116-00）。

第一种选项：

您可以使用 CP 命令 DEF STOR CONFIG 在您的客户机虚拟存储中围绕 DCSS 的地址范围定义一个“内存空洞”。

示例：DEF STOR CONFIG 0.140M 200M.200M

这将定义两个存储块，第一个大小为 140MB，从地址 0MB 开始，第二个大小为 200MB，从地址 200MB 开始，总存储空间为 340MB。请注意，第一个块应始终从 0 开始，并且大小至少为 64MB。

第二种选项：

您的客户机虚拟存储必须在 DCSS 的起始地址之下结束，并且您必须在 parmfile 中使用“mem=”内核参数，其值大于 DCSS 的结束地址。

示例

DEF STOR 140M

这将为您的客户机定义 140MB 的存储大小，参数“mem=160M”添加到 parmfile 中。

用户界面

字符设备实现为一个名为“monreader”的内核模块，可以通过 modprobe 命令加载，也可以编译到内核中。有一个可选模块（或内核）参数“mondcss”，用于指定监视器 DCSS 的名称。如果模块编译到内核中，则可以在 parmfile 中指定内核参数“monreader.mondcss=<DCSS NAME>”。

如果没有指定，DCSS 的默认名称为“MONDCSS”。如果已经有其他用户连接到 *MONITOR 服务（例如，Performance Toolkit），则监视器 DCSS 已经定义，您必须使用相同的 DCSS。如果已经定义，CP 命令 Q MONITOR（Class E 特权）会显示监视器 DCSS 的名称以及连接到 *MONITOR 服务的用户。请参阅“z/VM Performance”一书 (SC24-6109-00)，了解如何在 z/VM 中创建监视器 DCSS（如果您的 z/VM 还没有监视器 DCSS），您需要 Class E 特权来定义和保存 DCSS。

示例：

modprobe monreader mondcss=MYDCSS

这将加载模块并将 DCSS 名称设置为“MYDCSS”。

注意：

此 API 不提供控制 *MONITOR 服务的接口，例如，指定应收集哪些数据。这可以通过 CP 命令 MONITOR（Class E 特权）完成，请参阅“CP 命令和实用程序参考”。

使用 udev 的设备节点：

加载模块后，将创建一个字符设备以及设备节点 /<udev 目录>/monreader。

不使用 udev 的设备节点：

如果您的发行版不支持 udev，则不会自动创建设备节点，您必须在加载模块后手动创建它。因此，您需要知道设备的主编号和次编号。这些数字可以在 /sys/class/misc/monreader/dev 中找到。

键入 cat /sys/class/misc/monreader/dev 将给出 <major>:<minor> 形式的输出。设备节点可以通过 mknod 命令创建，输入 mknod <name> c <major> <minor>，其中 <name> 是要创建的设备节点的名称。

示例：

# modprobe monreader
# cat /sys/class/misc/monreader/dev
10:63
# mknod /dev/monreader c 10 63

这将加载具有默认监视器 DCSS (MONDCSS) 的模块并创建一个设备节点。

文件操作：

支持以下文件操作：open、release、read、poll。有两种读取的替代方法：一种是与轮询结合使用的非阻塞读取，另一种是不使用轮询的阻塞读取。不支持 IOCTL。

读取：

从设备读取会提供一个 12 字节的监视器控制元素 (MCE)，后跟一组一个或多个连续的监视器记录（类似于 CMS 实用程序 MONWRITE 的输出，但不包括 4K 控制块）。MCE 包含有关以下记录集类型（采样/事件数据）、其中包含的监视器域以及监视器 DCSS 中记录集的起始地址和结束地址的信息。起始地址和结束地址可用于确定记录集的大小，结束地址是数据的最后一个字节的地址。需要起始地址来正确处理“帧尾”记录（域 1，记录 13），即，它可用于确定相对于 4K 页（帧）边界的记录起始偏移量。

有关监视器控制元素布局的说明，请参阅“z/VM Performance”文档中的“附录 A：*MONITOR”。监视器记录的布局可以在这里找到 (z/VM 5.1)：https://www.vm.ibm.com/pubs/mon510/index.html

monreader 设备提供的数据流的布局如下

...
<0 byte read>
<first MCE>              \
<first set of records>    |
...                       |- data set
<last MCE>                |
<last set of records>    /
<0 byte read>
...

一个数据集中可能存在多个 MCE 和相应的记录集组合，并且每个数据集的末尾都由成功的读取（返回值为 0（0 字节读取））表示。在成功读取包括关闭 0 字节读取的完整集之前，收到的任何数据都必须被视为无效。因此，在处理数据之前，您应始终将整个集读取到缓冲区中。

数据集的最大大小可以与监视器 DCSS 的大小一样大，因此请充分设计缓冲区或使用动态内存分配。加载模块后，监视器 DCSS 的大小将打印到 syslog 中。您还可以使用（Class E 特权）CP 命令 Q NSS MAP 列出所有可用的段及其相关信息。

与大多数字符设备一样，错误情况通过返回读取的字节数的负值来指示。在这种情况下，errno 变量指示错误情况

EIO

回复失败，读取的数据无效，应用程序应丢弃自上次成功读取且大小为 0 以来的读取数据。

EFAULT

copy_to_user 失败，读取的数据无效，应用程序应丢弃自上次成功读取且大小为 0 以来的读取数据。

EAGAIN

如果在当前没有数据可用时，在非阻塞读取时发生。没有数据丢失或损坏，只需重试或最好使用轮询进行非阻塞读取。

EOVERFLOW

达到消息限制，自上次成功读取且大小为 0 以来的读取数据有效，但可能缺少后续记录。

在最后一种情况 (EOVERFLOW) 中，可能会缺少数据，在前两种情况 (EIO, EFAULT) 中，将缺少数据。是否继续读取后续数据还是退出由应用程序决定。

打开：

只允许一个用户打开字符设备。如果字符设备已被使用，则 open 函数将失败（返回一个负值）并将 errno 设置为 EBUSY。如果无法建立到 *MONITOR 服务的 IUCV 连接，open 函数也可能失败。在这种情况下，errno 将设置为 EIO，并且带有 IPUSER SEVER 代码的错误消息将打印到 syslog 中。“z/VM Performance”一书的附录 A 中描述了 IPUSER SEVER 代码。

注意:

一旦设备被打开，就会接受传入的消息，并且这些消息将计入消息限制。也就是说，打开设备而不从中读取数据最终会引发“消息限制已达到”的错误（EOVERFLOW 错误代码）。