1================================================= 2Linux API for read access to z/VM Monitor Records 3================================================= 4 5Date : 2004-Nov-26 6 7Author: Gerald Schaefer (geraldsc@de.ibm.com) 8 9 10 11 12Description 13=========== 14This item delivers a new Linux API in the form of a misc char device that is 15usable from user space and allows read access to the z/VM Monitor Records 16collected by the `*MONITOR` System Service of z/VM. 17 18 19User Requirements 20================= 21The z/VM guest on which you want to access this API needs to be configured in 22order to allow IUCV connections to the `*MONITOR` service, i.e. it needs the 23IUCV `*MONITOR` statement in its user entry. If the monitor DCSS to be used is 24restricted (likely), you also need the NAMESAVE <DCSS NAME> statement. 25This item will use the IUCV device driver to access the z/VM services, so you 26need a kernel with IUCV support. You also need z/VM version 4.4 or 5.1. 27 28There are two options for being able to load the monitor DCSS (examples assume 29that the monitor DCSS begins at 144 MB and ends at 152 MB). You can query the 30location of the monitor DCSS with the Class E privileged CP command Q NSS MAP 31(the values BEGPAG and ENDPAG are given in units of 4K pages). 32 33See also "CP Command and Utility Reference" (SC24-6081-00) for more information 34on the DEF STOR and Q NSS MAP commands, as well as "Saved Segments Planning 35and Administration" (SC24-6116-00) for more information on DCSSes. 36 371st option: 38----------- 39You can use the CP command DEF STOR CONFIG to define a "memory hole" in your 40guest virtual storage around the address range of the DCSS. 41 42Example: DEF STOR CONFIG 0.140M 200M.200M 43 44This defines two blocks of storage, the first is 140MB in size an begins at 45address 0MB, the second is 200MB in size and begins at address 200MB, 46resulting in a total storage of 340MB. Note that the first block should 47always start at 0 and be at least 64MB in size. 48 492nd option: 50----------- 51Your guest virtual storage has to end below the starting address of the DCSS 52and you have to specify the "mem=" kernel parameter in your parmfile with a 53value greater than the ending address of the DCSS. 54 55Example:: 56 57 DEF STOR 140M 58 59This defines 140MB storage size for your guest, the parameter "mem=160M" is 60added to the parmfile. 61 62 63User Interface 64============== 65The char device is implemented as a kernel module named "monreader", 66which can be loaded via the modprobe command, or it can be compiled into the 67kernel instead. There is one optional module (or kernel) parameter, "mondcss", 68to specify the name of the monitor DCSS. If the module is compiled into the 69kernel, the kernel parameter "monreader.mondcss=<DCSS NAME>" can be specified 70in the parmfile. 71 72The default name for the DCSS is "MONDCSS" if none is specified. In case that 73there are other users already connected to the `*MONITOR` service (e.g. 74Performance Toolkit), the monitor DCSS is already defined and you have to use 75the same DCSS. The CP command Q MONITOR (Class E privileged) shows the name 76of the monitor DCSS, if already defined, and the users connected to the 77`*MONITOR` service. 78Refer to the "z/VM Performance" book (SC24-6109-00) on how to create a monitor 79DCSS if your z/VM doesn't have one already, you need Class E privileges to 80define and save a DCSS. 81 82Example: 83-------- 84 85:: 86 87 modprobe monreader mondcss=MYDCSS 88 89This loads the module and sets the DCSS name to "MYDCSS". 90 91NOTE: 92----- 93This API provides no interface to control the `*MONITOR` service, e.g. specify 94which data should be collected. This can be done by the CP command MONITOR 95(Class E privileged), see "CP Command and Utility Reference". 96 97Device nodes with udev: 98----------------------- 99After loading the module, a char device will be created along with the device 100node /<udev directory>/monreader. 101 102Device nodes without udev: 103-------------------------- 104If your distribution does not support udev, a device node will not be created 105automatically and you have to create it manually after loading the module. 106Therefore you need to know the major and minor numbers of the device. These 107numbers can be found in /sys/class/misc/monreader/dev. 108 109Typing cat /sys/class/misc/monreader/dev will give an output of the form 110<major>:<minor>. The device node can be created via the mknod command, enter 111mknod <name> c <major> <minor>, where <name> is the name of the device node 112to be created. 113 114Example: 115-------- 116 117:: 118 119 # modprobe monreader 120 # cat /sys/class/misc/monreader/dev 121 10:63 122 # mknod /dev/monreader c 10 63 123 124This loads the module with the default monitor DCSS (MONDCSS) and creates a 125device node. 126 127File operations: 128---------------- 129The following file operations are supported: open, release, read, poll. 130There are two alternative methods for reading: either non-blocking read in 131conjunction with polling, or blocking read without polling. IOCTLs are not 132supported. 133 134Read: 135----- 136Reading from the device provides a 12 Byte monitor control element (MCE), 137followed by a set of one or more contiguous monitor records (similar to the 138output of the CMS utility MONWRITE without the 4K control blocks). The MCE 139contains information on the type of the following record set (sample/event 140data), the monitor domains contained within it and the start and end address 141of the record set in the monitor DCSS. The start and end address can be used 142to determine the size of the record set, the end address is the address of the 143last byte of data. The start address is needed to handle "end-of-frame" records 144correctly (domain 1, record 13), i.e. it can be used to determine the record 145start offset relative to a 4K page (frame) boundary. 146 147See "Appendix A: `*MONITOR`" in the "z/VM Performance" document for a description 148of the monitor control element layout. The layout of the monitor records can 149be found here (z/VM 5.1): https://www.vm.ibm.com/pubs/mon510/index.html 150 151The layout of the data stream provided by the monreader device is as follows:: 152 153 ... 154 <0 byte read> 155 <first MCE> \ 156 <first set of records> | 157 ... |- data set 158 <last MCE> | 159 <last set of records> / 160 <0 byte read> 161 ... 162 163There may be more than one combination of MCE and corresponding record set 164within one data set and the end of each data set is indicated by a successful 165read with a return value of 0 (0 byte read). 166Any received data must be considered invalid until a complete set was 167read successfully, including the closing 0 byte read. Therefore you should 168always read the complete set into a buffer before processing the data. 169 170The maximum size of a data set can be as large as the size of the 171monitor DCSS, so design the buffer adequately or use dynamic memory allocation. 172The size of the monitor DCSS will be printed into syslog after loading the 173module. You can also use the (Class E privileged) CP command Q NSS MAP to 174list all available segments and information about them. 175 176As with most char devices, error conditions are indicated by returning a 177negative value for the number of bytes read. In this case, the errno variable 178indicates the error condition: 179 180EIO: 181 reply failed, read data is invalid and the application 182 should discard the data read since the last successful read with 0 size. 183EFAULT: 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. 186EAGAIN: 187 occurs on a non-blocking read if there is no data available at the 188 moment. There is no data missing or corrupted, just try again or rather 189 use polling for non-blocking reads. 190EOVERFLOW: 191 message limit reached, the data read since the last successful 192 read with 0 size is valid but subsequent records may be missing. 193 194In the last case (EOVERFLOW) there may be missing data, in the first two cases 195(EIO, EFAULT) there will be missing data. It's up to the application if it will 196continue reading subsequent data or rather exit. 197 198Open: 199----- 200Only one user is allowed to open the char device. If it is already in use, the 201open function will fail (return a negative value) and set errno to EBUSY. 202The open function may also fail if an IUCV connection to the `*MONITOR` service 203cannot be established. In this case errno will be set to EIO and an error 204message with an IPUSER SEVER code will be printed into syslog. The IPUSER SEVER 205codes are described in the "z/VM Performance" book, Appendix A. 206 207NOTE: 208----- 209As soon as the device is opened, incoming messages will be accepted and they 210will account for the message limit, i.e. opening the device without reading 211from it will provoke the "message limit reached" error (EOVERFLOW error code) 212eventually. 213