ia64/linux-2.6.18-xen.hg

view Documentation/i2o/ioctl @ 897:329ea0ccb344

balloon: try harder to balloon up under memory pressure.

Currently if the balloon driver is unable to increase the guest's
reservation it assumes the failure was due to reaching its full
allocation, gives up on the ballooning operation and records the limit
it reached as the "hard limit". The driver will not try again until
the target is set again (even to the same value).

However it is possible that ballooning has in fact failed due to
memory pressure in the host and therefore it is desirable to keep
attempting to reach the target in case memory becomes available. The
most likely scenario is that some guests are ballooning down while
others are ballooning up and therefore there is temporary memory
pressure while things stabilise. You would not expect a well behaved
toolstack to ask a domain to balloon to more than its allocation nor
would you expect it to deliberately over-commit memory by setting
balloon targets which exceed the total host memory.

This patch drops the concept of a hard limit and causes the balloon
driver to retry increasing the reservation on a timer in the same
manner as when decreasing the reservation.

Also if we partially succeed in increasing the reservation
(i.e. receive less pages than we asked for) then we may as well keep
those pages rather than returning them to Xen.

Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
author Keir Fraser <keir.fraser@citrix.com>
date Fri Jun 05 14:01:20 2009 +0100 (2009-06-05)
parents 831230e53067
children
line source
2 Linux I2O User Space Interface
3 rev 0.3 - 04/20/99
5 =============================================================================
6 Originally written by Deepak Saxena(deepak@plexity.net)
7 Currently maintained by Deepak Saxena(deepak@plexity.net)
8 =============================================================================
10 I. Introduction
12 The Linux I2O subsystem provides a set of ioctl() commands that can be
13 utilized by user space applications to communicate with IOPs and devices
14 on individual IOPs. This document defines the specific ioctl() commands
15 that are available to the user and provides examples of their uses.
17 This document assumes the reader is familiar with or has access to the
18 I2O specification as no I2O message parameters are outlined. For information
19 on the specification, see http://www.i2osig.org
21 This document and the I2O user space interface are currently maintained
22 by Deepak Saxena. Please send all comments, errata, and bug fixes to
23 deepak@csociety.purdue.edu
25 II. IOP Access
27 Access to the I2O subsystem is provided through the device file named
28 /dev/i2o/ctl. This file is a character file with major number 10 and minor
29 number 166. It can be created through the following command:
31 mknod /dev/i2o/ctl c 10 166
33 III. Determining the IOP Count
35 SYNOPSIS
37 ioctl(fd, I2OGETIOPS, int *count);
39 u8 count[MAX_I2O_CONTROLLERS];
41 DESCRIPTION
43 This function returns the system's active IOP table. count should
44 point to a buffer containing MAX_I2O_CONTROLLERS entries. Upon
45 returning, each entry will contain a non-zero value if the given
46 IOP unit is active, and NULL if it is inactive or non-existent.
48 RETURN VALUE.
50 Returns 0 if no errors occur, and -1 otherwise. If an error occurs,
51 errno is set appropriately:
53 EFAULT Invalid user space pointer was passed
55 IV. Getting Hardware Resource Table
57 SYNOPSIS
59 ioctl(fd, I2OHRTGET, struct i2o_cmd_hrt *hrt);
61 struct i2o_cmd_hrtlct
62 {
63 u32 iop; /* IOP unit number */
64 void *resbuf; /* Buffer for result */
65 u32 *reslen; /* Buffer length in bytes */
66 };
68 DESCRIPTION
70 This function returns the Hardware Resource Table of the IOP specified
71 by hrt->iop in the buffer pointed to by hrt->resbuf. The actual size of
72 the data is written into *(hrt->reslen).
74 RETURNS
76 This function returns 0 if no errors occur. If an error occurs, -1
77 is returned and errno is set appropriately:
79 EFAULT Invalid user space pointer was passed
80 ENXIO Invalid IOP number
81 ENOBUFS Buffer not large enough. If this occurs, the required
82 buffer length is written into *(hrt->reslen)
84 V. Getting Logical Configuration Table
86 SYNOPSIS
88 ioctl(fd, I2OLCTGET, struct i2o_cmd_lct *lct);
90 struct i2o_cmd_hrtlct
91 {
92 u32 iop; /* IOP unit number */
93 void *resbuf; /* Buffer for result */
94 u32 *reslen; /* Buffer length in bytes */
95 };
97 DESCRIPTION
99 This function returns the Logical Configuration Table of the IOP specified
100 by lct->iop in the buffer pointed to by lct->resbuf. The actual size of
101 the data is written into *(lct->reslen).
103 RETURNS
105 This function returns 0 if no errors occur. If an error occurs, -1
106 is returned and errno is set appropriately:
108 EFAULT Invalid user space pointer was passed
109 ENXIO Invalid IOP number
110 ENOBUFS Buffer not large enough. If this occurs, the required
111 buffer length is written into *(lct->reslen)
113 VI. Settting Parameters
115 SYNOPSIS
117 ioctl(fd, I2OPARMSET, struct i2o_parm_setget *ops);
119 struct i2o_cmd_psetget
120 {
121 u32 iop; /* IOP unit number */
122 u32 tid; /* Target device TID */
123 void *opbuf; /* Operation List buffer */
124 u32 oplen; /* Operation List buffer length in bytes */
125 void *resbuf; /* Result List buffer */
126 u32 *reslen; /* Result List buffer length in bytes */
127 };
129 DESCRIPTION
131 This function posts a UtilParamsSet message to the device identified
132 by ops->iop and ops->tid. The operation list for the message is
133 sent through the ops->opbuf buffer, and the result list is written
134 into the buffer pointed to by ops->resbuf. The number of bytes
135 written is placed into *(ops->reslen).
137 RETURNS
139 The return value is the size in bytes of the data written into
140 ops->resbuf if no errors occur. If an error occurs, -1 is returned
141 and errno is set appropriatly:
143 EFAULT Invalid user space pointer was passed
144 ENXIO Invalid IOP number
145 ENOBUFS Buffer not large enough. If this occurs, the required
146 buffer length is written into *(ops->reslen)
147 ETIMEDOUT Timeout waiting for reply message
148 ENOMEM Kernel memory allocation error
150 A return value of 0 does not mean that the value was actually
151 changed properly on the IOP. The user should check the result
152 list to determine the specific status of the transaction.
154 VII. Getting Parameters
156 SYNOPSIS
158 ioctl(fd, I2OPARMGET, struct i2o_parm_setget *ops);
160 struct i2o_parm_setget
161 {
162 u32 iop; /* IOP unit number */
163 u32 tid; /* Target device TID */
164 void *opbuf; /* Operation List buffer */
165 u32 oplen; /* Operation List buffer length in bytes */
166 void *resbuf; /* Result List buffer */
167 u32 *reslen; /* Result List buffer length in bytes */
168 };
170 DESCRIPTION
172 This function posts a UtilParamsGet message to the device identified
173 by ops->iop and ops->tid. The operation list for the message is
174 sent through the ops->opbuf buffer, and the result list is written
175 into the buffer pointed to by ops->resbuf. The actual size of data
176 written is placed into *(ops->reslen).
178 RETURNS
180 EFAULT Invalid user space pointer was passed
181 ENXIO Invalid IOP number
182 ENOBUFS Buffer not large enough. If this occurs, the required
183 buffer length is written into *(ops->reslen)
184 ETIMEDOUT Timeout waiting for reply message
185 ENOMEM Kernel memory allocation error
187 A return value of 0 does not mean that the value was actually
188 properly retrieved. The user should check the result list
189 to determine the specific status of the transaction.
191 VIII. Downloading Software
193 SYNOPSIS
195 ioctl(fd, I2OSWDL, struct i2o_sw_xfer *sw);
197 struct i2o_sw_xfer
198 {
199 u32 iop; /* IOP unit number */
200 u8 flags; /* DownloadFlags field */
201 u8 sw_type; /* Software type */
202 u32 sw_id; /* Software ID */
203 void *buf; /* Pointer to software buffer */
204 u32 *swlen; /* Length of software buffer */
205 u32 *maxfrag; /* Number of fragments */
206 u32 *curfrag; /* Current fragment number */
207 };
209 DESCRIPTION
211 This function downloads a software fragment pointed by sw->buf
212 to the iop identified by sw->iop. The DownloadFlags, SwID, SwType
213 and SwSize fields of the ExecSwDownload message are filled in with
214 the values of sw->flags, sw->sw_id, sw->sw_type and *(sw->swlen).
216 The fragments _must_ be sent in order and be 8K in size. The last
217 fragment _may_ be shorter, however. The kernel will compute its
218 size based on information in the sw->swlen field.
220 Please note that SW transfers can take a long time.
222 RETURNS
224 This function returns 0 no errors occur. If an error occurs, -1
225 is returned and errno is set appropriatly:
227 EFAULT Invalid user space pointer was passed
228 ENXIO Invalid IOP number
229 ETIMEDOUT Timeout waiting for reply message
230 ENOMEM Kernel memory allocation error
232 IX. Uploading Software
234 SYNOPSIS
236 ioctl(fd, I2OSWUL, struct i2o_sw_xfer *sw);
238 struct i2o_sw_xfer
239 {
240 u32 iop; /* IOP unit number */
241 u8 flags; /* UploadFlags */
242 u8 sw_type; /* Software type */
243 u32 sw_id; /* Software ID */
244 void *buf; /* Pointer to software buffer */
245 u32 *swlen; /* Length of software buffer */
246 u32 *maxfrag; /* Number of fragments */
247 u32 *curfrag; /* Current fragment number */
248 };
250 DESCRIPTION
252 This function uploads a software fragment from the IOP identified
253 by sw->iop, sw->sw_type, sw->sw_id and optionally sw->swlen fields.
254 The UploadFlags, SwID, SwType and SwSize fields of the ExecSwUpload
255 message are filled in with the values of sw->flags, sw->sw_id,
256 sw->sw_type and *(sw->swlen).
258 The fragments _must_ be requested in order and be 8K in size. The
259 user is responsible for allocating memory pointed by sw->buf. The
260 last fragment _may_ be shorter.
262 Please note that SW transfers can take a long time.
264 RETURNS
266 This function returns 0 if no errors occur. If an error occurs, -1
267 is returned and errno is set appropriatly:
269 EFAULT Invalid user space pointer was passed
270 ENXIO Invalid IOP number
271 ETIMEDOUT Timeout waiting for reply message
272 ENOMEM Kernel memory allocation error
274 X. Removing Software
276 SYNOPSIS
278 ioctl(fd, I2OSWDEL, struct i2o_sw_xfer *sw);
280 struct i2o_sw_xfer
281 {
282 u32 iop; /* IOP unit number */
283 u8 flags; /* RemoveFlags */
284 u8 sw_type; /* Software type */
285 u32 sw_id; /* Software ID */
286 void *buf; /* Unused */
287 u32 *swlen; /* Length of the software data */
288 u32 *maxfrag; /* Unused */
289 u32 *curfrag; /* Unused */
290 };
292 DESCRIPTION
294 This function removes software from the IOP identified by sw->iop.
295 The RemoveFlags, SwID, SwType and SwSize fields of the ExecSwRemove message
296 are filled in with the values of sw->flags, sw->sw_id, sw->sw_type and
297 *(sw->swlen). Give zero in *(sw->len) if the value is unknown. IOP uses
298 *(sw->swlen) value to verify correct identication of the module to remove.
299 The actual size of the module is written into *(sw->swlen).
301 RETURNS
303 This function returns 0 if no errors occur. If an error occurs, -1
304 is returned and errno is set appropriatly:
306 EFAULT Invalid user space pointer was passed
307 ENXIO Invalid IOP number
308 ETIMEDOUT Timeout waiting for reply message
309 ENOMEM Kernel memory allocation error
311 X. Validating Configuration
313 SYNOPSIS
315 ioctl(fd, I2OVALIDATE, int *iop);
316 u32 iop;
318 DESCRIPTION
320 This function posts an ExecConfigValidate message to the controller
321 identified by iop. This message indicates that the current
322 configuration is accepted. The iop changes the status of suspect drivers
323 to valid and may delete old drivers from its store.
325 RETURNS
327 This function returns 0 if no erro occur. If an error occurs, -1 is
328 returned and errno is set appropriatly:
330 ETIMEDOUT Timeout waiting for reply message
331 ENXIO Invalid IOP number
333 XI. Configuration Dialog
335 SYNOPSIS
337 ioctl(fd, I2OHTML, struct i2o_html *htquery);
338 struct i2o_html
339 {
340 u32 iop; /* IOP unit number */
341 u32 tid; /* Target device ID */
342 u32 page; /* HTML page */
343 void *resbuf; /* Buffer for reply HTML page */
344 u32 *reslen; /* Length in bytes of reply buffer */
345 void *qbuf; /* Pointer to HTTP query string */
346 u32 qlen; /* Length in bytes of query string buffer */
347 };
349 DESCRIPTION
351 This function posts an UtilConfigDialog message to the device identified
352 by htquery->iop and htquery->tid. The requested HTML page number is
353 provided by the htquery->page field, and the resultant data is stored
354 in the buffer pointed to by htquery->resbuf. If there is an HTTP query
355 string that is to be sent to the device, it should be sent in the buffer
356 pointed to by htquery->qbuf. If there is no query string, this field
357 should be set to NULL. The actual size of the reply received is written
358 into *(htquery->reslen).
360 RETURNS
362 This function returns 0 if no error occur. If an error occurs, -1
363 is returned and errno is set appropriatly:
365 EFAULT Invalid user space pointer was passed
366 ENXIO Invalid IOP number
367 ENOBUFS Buffer not large enough. If this occurs, the required
368 buffer length is written into *(ops->reslen)
369 ETIMEDOUT Timeout waiting for reply message
370 ENOMEM Kernel memory allocation error
372 XII. Events
374 In the process of determining this. Current idea is to have use
375 the select() interface to allow user apps to periodically poll
376 the /dev/i2o/ctl device for events. When select() notifies the user
377 that an event is available, the user would call read() to retrieve
378 a list of all the events that are pending for the specific device.
380 =============================================================================
381 Revision History
382 =============================================================================
384 Rev 0.1 - 04/01/99
385 - Initial revision
387 Rev 0.2 - 04/06/99
388 - Changed return values to match UNIX ioctl() standard. Only return values
389 are 0 and -1. All errors are reported through errno.
390 - Added summary of proposed possible event interfaces
392 Rev 0.3 - 04/20/99
393 - Changed all ioctls() to use pointers to user data instead of actual data
394 - Updated error values to match the code