view Documentation/input/joystick.txt @ 452:c7ed6fe5dca0

kexec: dont initialise regions in reserve_memory()

There is no need to initialise efi_memmap_res and boot_param_res in
reserve_memory() for the initial xen domain as it is done in
machine_kexec_setup_resources() using values from the kexec hypercall.

Signed-off-by: Simon Horman <horms@verge.net.au>
author Keir Fraser <keir.fraser@citrix.com>
date Thu Feb 28 10:55:18 2008 +0000 (2008-02-28)
parents 831230e53067
line source
1 Linux Joystick driver v2.0.0
2 (c) 1996-2000 Vojtech Pavlik <vojtech@ucw.cz>
3 Sponsored by SuSE
4 $Id: joystick.txt,v 1.12 2002/03/03 12:13:07 jdeneux Exp $
5 ----------------------------------------------------------------------------
7 0. Disclaimer
8 ~~~~~~~~~~~~~
9 This program is free software; you can redistribute it and/or modify it
10 under the terms of the GNU General Public License as published by the Free
11 Software Foundation; either version 2 of the License, or (at your option)
12 any later version.
14 This program is distributed in the hope that it will be useful, but
15 WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
16 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
17 more details.
19 You should have received a copy of the GNU General Public License along
20 with this program; if not, write to the Free Software Foundation, Inc., 59
21 Temple Place, Suite 330, Boston, MA 02111-1307 USA
23 Should you need to contact me, the author, you can do so either by e-mail
24 - mail your message to <vojtech@ucw.cz>, or by paper mail: Vojtech Pavlik,
25 Simunkova 1594, Prague 8, 182 00 Czech Republic
27 For your convenience, the GNU General Public License version 2 is included
28 in the package: See the file COPYING.
30 1. Intro
31 ~~~~~~~~
32 The joystick driver for Linux provides support for a variety of joysticks
33 and similar devices. It is based on a larger project aiming to support all
34 input devices in Linux.
36 Should you encounter any problems while using the driver, or joysticks
37 this driver can't make complete use of, I'm very interested in hearing about
38 them. Bug reports and success stories are also welcome.
40 The input project website is at:
42 http://atrey.karlin.mff.cuni.cz/~vojtech/input/
44 There is also a mailing list for the driver at:
46 listproc@atrey.karlin.mff.cuni.cz
48 send "subscribe linux-joystick Your Name" to subscribe to it.
50 2. Usage
51 ~~~~~~~~
52 For basic usage you just choose the right options in kernel config and
53 you should be set.
55 2.1 inpututils
56 ~~~~~~~~~~~~~~
57 For testing and other purposes (for example serial devices), a set of
58 utilities is available at the abovementioned website. I suggest you download
59 and install it before going on.
61 2.2 Device nodes
62 ~~~~~~~~~~~~~~~~
63 For applications to be able to use the joysticks, in you don't use devfs,
64 you'll have to manually create these nodes in /dev:
66 cd /dev
67 rm js*
68 mkdir input
69 mknod input/js0 c 13 0
70 mknod input/js1 c 13 1
71 mknod input/js2 c 13 2
72 mknod input/js3 c 13 3
73 ln -s input/js0 js0
74 ln -s input/js1 js1
75 ln -s input/js2 js2
76 ln -s input/js3 js3
78 For testing with inpututils it's also convenient to create these:
80 mknod input/event0 c 13 64
81 mknod input/event1 c 13 65
82 mknod input/event2 c 13 66
83 mknod input/event3 c 13 67
85 2.4 Modules needed
86 ~~~~~~~~~~~~~~~~~~
87 For all joystick drivers to function, you'll need the userland interface
88 module in kernel, either loaded or compiled in:
90 modprobe joydev
92 For gameport joysticks, you'll have to load the gameport driver as well;
94 modprobe ns558
96 And for serial port joysticks, you'll need the serial input line
97 discipline module loaded and the inputattach utility started:
99 modprobe serport
100 inputattach -xxx /dev/tts/X &
102 In addition to that, you'll need the joystick driver module itself, most
103 usually you'll have an analog joystick:
105 modprobe analog
107 For automatic module loading, something like this might work - tailor to
108 your needs:
110 alias tty-ldisc-2 serport
111 alias char-major-13 input
112 above input joydev ns558 analog
113 options analog map=gamepad,none,2btn
115 2.5 Verifying that it works
116 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
117 For testing the joystick driver functionality, there is the jstest
118 program in the utilities package. You run it by typing:
120 jstest /dev/js0
122 And it should show a line with the joystick values, which update as you
123 move the stick, and press its buttons. The axes should all be zero when the
124 joystick is in the center position. They should not jitter by themselves to
125 other close values, and they also should be steady in any other position of
126 the stick. They should have the full range from -32767 to 32767. If all this
127 is met, then it's all fine, and you can play the games. :)
129 If it's not, then there might be a problem. Try to calibrate the joystick,
130 and if it still doesn't work, read the drivers section of this file, the
131 troubleshooting section, and the FAQ.
133 2.6. Calibration
134 ~~~~~~~~~~~~~~~~
135 For most joysticks you won't need any manual calibration, since the
136 joystick should be autocalibrated by the driver automagically. However, with
137 some analog joysticks, that either do not use linear resistors, or if you
138 want better precision, you can use the jscal program
140 jscal -c /dev/js0
142 included in the joystick package to set better correction coefficients than
143 what the driver would choose itself.
145 After calibrating the joystick you can verify if you like the new
146 calibration using the jstest command, and if you do, you then can save the
147 correction coefficients into a file
149 jscal -p /dev/js0 > /etc/joystick.cal
151 And add a line to your rc script executing that file
153 source /etc/joystick.cal
155 This way, after the next reboot your joystick will remain calibrated. You
156 can also add the jscal -p line to your shutdown script.
159 3. HW specific driver information
160 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
161 In this section each of the separate hardware specific drivers is described.
163 3.1 Analog joysticks
164 ~~~~~~~~~~~~~~~~~~~~
165 The analog.c uses the standard analog inputs of the gameport, and thus
166 supports all standard joysticks and gamepads. It uses a very advanced
167 routine for this, allowing for data precision that can't be found on any
168 other system.
170 It also supports extensions like additional hats and buttons compatible
171 with CH Flightstick Pro, ThrustMaster FCS or 6 and 8 button gamepads. Saitek
172 Cyborg 'digital' joysticks are also supported by this driver, because
173 they're basically souped up CHF sticks.
175 However the only types that can be autodetected are:
177 * 2-axis, 4-button joystick
178 * 3-axis, 4-button joystick
179 * 4-axis, 4-button joystick
180 * Saitek Cyborg 'digital' joysticks
182 For other joystick types (more/less axes, hats, and buttons) support
183 you'll need to specify the types either on the kernel command line or on the
184 module command line, when inserting analog into the kernel. The
185 parameters are:
187 analog.map=<type1>,<type2>,<type3>,....
189 'type' is type of the joystick from the table below, defining joysticks
190 present on gameports in the system, starting with gameport0, second 'type'
191 entry defining joystick on gameport1 and so on.
193 Type | Meaning
194 -----------------------------------
195 none | No analog joystick on that port
196 auto | Autodetect joystick
197 2btn | 2-button n-axis joystick
198 y-joy | Two 2-button 2-axis joysticks on an Y-cable
199 y-pad | Two 2-button 2-axis gamepads on an Y-cable
200 fcs | Thrustmaster FCS compatible joystick
201 chf | Joystick with a CH Flightstick compatible hat
202 fullchf | CH Flightstick compatible with two hats and 6 buttons
203 gamepad | 4/6-button n-axis gamepad
204 gamepad8 | 8-button 2-axis gamepad
206 In case your joystick doesn't fit in any of the above categories, you can
207 specify the type as a number by combining the bits in the table below. This
208 is not recommended unless you really know what are you doing. It's not
209 dangerous, but not simple either.
211 Bit | Meaning
212 --------------------------
213 0 | Axis X1
214 1 | Axis Y1
215 2 | Axis X2
216 3 | Axis Y2
217 4 | Button A
218 5 | Button B
219 6 | Button C
220 7 | Button D
221 8 | CHF Buttons X and Y
222 9 | CHF Hat 1
223 10 | CHF Hat 2
224 11 | FCS Hat
225 12 | Pad Button X
226 13 | Pad Button Y
227 14 | Pad Button U
228 15 | Pad Button V
229 16 | Saitek F1-F4 Buttons
230 17 | Saitek Digital Mode
231 19 | GamePad
232 20 | Joy2 Axis X1
233 21 | Joy2 Axis Y1
234 22 | Joy2 Axis X2
235 23 | Joy2 Axis Y2
236 24 | Joy2 Button A
237 25 | Joy2 Button B
238 26 | Joy2 Button C
239 27 | Joy2 Button D
240 31 | Joy2 GamePad
242 3.2 Microsoft SideWinder joysticks
243 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
244 Microsoft 'Digital Overdrive' protocol is supported by the sidewinder.c
245 module. All currently supported joysticks:
247 * Microsoft SideWinder 3D Pro
248 * Microsoft SideWinder Force Feedback Pro
249 * Microsoft SideWinder Force Feedback Wheel
250 * Microsoft SideWinder FreeStyle Pro
251 * Microsoft SideWinder GamePad (up to four, chained)
252 * Microsoft SideWinder Precision Pro
253 * Microsoft SideWinder Precision Pro USB
255 are autodetected, and thus no module parameters are needed.
257 There is one caveat with the 3D Pro. There are 9 buttons reported,
258 although the joystick has only 8. The 9th button is the mode switch on the
259 rear side of the joystick. However, moving it, you'll reset the joystick,
260 and make it unresponsive for about a one third of a second. Furthermore, the
261 joystick will also re-center itself, taking the position it was in during
262 this time as a new center position. Use it if you want, but think first.
264 The SideWinder Standard is not a digital joystick, and thus is supported
265 by the analog driver described above.
267 3.3 Logitech ADI devices
268 ~~~~~~~~~~~~~~~~~~~~~~~~
269 Logitech ADI protocol is supported by the adi.c module. It should support
270 any Logitech device using this protocol. This includes, but is not limited
271 to:
273 * Logitech CyberMan 2
274 * Logitech ThunderPad Digital
275 * Logitech WingMan Extreme Digital
276 * Logitech WingMan Formula
277 * Logitech WingMan Interceptor
278 * Logitech WingMan GamePad
279 * Logitech WingMan GamePad USB
280 * Logitech WingMan GamePad Extreme
281 * Logitech WingMan Extreme Digital 3D
283 ADI devices are autodetected, and the driver supports up to two (any
284 combination of) devices on a single gameport, using an Y-cable or chained
285 together.
287 Logitech WingMan Joystick, Logitech WingMan Attack, Logitech WingMan
288 Extreme and Logitech WingMan ThunderPad are not digital joysticks and are
289 handled by the analog driver described above. Logitech WingMan Warrior and
290 Logitech Magellan are supported by serial drivers described below. Logitech
291 WingMan Force and Logitech WingMan Formula Force are supported by the
292 I-Force driver described below. Logitech CyberMan is not supported yet.
294 3.4 Gravis GrIP
295 ~~~~~~~~~~~~~~~
296 Gravis GrIP protocol is supported by the grip.c module. It currently
297 supports:
299 * Gravis GamePad Pro
300 * Gravis BlackHawk Digital
301 * Gravis Xterminator
302 * Gravis Xterminator DualControl
304 All these devices are autodetected, and you can even use any combination
305 of up to two of these pads either chained together or using an Y-cable on a
306 single gameport.
308 GrIP MultiPort isn't supported yet. Gravis Stinger is a serial device and is
309 supported by the stinger driver. Other Gravis joysticks are supported by the
310 analog driver.
312 3.5 FPGaming A3D and MadCatz A3D
313 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
314 The Assassin 3D protocol created by FPGaming, is used both by FPGaming
315 themselves and is licensed to MadCatz. A3D devices are supported by the
316 a3d.c module. It currently supports:
318 * FPGaming Assassin 3D
319 * MadCatz Panther
320 * MadCatz Panther XL
322 All these devices are autodetected. Because the Assassin 3D and the Panther
323 allow connecting analog joysticks to them, you'll need to load the analog
324 driver as well to handle the attached joysticks.
326 The trackball should work with USB mousedev module as a normal mouse. See
327 the USB documentation for how to setup an USB mouse.
329 3.6 ThrustMaster DirectConnect (BSP)
330 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
331 The TM DirectConnect (BSP) protocol is supported by the tmdc.c
332 module. This includes, but is not limited to:
334 * ThrustMaster Millenium 3D Inceptor
335 * ThrustMaster 3D Rage Pad
336 * ThrustMaster Fusion Digital Game Pad
338 Devices not directly supported, but hopefully working are:
340 * ThrustMaster FragMaster
341 * ThrustMaster Attack Throttle
343 If you have one of these, contact me.
345 TMDC devices are autodetected, and thus no parameters to the module
346 are needed. Up to two TMDC devices can be connected to one gameport, using
347 an Y-cable.
349 3.7 Creative Labs Blaster
350 ~~~~~~~~~~~~~~~~~~~~~~~~~
351 The Blaster protocol is supported by the cobra.c module. It supports only
352 the:
354 * Creative Blaster GamePad Cobra
356 Up to two of these can be used on a single gameport, using an Y-cable.
358 3.8 Genius Digital joysticks
359 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
360 The Genius digitally communicating joysticks are supported by the gf2k.c
361 module. This includes:
363 * Genius Flight2000 F-23 joystick
364 * Genius Flight2000 F-31 joystick
365 * Genius G-09D gamepad
367 Other Genius digital joysticks are not supported yet, but support can be
368 added fairly easily.
370 3.9 InterAct Digital joysticks
371 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
372 The InterAct digitally communicating joysticks are supported by the
373 interact.c module. This includes:
375 * InterAct HammerHead/FX gamepad
376 * InterAct ProPad8 gamepad
378 Other InterAct digital joysticks are not supported yet, but support can be
379 added fairly easily.
381 3.10 PDPI Lightning 4 gamecards
382 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
383 PDPI Lightning 4 gamecards are supported by the lightning.c module.
384 Once the module is loaded, the analog driver can be used to handle the
385 joysticks. Digitally communicating joystick will work only on port 0, while
386 using Y-cables, you can connect up to 8 analog joysticks to a single L4
387 card, 16 in case you have two in your system.
389 3.11 Trident 4DWave / Aureal Vortex
390 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
391 Soundcards with a Trident 4DWave DX/NX or Aureal Vortex/Vortex2 chipsets
392 provide an "Enhanced Game Port" mode where the soundcard handles polling the
393 joystick. This mode is supported by the pcigame.c module. Once loaded the
394 analog driver can use the enhanced features of these gameports..
396 3.13 Crystal SoundFusion
397 ~~~~~~~~~~~~~~~~~~~~~~~~
398 Soundcards with Crystal SoundFusion chipsets provide an "Enhanced Game
399 Port", much like the 4DWave or Vortex above. This, and also the normal mode
400 for the port of the SoundFusion is supported by the cs461x.c module.
402 3.14 SoundBlaster Live!
403 ~~~~~~~~~~~~~~~~~~~~~~~~
404 The Live! has a special PCI gameport, which, although it doesn't provide
405 any "Enhanced" stuff like 4DWave and friends, is quite a bit faster than
406 it's ISA counterparts. It also requires special support, hence the
407 emu10k1-gp.c module for it instead of the normal ns558.c one.
409 3.15 SoundBlaster 64 and 128 - ES1370 and ES1371, ESS Solo1 and S3 SonicVibes
410 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
411 These PCI soundcards have specific gameports. They are handled by the
412 sound drivers themselves. Make sure you select gameport support in the
413 joystick menu and sound card support in the sound menu for your appropriate
414 card.
416 3.16 Amiga
417 ~~~~~~~~~~
418 Amiga joysticks, connected to an Amiga, are supported by the amijoy.c
419 driver. Since they can't be autodetected, the driver has a command line.
421 amijoy.map=<a>,<b>
423 a and b define the joysticks connected to the JOY0DAT and JOY1DAT ports of
424 the Amiga.
426 Value | Joystick type
427 ---------------------
428 0 | None
429 1 | 1-button digital joystick
431 No more joystick types are supported now, but that should change in the
432 future if I get an Amiga in the reach of my fingers.
434 3.17 Game console and 8-bit pads and joysticks
435 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
436 See joystick-parport.txt for more info.
438 3.18 SpaceTec/LabTec devices
439 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
440 SpaceTec serial devices communicate using the SpaceWare protocol. It is
441 supported by the spaceorb.c and spaceball.c drivers. The devices currently
442 supported by spaceorb.c are:
444 * SpaceTec SpaceBall Avenger
445 * SpaceTec SpaceOrb 360
447 Devices currently supported by spaceball.c are:
449 * SpaceTec SpaceBall 4000 FLX
451 In addition to having the spaceorb/spaceball and serport modules in the
452 kernel, you also need to attach a serial port to it. to do that, run the
453 inputattach program:
455 inputattach --spaceorb /dev/tts/x &
456 or
457 inputattach --spaceball /dev/tts/x &
459 where /dev/tts/x is the serial port which the device is connected to. After
460 doing this, the device will be reported and will start working.
462 There is one caveat with the SpaceOrb. The button #6, the on the bottom
463 side of the orb, although reported as an ordinary button, causes internal
464 recentering of the spaceorb, moving the zero point to the position in which
465 the ball is at the moment of pressing the button. So, think first before
466 you bind it to some other function.
468 SpaceTec SpaceBall 2003 FLX and 3003 FLX are not supported yet.
470 3.19 Logitech SWIFT devices
471 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
472 The SWIFT serial protocol is supported by the warrior.c module. It
473 currently supports only the:
475 * Logitech WingMan Warrior
477 but in the future, Logitech CyberMan (the original one, not CM2) could be
478 supported as well. To use the module, you need to run inputattach after you
479 insert/compile the module into your kernel:
481 inputattach --warrior /dev/tts/x &
483 /dev/tts/x is the serial port your Warrior is attached to.
485 3.20 Magellan / Space Mouse
486 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
487 The Magellan (or Space Mouse), manufactured by LogiCad3d (formerly Space
488 Systems), for many other companies (Logitech, HP, ...) is supported by the
489 joy-magellan module. It currently supports only the:
491 * Magellan 3D
492 * Space Mouse
494 models, the additional buttons on the 'Plus' versions are not supported yet.
496 To use it, you need to attach the serial port to the driver using the
498 inputattach --magellan /dev/tts/x &
500 command. After that the Magellan will be detected, initialized, will beep,
501 and the /dev/input/jsX device should become usable.
503 3.21 I-Force devices
504 ~~~~~~~~~~~~~~~~~~~~
505 All I-Force devices are supported by the iforce module. This includes:
507 * AVB Mag Turbo Force
508 * AVB Top Shot Pegasus
509 * AVB Top Shot Force Feedback Racing Wheel
510 * Logitech WingMan Force
511 * Logitech WingMan Force Wheel
512 * Guillemot Race Leader Force Feedback
513 * Guillemot Force Feedback Racing Wheel
514 * Thrustmaster Motor Sport GT
516 To use it, you need to attach the serial port to the driver using the
518 inputattach --iforce /dev/tts/x &
520 command. After that the I-Force device will be detected, and the
521 /dev/input/jsX device should become usable.
523 In case you're using the device via the USB port, the inputattach command
524 isn't needed.
526 The I-Force driver now supports force feedback via the event interface.
528 Please note that Logitech WingMan *3D devices are _not_ supported by this
529 module, rather by hid. Force feedback is not supported for those devices.
530 Logitech gamepads are also hid devices.
532 3.22 Gravis Stinger gamepad
533 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
534 The Gravis Stinger serial port gamepad, designed for use with laptop
535 computers, is supported by the stinger.c module. To use it, attach the
536 serial port to the driver using:
538 inputattach --stinger /dev/tty/x &
540 where x is the number of the serial port.
542 4. Troubleshooting
543 ~~~~~~~~~~~~~~~~~~
544 There is quite a high probability that you run into some problems. For
545 testing whether the driver works, if in doubt, use the jstest utility in
546 some of its modes. The most useful modes are "normal" - for the 1.x
547 interface, and "old" for the "0.x" interface. You run it by typing:
549 jstest --normal /dev/input/js0
550 jstest --old /dev/input/js0
552 Additionally you can do a test with the evtest utility:
554 evtest /dev/input/event0
556 Oh, and read the FAQ! :)
558 5. FAQ
559 ~~~~~~
560 Q: Running 'jstest /dev/js0' results in "File not found" error. What's the
561 cause?
562 A: The device files don't exist. Create them (see section 2.2).
564 Q: Is it possible to connect my old Atari/Commodore/Amiga/console joystick
565 or pad that uses a 9-pin D-type cannon connector to the serial port of my
566 PC?
567 A: Yes, it is possible, but it'll burn your serial port or the pad. It
568 won't work, of course.
570 Q: My joystick doesn't work with Quake / Quake 2. What's the cause?
571 A: Quake / Quake 2 don't support joystick. Use joy2key to simulate keypresses
572 for them.
574 6. Programming Interface
575 ~~~~~~~~~~~~~~~~~~~~~~~~
576 The 1.0 driver uses a new, event based approach to the joystick driver.
577 Instead of the user program polling for the joystick values, the joystick
578 driver now reports only any changes of its state. See joystick-api.txt,
579 joystick.h and jstest.c included in the joystick package for more
580 information. The joystick device can be used in either blocking or
581 nonblocking mode and supports select() calls.
583 For backward compatibility the old (v0.x) interface is still included.
584 Any call to the joystick driver using the old interface will return values
585 that are compatible to the old interface. This interface is still limited
586 to 2 axes, and applications using it usually decode only 2 buttons, although
587 the driver provides up to 32.