annotate Documentation/ftape.txt @ 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
rev   line source
ian@0 1 Intro
ian@0 2 =====
ian@0 3
ian@0 4 This file describes some issues involved when using the "ftape"
ian@0 5 floppy tape device driver that comes with the Linux kernel.
ian@0 6
ian@0 7 ftape has a home page at
ian@0 8
ian@0 9 http://ftape.dot-heine.de/
ian@0 10
ian@0 11 which contains further information about ftape. Please cross check
ian@0 12 this WWW address against the address given (if any) in the MAINTAINERS
ian@0 13 file located in the top level directory of the Linux kernel source
ian@0 14 tree.
ian@0 15
ian@0 16 NOTE: This is an unmaintained set of drivers, and it is not guaranteed to work.
ian@0 17 If you are interested in taking over maintenance, contact Claus-Justus Heine
ian@0 18 <ch@dot-heine.de>, the former maintainer.
ian@0 19
ian@0 20 Contents
ian@0 21 ========
ian@0 22
ian@0 23 A minus 1: Ftape documentation
ian@0 24
ian@0 25 A. Changes
ian@0 26 1. Goal
ian@0 27 2. I/O Block Size
ian@0 28 3. Write Access when not at EOD (End Of Data) or BOT (Begin Of Tape)
ian@0 29 4. Formatting
ian@0 30 5. Interchanging cartridges with other operating systems
ian@0 31
ian@0 32 B. Debugging Output
ian@0 33 1. Introduction
ian@0 34 2. Tuning the debugging output
ian@0 35
ian@0 36 C. Boot and load time configuration
ian@0 37 1. Setting boot time parameters
ian@0 38 2. Module load time parameters
ian@0 39 3. Ftape boot- and load time options
ian@0 40 4. Example kernel parameter setting
ian@0 41 5. Example module parameter setting
ian@0 42
ian@0 43 D. Support and contacts
ian@0 44
ian@0 45 *******************************************************************************
ian@0 46
ian@0 47 A minus 1. Ftape documentation
ian@0 48 ==============================
ian@0 49
ian@0 50 Unluckily, the ftape-HOWTO is out of date. This really needs to be
ian@0 51 changed. Up to date documentation as well as recent development
ian@0 52 versions of ftape and useful links to related topics can be found at
ian@0 53 the ftape home page at
ian@0 54
ian@0 55 http://ftape.dot-heine.de/
ian@0 56
ian@0 57 *******************************************************************************
ian@0 58
ian@0 59 A. Changes
ian@0 60 ==========
ian@0 61
ian@0 62 1. Goal
ian@0 63 ~~~~
ian@0 64 The goal of all that incompatibilities was to give ftape an interface
ian@0 65 that resembles the interface provided by SCSI tape drives as close
ian@0 66 as possible. Thus any Unix backup program that is known to work
ian@0 67 with SCSI tape drives should also work.
ian@0 68
ian@0 69 The concept of a fixed block size for read/write transfers is
ian@0 70 rather unrelated to this SCSI tape compatibility at the file system
ian@0 71 interface level. It developed out of a feature of zftape, a
ian@0 72 block wise user transparent on-the-fly compression. That compression
ian@0 73 support will not be dropped in future releases for compatibility
ian@0 74 reasons with previous releases of zftape.
ian@0 75
ian@0 76 2. I/O Block Size
ian@0 77 ~~~~~~~~~~~~~~
ian@0 78 The block size defaults to 10k which is the default block size of
ian@0 79 GNU tar.
ian@0 80
ian@0 81 The block size can be tuned either during kernel configuration or
ian@0 82 at runtime with the MTIOCTOP ioctl using the MTSETBLK operation
ian@0 83 (i.e. do "mt -f /dev/qft0" setblk #BLKSZ). A block size of 0
ian@0 84 switches to variable block size mode i.e. "mt setblk 0" switches
ian@0 85 off the block size restriction. However, this disables zftape's
ian@0 86 built in on-the-fly compression which doesn't work with variable
ian@0 87 block size mode.
ian@0 88
ian@0 89 The BLKSZ parameter must be given as a byte count and must be a
ian@0 90 multiple of 32k or 0, i.e. use "mt setblk 32768" to switch to a
ian@0 91 block size of 32k.
ian@0 92
ian@0 93 The typical symptom of a block size mismatch is an "invalid
ian@0 94 argument" error message.
ian@0 95
ian@0 96 3. Write Access when not at EOD (End Of Data) or BOT (Begin Of Tape)
ian@0 97 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
ian@0 98 zftape (the file system interface of ftape-3.x) denies write access
ian@0 99 to the tape cartridge when it isn't positioned either at BOT or
ian@0 100 EOD.
ian@0 101
ian@0 102 4. Formatting
ian@0 103 ~~~~~~~~~~
ian@0 104 ftape DOES support formatting of floppy tape cartridges. You need the
ian@0 105 `ftformat' program that is shipped with the modules version of ftape.
ian@0 106 Please get the latest version of ftape from
ian@0 107
ian@0 108 ftp://sunsite.unc.edu/pub/Linux/kernel/tapes
ian@0 109
ian@0 110 or from the ftape home page at
ian@0 111
ian@0 112 http://ftape.dot-heine.de/
ian@0 113
ian@0 114 `ftformat' is contained in the `./contrib/' subdirectory of that
ian@0 115 separate ftape package.
ian@0 116
ian@0 117 5. Interchanging cartridges with other operating systems
ian@0 118 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
ian@0 119
ian@0 120 The internal emulation of Unix tape device file marks has changed
ian@0 121 completely. ftape now uses the volume table segment as specified
ian@0 122 by the QIC-40/80/3010/3020/113 standards to emulate file marks. As
ian@0 123 a consequence there is limited support to interchange cartridges
ian@0 124 with other operating systems.
ian@0 125
ian@0 126 To be more precise: ftape will detect volumes written by other OS's
ian@0 127 programs and other OS's programs will detect volumes written by
ian@0 128 ftape.
ian@0 129
ian@0 130 However, it isn't possible to extract the data dumped to the tape
ian@0 131 by some MSDOS program with ftape. This exceeds the scope of a
ian@0 132 kernel device driver. If you need such functionality, then go ahead
ian@0 133 and write a user space utility that is able to do that. ftape already
ian@0 134 provides all kernel level support necessary to do that.
ian@0 135
ian@0 136 *******************************************************************************
ian@0 137
ian@0 138 B. Debugging Output
ian@0 139 ================
ian@0 140
ian@0 141 1. Introduction
ian@0 142 ~~~~~~~~~~~~
ian@0 143 The ftape driver can be very noisy in that is can print lots of
ian@0 144 debugging messages to the kernel log files and the system console.
ian@0 145 While this is useful for debugging it might be annoying during
ian@0 146 normal use and enlarges the size of the driver by several kilobytes.
ian@0 147
ian@0 148 To reduce the size of the driver you can trim the maximal amount of
ian@0 149 debugging information available during kernel configuration. Please
ian@0 150 refer to the kernel configuration script and its on-line help
ian@0 151 functionality.
ian@0 152
ian@0 153 The amount of debugging output maps to the "tracing" boot time
ian@0 154 option and the "ft_tracing" modules option as follows:
ian@0 155
ian@0 156 0 bugs
ian@0 157 1 + errors (with call-stack dump)
ian@0 158 2 + warnings
ian@0 159 3 + information
ian@0 160 4 + more information
ian@0 161 5 + program flow
ian@0 162 6 + fdc/dma info
ian@0 163 7 + data flow
ian@0 164 8 + everything else
ian@0 165
ian@0 166 2. Tuning the debugging output
ian@0 167 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
ian@0 168 To reduce the amount of debugging output printed to the system
ian@0 169 console you can
ian@0 170
ian@0 171 i) trim the debugging output at run-time with
ian@0 172
ian@0 173 mt -f /dev/nqft0 setdensity #DBGLVL
ian@0 174
ian@0 175 where "#DBGLVL" is a number between 0 and 9
ian@0 176
ian@0 177 ii) trim the debugging output at module load time with
ian@0 178
ian@0 179 modprobe ftape ft_tracing=#DBGLVL
ian@0 180
ian@0 181 Of course, this applies only if you have configured ftape to be
ian@0 182 compiled as a module.
ian@0 183
ian@0 184 iii) trim the debugging output during system boot time. Add the
ian@0 185 following to the kernel command line:
ian@0 186
ian@0 187 ftape=#DBGLVL,tracing
ian@0 188
ian@0 189 Please refer also to the next section if you don't know how to
ian@0 190 set boot time parameters.
ian@0 191
ian@0 192 *******************************************************************************
ian@0 193
ian@0 194 C. Boot and load time configuration
ian@0 195 ================================
ian@0 196
ian@0 197 1. Setting boot time parameters
ian@0 198 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
ian@0 199 Assuming that you use lilo, the LI)nux LO)ader, boot time kernel
ian@0 200 parameters can be set by adding a line
ian@0 201
ian@0 202 append some_kernel_boot_time_parameter
ian@0 203
ian@0 204 to `/etc/lilo.conf' or at real boot time by typing in the options
ian@0 205 at the prompt provided by LILO. I can't give you advice on how to
ian@0 206 specify those parameters with other loaders as I don't use them.
ian@0 207
ian@0 208 For ftape, each "some_kernel_boot_time_parameter" looks like
ian@0 209 "ftape=value,option". As an example, the debugging output can be
ian@0 210 increased with
ian@0 211
ian@0 212 ftape=4,tracing
ian@0 213
ian@0 214 NOTE: the value precedes the option name.
ian@0 215
ian@0 216 2. Module load time parameters
ian@0 217 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
ian@0 218 Module parameters can be specified either directly when invoking
ian@0 219 the program 'modprobe' at the shell prompt:
ian@0 220
ian@0 221 modprobe ftape ft_tracing=4
ian@0 222
ian@0 223 or by editing the file `/etc/modprobe.conf' in which case they take
ian@0 224 effect each time when the module is loaded with `modprobe' (please
ian@0 225 refer to the respective manual pages). Thus, you should add a line
ian@0 226
ian@0 227 options ftape ft_tracing=4
ian@0 228
ian@0 229 to `/etc/modprobe.conf` if you intend to increase the debugging
ian@0 230 output of the driver.
ian@0 231
ian@0 232
ian@0 233 3. Ftape boot- and load time options
ian@0 234 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
ian@0 235
ian@0 236 i. Controlling the amount of debugging output
ian@0 237 DBGLVL has to be replaced by a number between 0 and 8.
ian@0 238
ian@0 239 module | kernel command line
ian@0 240 -----------------------|----------------------
ian@0 241 ft_tracing=DBGLVL | ftape=DBGLVL,tracing
ian@0 242
ian@0 243 ii. Hardware setup
ian@0 244 BASE is the base address of your floppy disk controller,
ian@0 245 IRQ and DMA give its interrupt and DMA channel, respectively.
ian@0 246 BOOL is an integer, "0" means "no"; any other value means
ian@0 247 "yes". You don't need to specify anything if connecting your tape
ian@0 248 drive to the standard floppy disk controller. All of these
ian@0 249 values have reasonable defaults. The defaults can be modified
ian@0 250 during kernel configuration, i.e. while running "make config",
ian@0 251 "make menuconfig" or "make xconfig" in the top level directory
ian@0 252 of the Linux kernel source tree. Please refer also to the on
ian@0 253 line documentation provided during that kernel configuration
ian@0 254 process.
ian@0 255
ian@0 256 ft_probe_fc10 is set to a non-zero value if you wish for ftape to
ian@0 257 probe for a Colorado FC-10 or FC-20 controller.
ian@0 258
ian@0 259 ft_mach2 is set to a non-zero value if you wish for ftape to probe
ian@0 260 for a Mountain MACH-2 controller.
ian@0 261
ian@0 262 module | kernel command line
ian@0 263 -----------------------|----------------------
ian@0 264 ft_fdc_base=BASE | ftape=BASE,ioport
ian@0 265 ft_fdc_irq=IRQ | ftape=IRQ,irq
ian@0 266 ft_fdc_dma=DMA | ftape=DMA,dma
ian@0 267 ft_probe_fc10=BOOL | ftape=BOOL,fc10
ian@0 268 ft_mach2=BOOL | ftape=BOOL,mach2
ian@0 269 ft_fdc_threshold=THR | ftape=THR,threshold
ian@0 270 ft_fdc_rate_limit=RATE | ftape=RATE,datarate
ian@0 271
ian@0 272 4. Example kernel parameter setting
ian@0 273 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
ian@0 274 To configure ftape to probe for a Colorado FC-10/FC-20 controller
ian@0 275 and to increase the amount of debugging output a little bit, add
ian@0 276 the following line to `/etc/lilo.conf':
ian@0 277
ian@0 278 append ftape=1,fc10 ftape=4,tracing
ian@0 279
ian@0 280 5. Example module parameter setting
ian@0 281 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
ian@0 282 To do the same, but with ftape compiled as a loadable kernel
ian@0 283 module, add the following line to `/etc/modprobe.conf':
ian@0 284
ian@0 285 options ftape ft_probe_fc10=1 ft_tracing=4
ian@0 286
ian@0 287 *******************************************************************************
ian@0 288
ian@0 289 D. Support and contacts
ian@0 290 ====================
ian@0 291
ian@0 292 Ftape is distributed under the GNU General Public License. There is
ian@0 293 absolutely no warranty for this software. However, you can reach
ian@0 294 the current maintainer of the ftape package under the email address
ian@0 295 given in the MAINTAINERS file which is located in the top level
ian@0 296 directory of the Linux kernel source tree. There you'll find also
ian@0 297 the relevant mailing list to use as a discussion forum and the web
ian@0 298 page to query for the most recent documentation, related work and
ian@0 299 development versions of ftape.
ian@0 300
ian@0 301 Changelog:
ian@0 302 ==========
ian@0 303
ian@0 304 ~1996: Original Document
ian@0 305
ian@0 306 10-24-2004: General cleanup and updating, noting additional module options.
ian@0 307 James Nelson <james4765@gmail.com>