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

日期：2004-11-26

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

描述

此项目提供了一个新的 Linux API，以 misc 字符设备的形式，可从用户空间使用，并允许读取 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 页为单位给出）。

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

第一个选项：

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

示例：

modprobe monreader mondcss=MYDCSS

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

注意：

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

带有 udev 的设备节点：

加载模块后，将创建一个字符设备以及设备节点 /<udev directory>/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) 中，将有数据丢失。 如果应用程序将继续读取后续数据或退出，则由应用程序决定。

打开：

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

注意：

一旦设备打开，传入的消息将被接受，并且它们将计入消息限制，即打开设备而不从中读取最终将导致“达到消息限制”错误（EOVERFLOW 错误代码）。