1 ==============================================
2 Linux API for read access to z/VM Monitor Reco
3 ==============================================
4
5 Date : 2004-Nov-26
6
7 Author: Gerald Schaefer (geraldsc@de.ibm.com)
8
9
10
11
12 Description
13 ===========
14 This item delivers a new Linux API in the form
15 usable from user space and allows read access
16 collected by the `*MONITOR` System Service of
17
18
19 User Requirements
20 =================
21 The z/VM guest on which you want to access thi
22 order to allow IUCV connections to the `*MONIT
23 IUCV `*MONITOR` statement in its user entry. I
24 restricted (likely), you also need the NAMESAV
25 This item will use the IUCV device driver to a
26 need a kernel with IUCV support. You also need
27
28 There are two options for being able to load t
29 that the monitor DCSS begins at 144 MB and end
30 location of the monitor DCSS with the Class E
31 (the values BEGPAG and ENDPAG are given in uni
32
33 See also "CP Command and Utility Reference" (S
34 on the DEF STOR and Q NSS MAP commands, as wel
35 and Administration" (SC24-6116-00) for more in
36
37 1st option:
38 -----------
39 You can use the CP command DEF STOR CONFIG to
40 guest virtual storage around the address range
41
42 Example: DEF STOR CONFIG 0.140M 200M.200M
43
44 This defines two blocks of storage, the first
45 address 0MB, the second is 200MB in size and b
46 resulting in a total storage of 340MB. Note th
47 always start at 0 and be at least 64MB in size
48
49 2nd option:
50 -----------
51 Your guest virtual storage has to end below th
52 and you have to specify the "mem=" kernel para
53 value greater than the ending address of the D
54
55 Example::
56
57 DEF STOR 140M
58
59 This defines 140MB storage size for your guest
60 added to the parmfile.
61
62
63 User Interface
64 ==============
65 The char device is implemented as a kernel mod
66 which can be loaded via the modprobe command,
67 kernel instead. There is one optional module (
68 to specify the name of the monitor DCSS. If th
69 kernel, the kernel parameter "monreader.mondcs
70 in the parmfile.
71
72 The default name for the DCSS is "MONDCSS" if
73 there are other users already connected to the
74 Performance Toolkit), the monitor DCSS is alre
75 the same DCSS. The CP command Q MONITOR (Class
76 of the monitor DCSS, if already defined, and t
77 `*MONITOR` service.
78 Refer to the "z/VM Performance" book (SC24-610
79 DCSS if your z/VM doesn't have one already, yo
80 define and save a DCSS.
81
82 Example:
83 --------
84
85 ::
86
87 modprobe monreader mondcss=MYDCSS
88
89 This loads the module and sets the DCSS name t
90
91 NOTE:
92 -----
93 This API provides no interface to control the
94 which data should be collected. This can be do
95 (Class E privileged), see "CP Command and Util
96
97 Device nodes with udev:
98 -----------------------
99 After loading the module, a char device will b
100 node /<udev directory>/monreader.
101
102 Device nodes without udev:
103 --------------------------
104 If your distribution does not support udev, a
105 automatically and you have to create it manual
106 Therefore you need to know the major and minor
107 numbers can be found in /sys/class/misc/monrea
108
109 Typing cat /sys/class/misc/monreader/dev will
110 <major>:<minor>. The device node can be create
111 mknod <name> c <major> <minor>, where <name> i
112 to be created.
113
114 Example:
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
124 This loads the module with the default monitor
125 device node.
126
127 File operations:
128 ----------------
129 The following file operations are supported: o
130 There are two alternative methods for reading:
131 conjunction with polling, or blocking read wit
132 supported.
133
134 Read:
135 -----
136 Reading from the device provides a 12 Byte mon
137 followed by a set of one or more contiguous mo
138 output of the CMS utility MONWRITE without the
139 contains information on the type of the follow
140 data), the monitor domains contained within it
141 of the record set in the monitor DCSS. The sta
142 to determine the size of the record set, the e
143 last byte of data. The start address is needed
144 correctly (domain 1, record 13), i.e. it can b
145 start offset relative to a 4K page (frame) bou
146
147 See "Appendix A: `*MONITOR`" in the "z/VM Perf
148 of the monitor control element layout. The lay
149 be found here (z/VM 5.1): https://www.vm.ibm.c
150
151 The layout of the data stream provided by the
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
163 There may be more than one combination of MCE
164 within one data set and the end of each data s
165 read with a return value of 0 (0 byte read).
166 Any received data must be considered invalid u
167 read successfully, including the closing 0 byt
168 always read the complete set into a buffer bef
169
170 The maximum size of a data set can be as large
171 monitor DCSS, so design the buffer adequately
172 The size of the monitor DCSS will be printed i
173 module. You can also use the (Class E privileg
174 list all available segments and information ab
175
176 As with most char devices, error conditions ar
177 negative value for the number of bytes read. I
178 indicates the error condition:
179
180 EIO:
181 reply failed, read data is invalid and th
182 should discard the data read since the la
183 EFAULT:
184 copy_to_user failed, read data is inva
185 discard the data read since the last s
186 EAGAIN:
187 occurs on a non-blocking read if there
188 moment. There is no data missing or co
189 use polling for non-blocking reads.
190 EOVERFLOW:
191 message limit reached, the data rea
192 read with 0 size is valid but subse
193
194 In the last case (EOVERFLOW) there may be miss
195 (EIO, EFAULT) there will be missing data. It's
196 continue reading subsequent data or rather exi
197
198 Open:
199 -----
200 Only one user is allowed to open the char devi
201 open function will fail (return a negative val
202 The open function may also fail if an IUCV con
203 cannot be established. In this case errno will
204 message with an IPUSER SEVER code will be prin
205 codes are described in the "z/VM Performance"
206
207 NOTE:
208 -----
209 As soon as the device is opened, incoming mess
210 will account for the message limit, i.e. openi
211 from it will provoke the "message limit reache
212 eventually.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.