<!DOCTYPE html>
<html lang="en" data-content_root="../../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Linux API for read access to z/VM Monitor Records — The Linux Kernel documentation</title>
<link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../../_static/alabaster.css?v=3918102e" />
<script src="../../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../../_static/doctools.js?v=9bcbadda"></script>
<script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
<link rel="next" title="IBM s390 QDIO Ethernet Driver" href="qeth.html" />
<link rel="prev" title="Memory Management" href="mm.html" />
<link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
</head><body>
<div class="document">
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../../index.html">
<img class="logo" src="../../_static/logo.svg" alt="Logo of The Linux Kernel"/>
</a></p>
<h1 class="logo"><a href="../../index.html">The Linux Kernel</a></h1>
<p class="blurb">6.18.50</p>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
<p>
<h3 class="kernel-toc-contents">Contents</h3>
<input type="checkbox" class="kernel-toc-toggle" id = "kernel-toc-toggle" checked>
<label class="kernel-toc-title" for="kernel-toc-toggle"></label>
<div class="kerneltoc" id="kerneltoc">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../process/development-process.html">Development process</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../process/submitting-patches.html">Submitting patches</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../process/code-of-conduct.html">Code of conduct</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../maintainer/index.html">Maintainer handbook</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../process/index.html">All development-process docs</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../core-api/index.html">Core API</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../driver-api/index.html">Driver APIs</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../subsystem-apis.html">Subsystems</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../locking/index.html">Locking</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../process/license-rules.html">Licensing rules</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../doc-guide/index.html">Writing documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../dev-tools/index.html">Development tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../dev-tools/testing-overview.html">Testing guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../kernel-hacking/index.html">Hacking guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../trace/index.html">Tracing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../fault-injection/index.html">Fault injection</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../livepatch/index.html">Livepatching</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../rust/index.html">Rust</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../admin-guide/index.html">Administration</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../kbuild/index.html">Build system</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../admin-guide/reporting-issues.html">Reporting issues</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../tools/index.html">Userspace tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../userspace-api/index.html">Userspace API</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../firmware-guide/index.html">Firmware</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../devicetree/index.html">Firmware and Devicetree</a></li>
</ul>
<ul class="current">
<li class="toctree-l1 current"><a class="reference internal" href="../index.html">CPU architectures</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../arc/index.html">ARC architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../arm/index.html">ARM Architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../arm64/index.html">ARM64 Architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../loongarch/index.html">LoongArch Architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../m68k/index.html">m68k Architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../mips/index.html">MIPS-specific Documentation</a></li>
<li class="toctree-l2"><a class="reference internal" href="../nios2/index.html">Nios II Specific Documentation</a></li>
<li class="toctree-l2"><a class="reference internal" href="../openrisc/index.html">OpenRISC Architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../parisc/index.html">PA-RISC Architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../powerpc/index.html">powerpc</a></li>
<li class="toctree-l2"><a class="reference internal" href="../riscv/index.html">RISC-V architecture</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="index.html">s390 Architecture</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="cds.html">Linux for S/390 and zSeries</a></li>
<li class="toctree-l3"><a class="reference internal" href="3270.html">IBM 3270 Display System support</a></li>
<li class="toctree-l3"><a class="reference internal" href="driver-model.html">S/390 driver model interfaces</a></li>
<li class="toctree-l3"><a class="reference internal" href="mm.html">Memory Management</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#">Linux API for read access to z/VM Monitor Records</a></li>
<li class="toctree-l3"><a class="reference internal" href="qeth.html">IBM s390 QDIO Ethernet Driver</a></li>
<li class="toctree-l3"><a class="reference internal" href="s390dbf.html">S390 Debug Feature</a></li>
<li class="toctree-l3"><a class="reference internal" href="vfio-ap.html">Adjunct Processor (AP) facility</a></li>
<li class="toctree-l3"><a class="reference internal" href="vfio-ap-locking.html">VFIO AP Locks Overview</a></li>
<li class="toctree-l3"><a class="reference internal" href="vfio-ccw.html">vfio-ccw: the basic infrastructure</a></li>
<li class="toctree-l3"><a class="reference internal" href="zfcpdump.html">The s390 SCSI dump tool (zfcpdump)</a></li>
<li class="toctree-l3"><a class="reference internal" href="common_io.html">S/390 common I/O-Layer</a></li>
<li class="toctree-l3"><a class="reference internal" href="pci.html">S/390 PCI</a></li>
<li class="toctree-l3"><a class="reference internal" href="text_files.html">ibm 3270 changelog</a></li>
<li class="toctree-l3"><a class="reference internal" href="text_files.html#ibm-3270-config3270-sh">ibm 3270 config3270.sh</a></li>
<li class="toctree-l3"><a class="reference internal" href="features.html">Feature status on s390 architecture</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../sh/index.html">SuperH Interfaces Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="../sparc/index.html">Sparc Architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../x86/index.html">x86-specific Documentation</a></li>
<li class="toctree-l2"><a class="reference internal" href="../xtensa/index.html">Xtensa Architecture</a></li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../staging/index.html">Unsorted documentation</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../translations/index.html">Translations</a></li>
</ul>
</div>
<script type="text/javascript"> <!--
var sbar = document.getElementsByClassName("sphinxsidebar")[0];
let currents = document.getElementsByClassName("current")
if (currents.length) {
sbar.scrollTop = currents[currents.length - 1].offsetTop;
}
--> </script>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../_sources/arch/s390/monreader.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
</div>
</div>
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="linux-api-for-read-access-to-z-vm-monitor-records">
<h1>Linux API for read access to z/VM Monitor Records<a class="headerlink" href="#linux-api-for-read-access-to-z-vm-monitor-records" title="Link to this heading">¶</a></h1>
<p>Date : 2004-Nov-26</p>
<p>Author: Gerald Schaefer (<a class="reference external" href="mailto:geraldsc%40de.ibm.com">geraldsc<span>@</span>de<span>.</span>ibm<span>.</span>com</a>)</p>
<section id="description">
<h2>Description<a class="headerlink" href="#description" title="Link to this heading">¶</a></h2>
<p>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 <cite>*MONITOR</cite> System Service of z/VM.</p>
</section>
<section id="user-requirements">
<h2>User Requirements<a class="headerlink" href="#user-requirements" title="Link to this heading">¶</a></h2>
<p>The z/VM guest on which you want to access this API needs to be configured in
order to allow IUCV connections to the <cite>*MONITOR</cite> service, i.e. it needs the
IUCV <cite>*MONITOR</cite> 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.</p>
<p>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).</p>
<p>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.</p>
<section id="st-option">
<h3>1st option:<a class="headerlink" href="#st-option" title="Link to this heading">¶</a></h3>
<p>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.</p>
<p>Example: DEF STOR CONFIG 0.140M 200M.200M</p>
<p>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.</p>
</section>
<section id="nd-option">
<h3>2nd option:<a class="headerlink" href="#nd-option" title="Link to this heading">¶</a></h3>
<p>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.</p>
<p>Example:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>DEF STOR 140M
</pre></div>
</div>
<p>This defines 140MB storage size for your guest, the parameter “mem=160M” is
added to the parmfile.</p>
</section>
</section>
<section id="user-interface">
<h2>User Interface<a class="headerlink" href="#user-interface" title="Link to this heading">¶</a></h2>
<p>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.</p>
<p>The default name for the DCSS is “MONDCSS” if none is specified. In case that
there are other users already connected to the <cite>*MONITOR</cite> 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
<cite>*MONITOR</cite> 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.</p>
<section id="example">
<h3>Example:<a class="headerlink" href="#example" title="Link to this heading">¶</a></h3>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>modprobe monreader mondcss=MYDCSS
</pre></div>
</div>
<p>This loads the module and sets the DCSS name to “MYDCSS”.</p>
</section>
<section id="note">
<h3>NOTE:<a class="headerlink" href="#note" title="Link to this heading">¶</a></h3>
<p>This API provides no interface to control the <cite>*MONITOR</cite> 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”.</p>
</section>
<section id="device-nodes-with-udev">
<h3>Device nodes with udev:<a class="headerlink" href="#device-nodes-with-udev" title="Link to this heading">¶</a></h3>
<p>After loading the module, a char device will be created along with the device
node /<udev directory>/monreader.</p>
</section>
<section id="device-nodes-without-udev">
<h3>Device nodes without udev:<a class="headerlink" href="#device-nodes-without-udev" title="Link to this heading">¶</a></h3>
<p>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.</p>
<p>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.</p>
</section>
<section id="id1">
<h3>Example:<a class="headerlink" href="#id1" title="Link to this heading">¶</a></h3>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># modprobe monreader
# cat /sys/class/misc/monreader/dev
10:63
# mknod /dev/monreader c 10 63
</pre></div>
</div>
<p>This loads the module with the default monitor DCSS (MONDCSS) and creates a
device node.</p>
</section>
<section id="file-operations">
<h3>File operations:<a class="headerlink" href="#file-operations" title="Link to this heading">¶</a></h3>
<p>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.</p>
</section>
<section id="read">
<h3>Read:<a class="headerlink" href="#read" title="Link to this heading">¶</a></h3>
<p>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.</p>
<p>See “Appendix A: <cite>*MONITOR</cite>” 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): <a class="reference external" href="https://www.vm.ibm.com/pubs/mon510/index.html">https://www.vm.ibm.com/pubs/mon510/index.html</a></p>
<p>The layout of the data stream provided by the monreader device is as follows:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>...
<0 byte read>
<first MCE> \
<first set of records> |
... |- data set
<last MCE> |
<last set of records> /
<0 byte read>
...
</pre></div>
</div>
<p>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.</p>
<p>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.</p>
<p>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:</p>
<dl class="simple">
<dt>EIO:</dt><dd><p>reply failed, read data is invalid and the application
should discard the data read since the last successful read with 0 size.</p>
</dd>
<dt>EFAULT:</dt><dd><p>copy_to_user failed, read data is invalid and the application should
discard the data read since the last successful read with 0 size.</p>
</dd>
<dt>EAGAIN:</dt><dd><p>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.</p>
</dd>
<dt>EOVERFLOW:</dt><dd><p>message limit reached, the data read since the last successful
read with 0 size is valid but subsequent records may be missing.</p>
</dd>
</dl>
<p>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.</p>
</section>
<section id="open">
<h3>Open:<a class="headerlink" href="#open" title="Link to this heading">¶</a></h3>
<p>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 <cite>*MONITOR</cite> 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.</p>
</section>
<section id="id2">
<h3>NOTE:<a class="headerlink" href="#id2" title="Link to this heading">¶</a></h3>
<p>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.</p>
</section>
</section>
</section>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©The kernel development community.
|
Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.1.3</a>
& <a href="https://alabaster.readthedocs.io">Alabaster 0.7.16</a>
|
<a href="../../_sources/arch/s390/monreader.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>