用於讀取 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 錯誤程式碼）。