요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
=================================================
Linux API for read access to z/VM Monitor Records
=================================================
Date : 2004-Nov-26
Author: Gerald Schaefer (geraldsc@de.ibm.com)
Description
===========
This item delivers a new Linux API in the form of a misc char device that is
usable from user space and allows read access to the z/VM Monitor Records
collected by the `*MONITOR` System Service of z/VM.
User Requirements
=================
The z/VM guest on which you want to access this API needs to be configured in
order to allow IUCV connections to the `*MONITOR` service, i.e. it needs the
IUCV `*MONITOR` statement in its user entry. If the monitor DCSS to be used is
restricted (likely), you also need the NAMESAVE <DCSS NAME> statement.
This item will use the IUCV device driver to access the z/VM services, so you
need a kernel with IUCV support. You also need z/VM version 4.4 or 5.1.
There are two options for being able to load the monitor DCSS (examples assume
that the monitor DCSS begins at 144 MB and ends at 152 MB). You can query the
location of the monitor DCSS with the Class E privileged CP command Q NSS MAP
(the values BEGPAG and ENDPAG are given in units of 4K pages).
See also "CP Command and Utility Reference" (SC24-6081-00) for more information
on the DEF STOR and Q NSS MAP commands, as well as "Saved Segments Planning
and Administration" (SC24-6116-00) for more information on DCSSes.
1st option:
-----------
You can use the CP command DEF STOR CONFIG to define a "memory hole" in your
guest virtual storage around the address range of the DCSS.
Example: DEF STOR CONFIG 0.140M 200M.200M
This defines two blocks of storage, the first is 140MB in size an begins at
address 0MB, the second is 200MB in size and begins at address 200MB,
resulting in a total storage of 340MB. Note that the first block should
always start at 0 and be at least 64MB in size.
2nd option:
-----------
Your guest virtual storage has to end below the starting address of the DCSS
and you have to specify the "mem=" kernel parameter in your parmfile with a
value greater than the ending address of the DCSS.
Example::
DEF STOR 140M
This defines 140MB storage size for your guest, the parameter "mem=160M" is
added to the parmfile.
User Interface
==============
The char device is implemented as a kernel module named "monreader",
which can be loaded via the modprobe command, or it can be compiled into the
kernel instead. There is one optional module (or kernel) parameter, "mondcss",
to specify the name of the monitor DCSS. If the module is compiled into the
kernel, the kernel parameter "monreader.mondcss=<DCSS NAME>" can be specified
in the parmfile.
The default name for the DCSS is "MONDCSS" if none is specified. In case that
there are other users already connected to the `*MONITOR` service (e.g.
Performance Toolkit), the monitor DCSS is already defined and you have to use
the same DCSS. The CP command Q MONITOR (Class E privileged) shows the name
of the monitor DCSS, if already defined, and the users connected to the
`*MONITOR` service.
Refer to the "z/VM Performance" book (SC24-6109-00) on how to create a monitor
DCSS if your z/VM doesn't have one already, you need Class E privileges to
define and save a DCSS.
Example:
--------
::
modprobe monreader mondcss=MYDCSS
This loads the module and sets the DCSS name to "MYDCSS".
NOTE:
-----
This API provides no interface to control the `*MONITOR` service, e.g. specify
which data should be collected. This can be done by the CP command MONITOR
(Class E privileged), see "CP Command and Utility Reference".
Device nodes with udev:
-----------------------
After loading the module, a char device will be created along with the device
node /<udev directory>/monreader.
Device nodes without udev:
--------------------------
If your distribution does not support udev, a device node will not be created
automatically and you have to create it manually after loading the module.
Therefore you need to know the major and minor numbers of the device. These
numbers can be found in /sys/class/misc/monreader/dev.
Typing cat /sys/class/misc/monreader/dev will give an output of the form
<major>:<minor>. The device node can be created via the mknod command, enter
mknod <name> c <major> <minor>, where <name> is the name of the device node
to be created.
Example:
--------
::
# modprobe monreader
# cat /sys/class/misc/monreader/dev
10:63
# mknod /dev/monreader c 10 63
This loads the module with the default monitor DCSS (MONDCSS) and creates a
device node.
File operations:
----------------
The following file operations are supported: open, release, read, poll.
There are two alternative methods for reading: either non-blocking read in
conjunction with polling, or blocking read without polling. IOCTLs are not
supported.
Read:
-----
Reading from the device provides a 12 Byte monitor control element (MCE),
followed by a set of one or more contiguous monitor records (similar to the
output of the CMS utility MONWRITE without the 4K control blocks). The MCE
contains information on the type of the following record set (sample/event
data), the monitor domains contained within it and the start and end address
of the record set in the monitor DCSS. The start and end address can be used
to determine the size of the record set, the end address is the address of the
last byte of data. The start address is needed to handle "end-of-frame" records
correctly (domain 1, record 13), i.e. it can be used to determine the record
start offset relative to a 4K page (frame) boundary.
See "Appendix A: `*MONITOR`" in the "z/VM Performance" document for a description
of the monitor control element layout. The layout of the monitor records can
be found here (z/VM 5.1): https://www.vm.ibm.com/pubs/mon510/index.html
The layout of the data stream provided by the monreader device is as follows::
...
<0 byte read>
<first MCE> \
<first set of records> |
... |- data set
<last MCE> |
<last set of records> /
<0 byte read>
...
There may be more than one combination of MCE and corresponding record set
within one data set and the end of each data set is indicated by a successful
read with a return value of 0 (0 byte read).
Any received data must be considered invalid until a complete set was
read successfully, including the closing 0 byte read. Therefore you should
always read the complete set into a buffer before processing the data.
The maximum size of a data set can be as large as the size of the
monitor DCSS, so design the buffer adequately or use dynamic memory allocation.
The size of the monitor DCSS will be printed into syslog after loading the
module. You can also use the (Class E privileged) CP command Q NSS MAP to
list all available segments and information about them.
As with most char devices, error conditions are indicated by returning a
negative value for the number of bytes read. In this case, the errno variable
indicates the error condition:
EIO:
reply failed, read data is invalid and the application
should discard the data read since the last successful read with 0 size.
EFAULT:
copy_to_user failed, read data is invalid and the application should
discard the data read since the last successful read with 0 size.
EAGAIN:
occurs on a non-blocking read if there is no data available at the
moment. There is no data missing or corrupted, just try again or rather
use polling for non-blocking reads.
EOVERFLOW:
message limit reached, the data read since the last successful
read with 0 size is valid but subsequent records may be missing.
In the last case (EOVERFLOW) there may be missing data, in the first two cases
(EIO, EFAULT) there will be missing data. It's up to the application if it will
continue reading subsequent data or rather exit.
Open:
-----
Only one user is allowed to open the char device. If it is already in use, the
open function will fail (return a negative value) and set errno to EBUSY.
The open function may also fail if an IUCV connection to the `*MONITOR` service
cannot be established. In this case errno will be set to EIO and an error
message with an IPUSER SEVER code will be printed into syslog. The IPUSER SEVER
codes are described in the "z/VM Performance" book, Appendix A.
NOTE:
-----
As soon as the device is opened, incoming messages will be accepted and they
will account for the message limit, i.e. opening the device without reading
from it will provoke the "message limit reached" error (EOVERFLOW error code)
eventually.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
z/VM Monitor Records 읽기용 Linux API
1-11이 문서는 2004년 11월 26일 Gerald Schaefer가 작성한 z/VM Monitor Records 읽기 API 설명서입니다.
설명
12-18이 기능은 사용자 공간에서 사용할 수 있는 miscellaneous 문자 장치 형태의 새 Linux API를 제공합니다. 이 장치를 통해 z/VM의 `*MONITOR` System Service가 수집한 z/VM Monitor Records를 읽을 수 있습니다.
사용자 요구 사항
19-36API를 사용할 z/VM 게스트는 `*MONITOR` 서비스로 IUCV 연결을 허용하도록 구성해야 합니다. 즉, 사용자 항목에 IUCV `*MONITOR` 문장이 필요합니다. 사용할 monitor DCSS가 제한되어 있다면 일반적으로 `NAMESAVE <DCSS NAME>` 문장도 필요합니다.
이 기능은 IUCV 장치 드라이버를 통해 z/VM 서비스에 접근하므로 IUCV를 지원하는 커널이 필요합니다. 지원 대상으로 명시된 z/VM 버전은 4.4 또는 5.1입니다.
monitor DCSS를 적재하는 방법은 두 가지입니다. 예제는 DCSS가 144 MB에서 시작해 152 MB에서 끝난다고 가정합니다. Class E 권한의 CP 명령 `Q NSS MAP`으로 위치를 조회할 수 있으며, `BEGPAG`와 `ENDPAG` 값의 단위는 4K 페이지입니다.
`DEF STOR`와 `Q NSS MAP`은 "CP Command and Utility Reference"(SC24-6081-00), DCSS는 "Saved Segments Planning and Administration"(SC24-6116-00)을 참조하십시오.
첫 번째 DCSS 적재 방법
37-48CP 명령 `DEF STOR CONFIG`를 사용해 게스트 가상 저장소에서 DCSS 주소 범위를 둘러싼 메모리 구멍을 정의할 수 있습니다.
DEF STOR CONFIG 0.140M 200M.200M이 예는 두 저장소 블록을 정의합니다. 첫 번째 블록은 0MB에서 시작하는 140MB이고, 두 번째 블록은 200MB에서 시작하는 200MB이므로 총 저장소 크기는 340MB입니다. 첫 번째 블록은 항상 0에서 시작해야 하며 크기는 최소 64MB여야 합니다.
두 번째 DCSS 적재 방법
49-62게스트 가상 저장소를 DCSS 시작 주소보다 아래에서 끝내고, parmfile의 `mem=` 커널 매개변수를 DCSS 끝 주소보다 큰 값으로 지정할 수 있습니다.
DEF STOR 140M이 예는 게스트 저장소 크기를 140MB로 정의하고 parmfile에는 `mem=160M`을 추가합니다.
사용자 인터페이스와 mondcss
63-96문자 장치는 `monreader` 커널 모듈로 구현됩니다. `modprobe`로 적재하거나 커널에 내장할 수 있습니다. 선택적 모듈 또는 커널 매개변수 `mondcss`는 monitor DCSS 이름을 지정합니다. 커널 내장 구성에서는 parmfile에 `monreader.mondcss=<DCSS NAME>`을 지정합니다.
이름을 지정하지 않으면 기본 DCSS 이름은 `MONDCSS`입니다. Performance Toolkit 같은 다른 사용자가 이미 `*MONITOR` 서비스에 연결되어 있다면 monitor DCSS도 이미 정의되어 있으므로 같은 DCSS를 사용해야 합니다. Class E 권한의 CP 명령 `Q MONITOR`는 이미 정의된 monitor DCSS 이름과 연결된 사용자를 표시합니다.
z/VM에 monitor DCSS가 아직 없다면 "z/VM Performance"(SC24-6109-00)의 생성 방법을 따르십시오. DCSS를 정의하고 저장하려면 Class E 권한이 필요합니다.
modprobe monreader mondcss=MYDCSS이 명령은 모듈을 적재하고 DCSS 이름을 `MYDCSS`로 설정합니다.
이 API는 수집할 데이터 지정 등 `*MONITOR` 서비스를 제어하는 인터페이스를 제공하지 않습니다. 해당 제어에는 Class E 권한의 CP 명령 `MONITOR`를 사용하며 자세한 내용은 "CP Command and Utility Reference"를 참조하십시오.
udev가 있는 장치 노드
97-101모듈을 적재하면 문자 장치와 함께 `/<udev directory>/monreader` 장치 노드가 생성됩니다.
udev가 없는 장치 노드
102-126배포판이 udev를 지원하지 않으면 장치 노드가 자동으로 생성되지 않으므로 모듈을 적재한 뒤 직접 만들어야 합니다. 필요한 major와 minor 번호는 `/sys/class/misc/monreader/dev`에서 확인합니다.
`cat /sys/class/misc/monreader/dev`의 출력 형식은 `<major>:<minor>`입니다. `mknod <name> c <major> <minor>`로 문자 장치 노드를 만들며 `<name>`은 생성할 장치 노드 이름입니다.
# modprobe monreader
# cat /sys/class/misc/monreader/dev
10:63
# mknod /dev/monreader c 10 63예제는 기본 monitor DCSS인 `MONDCSS`로 모듈을 적재하고 major 10, minor 63인 `/dev/monreader`를 생성합니다.
파일 연산
127-133지원하는 파일 연산은 `open`, `release`, `read`, `poll`입니다. 읽기는 polling과 함께 쓰는 non-blocking read 또는 polling 없이 쓰는 blocking read 두 방식 가운데 하나를 선택합니다. IOCTL은 지원하지 않습니다.
MCE와 monitor record 읽기
134-150장치를 읽으면 12 Byte monitor control element(MCE)가 먼저 오고 그 뒤에 연속된 monitor record 집합 하나 이상이 이어집니다. 이는 4K control block을 제외한 CMS 유틸리티 `MONWRITE` 출력과 비슷합니다.
MCE에는 뒤따르는 record 집합의 유형(sample 또는 event 데이터), 포함된 monitor domain, monitor DCSS 안에서의 시작 주소와 끝 주소가 들어 있습니다. 시작·끝 주소로 record 집합 크기를 계산하며 끝 주소는 데이터의 마지막 바이트 주소입니다.
시작 주소는 domain 1, record 13인 `end-of-frame` record를 올바르게 처리하는 데 필요합니다. 즉, 4K 페이지(frame) 경계에 대한 record 시작 오프셋을 계산할 수 있습니다.
MCE 배치는 "z/VM Performance"의 "Appendix A: `*MONITOR`"를 참조하십시오. z/VM 5.1 monitor record 배치는 다음 링크에 있습니다.
데이터 스트림과 완전성
151-175`monreader` 장치가 제공하는 데이터 스트림의 구조는 다음과 같습니다.
성공한 0바이트 읽기 사이에 하나 이상의 MCE와 대응 record 집합이 순서대로 놓입니다.
한 데이터 집합 안에는 MCE와 대응 record 집합 조합이 둘 이상 있을 수 있습니다. 각 데이터 집합의 끝은 반환값 0인 성공한 읽기, 즉 0 byte read로 표시됩니다.
닫는 0바이트 읽기까지 포함해 완전한 집합을 성공적으로 읽기 전에는 수신 데이터를 유효한 것으로 간주하면 안 됩니다. 데이터를 처리하기 전에 항상 전체 집합을 버퍼로 읽으십시오.
데이터 집합 최대 크기는 monitor DCSS 전체 크기만큼 클 수 있으므로 버퍼를 충분히 크게 설계하거나 동적 메모리 할당을 사용해야 합니다. 모듈 적재 후 monitor DCSS 크기가 syslog에 기록되며, Class E 권한의 CP 명령 `Q NSS MAP`으로 사용 가능한 모든 segment와 정보를 나열할 수도 있습니다.
read 오류 조건
176-197대부분의 문자 장치처럼 오류는 읽은 바이트 수 대신 음수를 반환하여 알리고, `errno`가 오류 조건을 나타냅니다.
| errno | 의미와 데이터 처리 |
|---|---|
| `EIO` | 응답이 실패했습니다. 읽은 데이터는 유효하지 않으므로 마지막으로 성공한 0바이트 읽기 이후의 데이터를 버려야 합니다. |
| `EFAULT` | `copy_to_user`가 실패했습니다. 읽은 데이터는 유효하지 않으므로 마지막으로 성공한 0바이트 읽기 이후의 데이터를 버려야 합니다. |
| `EAGAIN` | non-blocking read 시 현재 사용 가능한 데이터가 없습니다. 누락되거나 손상된 데이터는 없으므로 다시 시도하거나 polling을 사용합니다. |
| `EOVERFLOW` | message limit에 도달했습니다. 마지막으로 성공한 0바이트 읽기 이후 데이터는 유효하지만 뒤따르는 record가 누락됐을 수 있습니다. |
`EOVERFLOW`에서는 데이터가 누락됐을 가능성이 있고 `EIO`와 `EFAULT`에서는 데이터 누락이 확실합니다. 이후 데이터를 계속 읽을지 종료할지는 애플리케이션이 결정합니다.
open 제약과 message limit
198-212문자 장치는 한 사용자만 열 수 있습니다. 이미 사용 중이면 `open`은 음수를 반환하고 `errno`를 `EBUSY`로 설정합니다.
`*MONITOR` 서비스로 IUCV 연결을 만들 수 없어도 `open`이 실패할 수 있습니다. 이때 `errno`는 `EIO`이고 IPUSER SEVER 코드가 포함된 오류 메시지가 syslog에 기록됩니다. 코드는 "z/VM Performance"의 Appendix A에 설명돼 있습니다.
장치를 여는 즉시 들어오는 메시지를 수락하며 이 메시지는 message limit에 포함됩니다. 장치를 열어 놓고 읽지 않으면 결국 `message limit reached`, 즉 `EOVERFLOW` 오류가 발생합니다.
요약과 해설
monreader.rst:1-212`monreader`는 IUCV를 통해 z/VM `*MONITOR` 서비스의 monitor DCSS를 읽는 문자 장치입니다. 게스트 저장소와 DCSS 주소가 겹치지 않게 구성하고, 필요하면 `mondcss`로 이미 사용 중인 DCSS 이름을 맞춰야 합니다.
읽기 단위는 MCE와 대응 record 집합의 연속이며 0바이트 읽기가 데이터 집합 완료를 확정합니다. 이 종료 표식을 받기 전 데이터는 처리하면 안 되고, `EIO`, `EFAULT`, `EOVERFLOW`에 따라 폐기 범위와 누락 가능성을 구분해야 합니다.