annotate Documentation/specialix.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
ian@0 2 specialix.txt -- specialix IO8+ multiport serial driver readme.
ian@0 3
ian@0 4
ian@0 5
ian@0 6 Copyright (C) 1997 Roger Wolff (R.E.Wolff@BitWizard.nl)
ian@0 7
ian@0 8 Specialix pays for the development and support of this driver.
ian@0 9 Please DO contact io8-linux@specialix.co.uk if you require
ian@0 10 support.
ian@0 11
ian@0 12 This driver was developed in the BitWizard linux device
ian@0 13 driver service. If you require a linux device driver for your
ian@0 14 product, please contact devices@BitWizard.nl for a quote.
ian@0 15
ian@0 16 This code is firmly based on the riscom/8 serial driver,
ian@0 17 written by Dmitry Gorodchanin. The specialix IO8+ card
ian@0 18 programming information was obtained from the CL-CD1865 Data
ian@0 19 Book, and Specialix document number 6200059: IO8+ Hardware
ian@0 20 Functional Specification, augmented by document number 6200088:
ian@0 21 Merak Hardware Functional Specification. (IO8+/PCI is also
ian@0 22 called Merak)
ian@0 23
ian@0 24
ian@0 25 This program is free software; you can redistribute it and/or
ian@0 26 modify it under the terms of the GNU General Public License as
ian@0 27 published by the Free Software Foundation; either version 2 of
ian@0 28 the License, or (at your option) any later version.
ian@0 29
ian@0 30 This program is distributed in the hope that it will be
ian@0 31 useful, but WITHOUT ANY WARRANTY; without even the implied
ian@0 33 PURPOSE. See the GNU General Public License for more details.
ian@0 34
ian@0 35 You should have received a copy of the GNU General Public
ian@0 36 License along with this program; if not, write to the Free
ian@0 37 Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
ian@0 38 USA.
ian@0 39
ian@0 40
ian@0 41 Intro
ian@0 42 =====
ian@0 43
ian@0 44
ian@0 45 This file contains some random information, that I like to have online
ian@0 46 instead of in a manual that can get lost. Ever misplace your Linux
ian@0 47 kernel sources? And the manual of one of the boards in your computer?
ian@0 48
ian@0 49
ian@0 50 Addresses and interrupts
ian@0 51 ========================
ian@0 52
ian@0 53 Address dip switch settings:
ian@0 54 The dip switch sets bits 2-9 of the IO address.
ian@0 55
ian@0 56 9 8 7 6 5 4 3 2
ian@0 57 +-----------------+
ian@0 58 0 | X X X X X X X |
ian@0 59 | | = IoBase = 0x100
ian@0 60 1 | X |
ian@0 61 +-----------------+ ------ RS232 connectors ---->
ian@0 62
ian@0 63 | | |
ian@0 64 edge connector
ian@0 65 | | |
ian@0 66 V V V
ian@0 67
ian@0 68 Base address 0x100 caused a conflict in one of my computers once. I
ian@0 69 haven't the foggiest why. My Specialix card is now at 0x180. My
ian@0 70 other computer runs just fine with the Specialix card at 0x100....
ian@0 71 The card occupies 4 addresses, but actually only two are really used.
ian@0 72
ian@0 73 The PCI version doesn't have any dip switches. The BIOS assigns
ian@0 74 an IO address.
ian@0 75
ian@0 76 The driver now still autoprobes at 0x100, 0x180, 0x250 and 0x260. If
ian@0 77 that causes trouble for you, please report that. I'll remove
ian@0 78 autoprobing then.
ian@0 79
ian@0 80 The driver will tell the card what IRQ to use, so you don't have to
ian@0 81 change any jumpers to change the IRQ. Just use a command line
ian@0 82 argument (irq=xx) to the insmod program to set the interrupt.
ian@0 83
ian@0 84 The BIOS assigns the IRQ on the PCI version. You have no say in what
ian@0 85 IRQ to use in that case.
ian@0 86
ian@0 87 If your specialix cards are not at the default locations, you can use
ian@0 88 the kernel command line argument "specialix=io0,irq0,io1,irq1...".
ian@0 89 Here "io0" is the io address for the first card, and "irq0" is the
ian@0 90 irq line that the first card should use. And so on.
ian@0 91
ian@0 92 Examples.
ian@0 93
ian@0 94 You use the driver as a module and have three cards at 0x100, 0x250
ian@0 95 and 0x180. And some way or another you want them detected in that
ian@0 96 order. Moreover irq 12 is taken (e.g. by your PS/2 mouse).
ian@0 97
ian@0 98 insmod specialix.o iobase=0x100,0x250,0x180 irq=9,11,15
ian@0 99
ian@0 100 The same three cards, but now in the kernel would require you to
ian@0 101 add
ian@0 102
ian@0 103 specialix=0x100,9,0x250,11,0x180,15
ian@0 104
ian@0 105 to the command line. This would become
ian@0 106
ian@0 107 append="specialix=0x100,9,0x250,11,0x180,15"
ian@0 108
ian@0 109 in your /etc/lilo.conf file if you use lilo.
ian@0 110
ian@0 111 The Specialix driver is slightly odd: It allows you to have the second
ian@0 112 or third card detected without having a first card. This has
ian@0 113 advantages and disadvantages. A slot that isn't filled by an ISA card,
ian@0 114 might be filled if a PCI card is detected. Thus if you have an ISA
ian@0 115 card at 0x250 and a PCI card, you would get:
ian@0 116
ian@0 117 sx0: specialix IO8+ Board at 0x100 not found.
ian@0 118 sx1: specialix IO8+ Board at 0x180 not found.
ian@0 119 sx2: specialix IO8+ board detected at 0x250, IRQ 12, CD1865 Rev. B.
ian@0 120 sx3: specialix IO8+ Board at 0x260 not found.
ian@0 121 sx0: specialix IO8+ board detected at 0xd800, IRQ 9, CD1865 Rev. B.
ian@0 122
ian@0 123 This would happen if you don't give any probe hints to the driver.
ian@0 124 If you would specify:
ian@0 125
ian@0 126 specialix=0x250,11
ian@0 127
ian@0 128 you'd get the following messages:
ian@0 129
ian@0 130 sx0: specialix IO8+ board detected at 0x250, IRQ 11, CD1865 Rev. B.
ian@0 131 sx1: specialix IO8+ board detected at 0xd800, IRQ 9, CD1865 Rev. B.
ian@0 132
ian@0 133 ISA probing is aborted after the IO address you gave is exhausted, and
ian@0 134 the PCI card is now detected as the second card. The ISA card is now
ian@0 135 also forced to IRQ11....
ian@0 136
ian@0 137
ian@0 138 Baud rates
ian@0 139 ==========
ian@0 140
ian@0 141 The rev 1.2 and below boards use a CL-CD1864. These chips can only
ian@0 142 do 64kbit. The rev 1.3 and newer boards use a CL-CD1865. These chips
ian@0 143 are officially capable of 115k2.
ian@0 144
ian@0 145 The Specialix card uses a 25MHz crystal (in times two mode, which in
ian@0 146 fact is a divided by two mode). This is not enough to reach the rated
ian@0 147 115k2 on all ports at the same time. With this clock rate you can only
ian@0 148 do 37% of this rate. This means that at 115k2 on all ports you are
ian@0 149 going to lose characters (The chip cannot handle that many incoming
ian@0 150 bits at this clock rate.) (Yes, you read that correctly: there is a
ian@0 151 limit to the number of -=bits=- per second that the chip can handle.)
ian@0 152
ian@0 153 If you near the "limit" you will first start to see a graceful
ian@0 154 degradation in that the chip cannot keep the transmitter busy at all
ian@0 155 times. However with a central clock this slow, you can also get it to
ian@0 156 miss incoming characters. The driver will print a warning message when
ian@0 157 you are outside the official specs. The messages usually show up in
ian@0 158 the file /var/log/messages .
ian@0 159
ian@0 160 The specialix card cannot reliably do 115k2. If you use it, you have
ian@0 161 to do "extensive testing" (*) to verify if it actually works.
ian@0 162
ian@0 163 When "mgetty" communicates with my modem at 115k2 it reports:
ian@0 164 got: +++[0d]ATQ0V1H0[0d][0d][8a]O[cb][0d][8a]
ian@0 165 ^^^^ ^^^^ ^^^^
ian@0 166
ian@0 167 The three characters that have the "^^^" under them have suffered a
ian@0 168 bit error in the highest bit. In conclusion: I've tested it, and found
ian@0 169 that it simply DOESN'T work for me. I also suspect that this is also
ian@0 170 caused by the baud rate being just a little bit out of tune.
ian@0 171
ian@0 172 I upgraded the crystal to 66Mhz on one of my Specialix cards. Works
ian@0 173 great! Contact me for details. (Voids warranty, requires a steady hand
ian@0 174 and more such restrictions....)
ian@0 175
ian@0 176
ian@0 177 (*) Cirrus logic CD1864 databook, page 40.
ian@0 178
ian@0 179
ian@0 180 Cables for the Specialix IO8+
ian@0 181 =============================
ian@0 182
ian@0 183 The pinout of the connectors on the IO8+ is:
ian@0 184
ian@0 185 pin short direction long name
ian@0 186 name
ian@0 187 Pin 1 DCD input Data Carrier Detect
ian@0 188 Pin 2 RXD input Receive
ian@0 189 Pin 3 DTR/RTS output Data Terminal Ready/Ready To Send
ian@0 190 Pin 4 GND - Ground
ian@0 191 Pin 5 TXD output Transmit
ian@0 192 Pin 6 CTS input Clear To Send
ian@0 193
ian@0 194
ian@0 195 -- 6 5 4 3 2 1 --
ian@0 196 | |
ian@0 197 | |
ian@0 198 | |
ian@0 199 | |
ian@0 200 +----- -----+
ian@0 201 |__________|
ian@0 202 clip
ian@0 203
ian@0 204 Front view of an RJ12 connector. Cable moves "into" the paper.
ian@0 205 (the plug is ready to plug into your mouth this way...)
ian@0 206
ian@0 207
ian@0 208 NULL cable. I don't know who is going to use these except for
ian@0 209 testing purposes, but I tested the cards with this cable. (It
ian@0 210 took quite a while to figure out, so I'm not going to delete
ian@0 211 it. So there! :-)
ian@0 212
ian@0 213
ian@0 214 This end goes This end needs
ian@0 215 straight into the some twists in
ian@0 216 RJ12 plug. the wiring.
ian@0 217 IO8+ RJ12 IO8+ RJ12
ian@0 218 1 DCD white -
ian@0 219 - - 1 DCD
ian@0 220 2 RXD black 5 TXD
ian@0 221 3 DTR/RTS red 6 CTS
ian@0 222 4 GND green 4 GND
ian@0 223 5 TXD yellow 2 RXD
ian@0 224 6 CTS blue 3 DTR/RTS
ian@0 225
ian@0 226
ian@0 227 Same NULL cable, but now sorted on the second column.
ian@0 228
ian@0 229 1 DCD white -
ian@0 230 - - 1 DCD
ian@0 231 5 TXD yellow 2 RXD
ian@0 232 6 CTS blue 3 DTR/RTS
ian@0 233 4 GND green 4 GND
ian@0 234 2 RXD black 5 TXD
ian@0 235 3 DTR/RTS red 6 CTS
ian@0 236
ian@0 237
ian@0 238
ian@0 239 This is a modem cable usable for hardware handshaking:
ian@0 240 RJ12 DB25 DB9
ian@0 241 1 DCD white 8 DCD 1 DCD
ian@0 242 2 RXD black 3 RXD 2 RXD
ian@0 243 3 DTR/RTS red 4 RTS 7 RTS
ian@0 244 4 GND green 7 GND 5 GND
ian@0 245 5 TXD yellow 2 TXD 3 TXD
ian@0 246 6 CTS blue 5 CTS 8 CTS
ian@0 247 +---- 6 DSR 6 DSR
ian@0 248 +---- 20 DTR 4 DTR
ian@0 249
ian@0 250 This is a modem cable usable for software handshaking:
ian@0 251 It allows you to reset the modem using the DTR ioctls.
ian@0 252 I (REW) have never tested this, "but xxxxxxxxxxxxx
ian@0 253 says that it works." If you test this, please
ian@0 254 tell me and I'll fill in your name on the xxx's.
ian@0 255
ian@0 256 RJ12 DB25 DB9
ian@0 257 1 DCD white 8 DCD 1 DCD
ian@0 258 2 RXD black 3 RXD 2 RXD
ian@0 259 3 DTR/RTS red 20 DTR 4 DTR
ian@0 260 4 GND green 7 GND 5 GND
ian@0 261 5 TXD yellow 2 TXD 3 TXD
ian@0 262 6 CTS blue 5 CTS 8 CTS
ian@0 263 +---- 6 DSR 6 DSR
ian@0 264 +---- 4 RTS 7 RTS
ian@0 265
ian@0 266 I bought a 6 wire flat cable. It was colored as indicated.
ian@0 267 Check that yours is the same before you trust me on this.
ian@0 268
ian@0 269
ian@0 270 Hardware handshaking issues.
ian@0 271 ============================
ian@0 272
ian@0 273 The driver can be compiled in two different ways. The default
ian@0 274 ("Specialix DTR/RTS pin is RTS" is off) the pin behaves as DTR when
ian@0 275 hardware handshaking is off. It behaves as the RTS hardware
ian@0 276 handshaking signal when hardware handshaking is selected.
ian@0 277
ian@0 278 When you use this, you have to use the appropriate cable. The
ian@0 279 cable will either be compatible with hardware handshaking or with
ian@0 280 software handshaking. So switching on the fly is not really an
ian@0 281 option.
ian@0 282
ian@0 283 I actually prefer to use the "Specialix DTR/RTS pin is RTS" option.
ian@0 284 This makes the DTR/RTS pin always an RTS pin, and ioctls to
ian@0 285 change DTR are always ignored. I have a cable that is configured
ian@0 286 for this.
ian@0 287
ian@0 288
ian@0 289 Ports and devices
ian@0 290 =================
ian@0 291
ian@0 292 Port 0 is the one furthest from the card-edge connector.
ian@0 293
ian@0 294 Devices:
ian@0 295
ian@0 296 You should make the devices as follows:
ian@0 297
ian@0 298 bash
ian@0 299 cd /dev
ian@0 300 for i in 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 \
ian@0 301 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
ian@0 302 do
ian@0 303 echo -n "$i "
ian@0 304 mknod /dev/ttyW$i c 75 $i
ian@0 305 mknod /dev/cuw$i c 76 $i
ian@0 306 done
ian@0 307 echo ""
ian@0 308
ian@0 309 If your system doesn't come with these devices preinstalled, bug your
ian@0 310 linux-vendor about this. They have had ample time to get this
ian@0 311 implemented by now.
ian@0 312
ian@0 313 You cannot have more than 4 boards in one computer. The card only
ian@0 314 supports 4 different interrupts. If you really want this, contact me
ian@0 315 about this and I'll give you a few tips (requires soldering iron)....
ian@0 316
ian@0 317 If you have enough PCI slots, you can probably use more than 4 PCI
ian@0 318 versions of the card though....
ian@0 319
ian@0 320 The PCI version of the card cannot adhere to the mechanical part of
ian@0 321 the PCI spec because the 8 serial connectors are simply too large. If
ian@0 322 it doesn't fit in your computer, bring back the card.
ian@0 323
ian@0 324
ian@0 325 ------------------------------------------------------------------------
ian@0 326
ian@0 327
ian@0 328 Fixed bugs and restrictions:
ian@0 329 - During initialization, interrupts are blindly turned on.
ian@0 330 Having a shadow variable would cause an extra memory
ian@0 331 access on every IO instruction.
ian@0 332 - The interrupt (on the card) should be disabled when we
ian@0 333 don't allocate the Linux end of the interrupt. This allows
ian@0 334 a different driver/card to use it while all ports are not in
ian@0 335 use..... (a la standard serial port)
ian@0 336 == An extra _off variant of the sx_in and sx_out macros are
ian@0 337 now available. They don't set the interrupt enable bit.
ian@0 338 These are used during initialization. Normal operation uses
ian@0 339 the old variant which enables the interrupt line.
ian@0 340 - RTS/DTR issue needs to be implemented according to
ian@0 341 specialix' spec.
ian@0 342 I kind of like the "determinism" of the current
ian@0 343 implementation. Compile time flag?
ian@0 344 == Ok. Compile time flag! Default is how Specialix likes it.
ian@0 345 == Now a config time flag! Gets saved in your config file. Neat!
ian@0 346 - Can you set the IO address from the lilo command line?
ian@0 347 If you need this, bug me about it, I'll make it.
ian@0 348 == Hah! No bugging needed. Fixed! :-)
ian@0 349 - Cirrus logic hasn't gotten back to me yet why the CD1865 can
ian@0 350 and the CD1864 can't do 115k2. I suspect that this is
ian@0 351 because the CD1864 is not rated for 33MHz operation.
ian@0 352 Therefore the CD1864 versions of the card can't do 115k2 on
ian@0 353 all ports just like the CD1865 versions. The driver does
ian@0 354 not block 115k2 on CD1864 cards.
ian@0 355 == I called the Cirrus Logic representative here in Holland.
ian@0 356 The CD1864 databook is identical to the CD1865 databook,
ian@0 357 except for an extra warning at the end. Similar Bit errors
ian@0 358 have been observed in testing at 115k2 on both an 1865 and
ian@0 359 a 1864 chip. I see no reason why I would prohibit 115k2 on
ian@0 360 1864 chips and not do it on 1865 chips. Actually there is
ian@0 361 reason to prohibit it on BOTH chips. I print a warning.
ian@0 362 If you use 115k2, you're on your own.
ian@0 363 - A spiky CD may send spurious HUPs. Also in CLOCAL???
ian@0 364 -- A fix for this turned out to be counter productive.
ian@0 365 Different fix? Current behaviour is acceptable?
ian@0 366 -- Maybe the current implementation is correct. If anybody
ian@0 367 gets bitten by this, please report, and it will get fixed.
ian@0 368
ian@0 369 -- Testing revealed that when in CLOCAL, the problem doesn't
ian@0 370 occur. As warned for in the CD1865 manual, the chip may
ian@0 371 send modem intr's on a spike. We could filter those out,
ian@0 372 but that would be a cludge anyway (You'd still risk getting
ian@0 373 a spurious HUP when two spikes occur.).....
ian@0 374
ian@0 375
ian@0 376
ian@0 377 Bugs & restrictions:
ian@0 378 - This is a difficult card to autoprobe.
ian@0 379 You have to WRITE to the address register to even
ian@0 380 read-probe a CD186x register. Disable autodetection?
ian@0 381 -- Specialix: any suggestions?
ian@0 382 - Arbitrary baud rates are not implemented yet.
ian@0 383 If you need this, bug me about it.
ian@0 384
ian@0 385