arch/s390/monreader.rst

2 Linux API for read access to z/VM Monitor Records
5 Date  : 2004-Nov-26
15 usable from user space and allows read access to the z/VM Monitor Records
21 The z/VM guest on which you want to access this API needs to be configured in
22 order to allow IUCV connections to the `*MONITOR` service, i.e. it needs the
23 IUCV `*MONITOR` statement in its user entry. If the monitor DCSS to be used is
25 This item will use the IUCV device driver to access the z/VM services, so you
28 There are two options for being able to load the monitor DCSS (examples assume
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
50 -----------
51 Your guest virtual storage has to end below the starting address of the DCSS
52 and you have to specify the "mem=" kernel parameter in your parmfile with a
60 added to the parmfile.
68 to specify the name of the monitor DCSS. If the module is compiled into the
73 there are other users already connected to the `*MONITOR` service (e.g.
74 Performance Toolkit), the monitor DCSS is already defined and you have to use
76 of the monitor DCSS, if already defined, and the users connected to the
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
83 --------
89 This loads the module and sets the DCSS name to "MYDCSS".
92 -----
93 This API provides no interface to control the `*MONITOR` service, e.g. specify
98 -----------------------
103 --------------------------
105 automatically and you have to create it manually after loading the module.
106 Therefore you need to know the major and minor numbers of the device. These
112 to be created.
115 --------
128 ----------------
129 The following file operations are supported: open, release, read, poll.
130 There are two alternative methods for reading: either non-blocking read in
131 conjunction with polling, or blocking read without polling. IOCTLs are not
134 Read:
135 -----
137 followed by a set of one or more contiguous monitor records (similar to the
142 to determine the size of the record set, the end address is the address of the
143 last byte of data. The start address is needed to handle "end-of-frame" records
144 correctly (domain 1, record 13), i.e. it can be used to determine the record
145 start offset relative to a 4K page (frame) boundary.
154 	<0 byte read>
157 	...                       |- data set
160 	<0 byte read>
165 read with a return value of 0 (0 byte read).
167 read successfully, including the closing 0 byte read. Therefore you should
168 always read the complete set into a buffer before processing the data.
173 module. You can also use the (Class E privileged) CP command Q NSS MAP to
177 negative value for the number of bytes read. In this case, the errno variable
181      reply failed, read data is invalid and the application
182      should discard the data read since the last successful read with 0 size.
184 	copy_to_user failed, read data is invalid and the application should
185 	discard the data read since the last successful read with 0 size.
187 	occurs on a non-blocking read if there is no data available at the
189 	use polling for non-blocking reads.
191 	   message limit reached, the data read since the last successful
192 	   read with 0 size is valid but subsequent records may be missing.
195 (EIO, EFAULT) there will be missing data. It's up to the application if it will
199 -----
200 Only one user is allowed to open the char device. If it is already in use, the
201 open function will fail (return a negative value) and set errno to EBUSY.
202 The open function may also fail if an IUCV connection to the `*MONITOR` service
203 cannot be established. In this case errno will be set to EIO and an error
208 -----