arch/s390/monreader.rst

2 Linux API for read access to z/VM Monitor Records
5 Date  : 2004-Nov-26
14 This item delivers a new Linux API in the form of a misc char device that is
15 usable from user space and allows read access to the z/VM Monitor Records
16 collected by the `*MONITOR` System Service of z/VM.
21 The z/VM guest on which you want to access this API needs to be configured in
25 This item will use the IUCV device driver to access the z/VM services, so you
26 need a kernel with IUCV support. You also need z/VM version 4.4 or 5.1.
33 See also "CP Command and Utility Reference" (SC24-6081-00) for more information
35 and Administration" (SC24-6116-00) for more information on DCSSes.
38 -----------
39 You can use the CP command DEF STOR CONFIG to define a "memory hole" in your
46 resulting in a total storage of 340MB. Note that the first block should
50 -----------
52 and you have to specify the "mem=" kernel parameter in your parmfile with a
65 The char device is implemented as a kernel module named "monreader",
78 Refer to the "z/VM Performance" book (SC24-6109-00) on how to create a monitor
79 DCSS if your z/VM doesn't have one already, you need Class E privileges to
80 define and save a DCSS.
83 --------
92 -----
98 -----------------------
99 After loading the module, a char device will be created along with the device
103 --------------------------
104 If your distribution does not support udev, a device node will not be created
115 --------
124 This loads the module with the default monitor DCSS (MONDCSS) and creates a
128 ----------------
130 There are two alternative methods for reading: either non-blocking read in
135 -----
136 Reading from the device provides a 12 Byte monitor control element (MCE),
137 followed by a set of one or more contiguous monitor records (similar to the
143 last byte of data. The start address is needed to handle "end-of-frame" records
145 start offset relative to a 4K page (frame) boundary.
147 See "Appendix A: `*MONITOR`" in the "z/VM Performance" document for a description
149 be found here (z/VM 5.1): https://www.vm.ibm.com/pubs/mon510/index.html
157 	...                       |- data set
164 within one data set and the end of each data set is indicated by a successful
165 read with a return value of 0 (0 byte read).
166 Any received data must be considered invalid until a complete set was
168 always read the complete set into a buffer before processing the data.
170 The maximum size of a data set can be as large as the size of the
176 As with most char devices, error conditions are indicated by returning a
187 	occurs on a non-blocking read if there is no data available at the
189 	use polling for non-blocking reads.
199 -----
201 open function will fail (return a negative value) and set errno to EBUSY.
205 codes are described in the "z/VM Performance" book, Appendix A.
208 -----