Reading monitor records

6.10 z/VM guest

You can either read in non-blocking mode with polling, or you can read in blocking mode without polling.

About this task

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 4 K control blocks). The MCE contains information about:
  • The type of the following record set (sample/event data)
  • The monitor domains contained within it
  • 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), that is, it can be used to determine the record start offset relative to a 4 K page (frame) boundary.
See "Appendix A: *MONITOR" in z/VM: Performance, SC24-6301 for a description of the monitor control element layout. The layout of the monitor records can be found on 
www.ibm.com/vm/pubs/ctlblk.html
The layout of the data stream that is 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 might be more than one combination of MCE and a corresponding record set within one data set. The end of each data set is indicated by a successful read with a return value of 0 (0 byte read). Received data is not to be considered valid unless a complete record set is read successfully, including the closing 0-Byte read. You are advised to always read the complete set into a user space buffer before processing the data.

When designing a buffer, allow for record sizes up to the size of the entire monitor DCSS, 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.

Error conditions are indicated by returning a negative value for the number of bytes read. For an error condition, the errno variable can be:

EIO
Reply failed. All data that was read since the last successful read with 0 size is not valid. Data is missing. The application must decide whether to continue reading subsequent data or to exit.
EFAULT
Copy to user failed. All data that was read since the last successful read with 0 size is not valid. Data is missing. The application must decide whether to continue reading subsequent data or to exit.
EAGAIN
Occurs on a non-blocking read if there is no data available at the moment. No data is missing or damaged, retry or use polling for non-blocking reads.
EOVERFLOW
The message limit is reached. The data that was read since the last successful read with 0 size is valid, but subsequent records might be missing. The application must decide whether to continue reading subsequent data or to exit.