Input: docs - update joystick documentation a bit

Consolidate use instructions and userspace API notes into the same chapter;
remove completely obsolete references, move into a separate subdirectory.

Signed-off-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>

3 files changed, 947 insertions, 0 deletions

diff --git a/Documentation/input/joydev/index.rst b/Documentation/input/joydev/index.rst
new file mode 100644
index 000000000000..8d9666c7561c
--- /dev/null
+++ b/Documentation/input/joydev/index.rst
@@ -0,0 +1,18 @@
+.. include:: <isonum.txt>
+
+======================
+Linux Joystick support
+======================
+
+:Copyright: |copy| 1996-2000 Vojtech Pavlik <vojtech@ucw.cz> - Sponsored by SuSE
+
+.. class:: toc-title
+
+	Table of Contents
+
+.. toctree::
+	:maxdepth: 3
+	:numbered:
+
+	joystick
+	joystick-api
diff --git a/Documentation/input/joydev/joystick-api.rst b/Documentation/input/joydev/joystick-api.rst
new file mode 100644
index 000000000000..42edcfc6e8af
--- /dev/null
+++ b/Documentation/input/joydev/joystick-api.rst
@@ -0,0 +1,346 @@
+=====================
+Programming Interface
+=====================
+
+:Author: Ragnar Hojland Espinosa <ragnar@macula.net> - 7 Aug 1998
+
+Introduction
+============
+
+.. important::
+   This document describes legacy ``js`` interface. Newer clients are
+   encouraged to switch to the generic event (``evdev``) interface.
+
+The 1.0 driver uses a new, event based approach to the joystick driver.
+Instead of the user program polling for the joystick values, the joystick
+driver now reports only any changes of its state. See joystick-api.txt,
+joystick.h and jstest.c included in the joystick package for more
+information. The joystick device can be used in either blocking or
+nonblocking mode, and supports select() calls.
+
+For backward compatibility the old (v0.x) interface is still included.
+Any call to the joystick driver using the old interface will return values
+that are compatible to the old interface. This interface is still limited
+to 2 axes, and applications using it usually decode only 2 buttons, although
+the driver provides up to 32.
+
+Initialization
+==============
+
+Open the joystick device following the usual semantics (that is, with open).
+Since the driver now reports events instead of polling for changes,
+immediately after the open it will issue a series of synthetic events
+(JS_EVENT_INIT) that you can read to obtain the initial state of the
+joystick.
+
+By default, the device is opened in blocking mode::
+
+	int fd = open ("/dev/input/js0", O_RDONLY);
+
+
+Event Reading
+=============
+
+::
+
+	struct js_event e;
+	read (fd, &e, sizeof(e));
+
+where js_event is defined as::
+
+	struct js_event {
+		__u32 time;     /* event timestamp in milliseconds */
+		__s16 value;    /* value */
+		__u8 type;      /* event type */
+		__u8 number;    /* axis/button number */
+	};
+
+If the read is successful, it will return sizeof(e), unless you wanted to read
+more than one event per read as described in section 3.1.
+
+
+js_event.type
+-------------
+
+The possible values of ``type`` are::
+
+	#define JS_EVENT_BUTTON         0x01    /* button pressed/released */
+	#define JS_EVENT_AXIS           0x02    /* joystick moved */
+	#define JS_EVENT_INIT           0x80    /* initial state of device */
+
+As mentioned above, the driver will issue synthetic JS_EVENT_INIT ORed
+events on open. That is, if it's issuing a INIT BUTTON event, the
+current type value will be::
+
+	int type = JS_EVENT_BUTTON | JS_EVENT_INIT;	/* 0x81 */
+
+If you choose not to differentiate between synthetic or real events
+you can turn off the JS_EVENT_INIT bits::
+
+	type &= ~JS_EVENT_INIT;				/* 0x01 */
+
+
+js_event.number
+---------------
+
+The values of ``number`` correspond to the axis or button that
+generated the event. Note that they carry separate numeration (that
+is, you have both an axis 0 and a button 0). Generally,
+
+        =============== =======
+	Axis		number
+        =============== =======
+	1st Axis X	0
+	1st Axis Y	1
+	2nd Axis X	2
+	2nd Axis Y	3
+	...and so on
+        =============== =======
+
+Hats vary from one joystick type to another. Some can be moved in 8
+directions, some only in 4, The driver, however, always reports a hat as two
+independent axis, even if the hardware doesn't allow independent movement.
+
+
+js_event.value
+--------------
+
+For an axis, ``value`` is a signed integer between -32767 and +32767
+representing the position of the joystick along that axis. If you
+don't read a 0 when the joystick is ``dead``, or if it doesn't span the
+full range, you should recalibrate it (with, for example, jscal).
+
+For a button, ``value`` for a press button event is 1 and for a release
+button event is 0.
+
+Though this::
+
+	if (js_event.type == JS_EVENT_BUTTON) {
+		buttons_state ^= (1 << js_event.number);
+	}
+
+may work well if you handle JS_EVENT_INIT events separately,
+
+::
+
+	if ((js_event.type & ~JS_EVENT_INIT) == JS_EVENT_BUTTON) {
+		if (js_event.value)
+			buttons_state |= (1 << js_event.number);
+		else
+			buttons_state &= ~(1 << js_event.number);
+	}
+
+is much safer since it can't lose sync with the driver. As you would
+have to write a separate handler for JS_EVENT_INIT events in the first
+snippet, this ends up being shorter.
+
+
+js_event.time
+-------------
+
+The time an event was generated is stored in ``js_event.time``. It's a time
+in milliseconds since ... well, since sometime in the past.  This eases the
+task of detecting double clicks, figuring out if movement of axis and button
+presses happened at the same time, and similar.
+
+
+Reading
+=======
+
+If you open the device in blocking mode, a read will block (that is,
+wait) forever until an event is generated and effectively read. There
+are two alternatives if you can't afford to wait forever (which is,
+admittedly, a long time;)
+
+	a) use select to wait until there's data to be read on fd, or
+	   until it timeouts. There's a good example on the select(2)
+	   man page.
+
+	b) open the device in non-blocking mode (O_NONBLOCK)
+
+
+O_NONBLOCK
+----------
+
+If read returns -1 when reading in O_NONBLOCK mode, this isn't
+necessarily a "real" error (check errno(3)); it can just mean there
+are no events pending to be read on the driver queue. You should read
+all events on the queue (that is, until you get a -1).
+
+For example,
+
+::
+
+	while (1) {
+		while (read (fd, &e, sizeof(e)) > 0) {
+			process_event (e);
+		}
+		/* EAGAIN is returned when the queue is empty */
+		if (errno != EAGAIN) {
+			/* error */
+		}
+		/* do something interesting with processed events */
+	}
+
+One reason for emptying the queue is that if it gets full you'll start
+missing events since the queue is finite, and older events will get
+overwritten.
+
+The other reason is that you want to know all what happened, and not
+delay the processing till later.
+
+Why can get the queue full? Because you don't empty the queue as
+mentioned, or because too much time elapses from one read to another
+and too many events to store in the queue get generated. Note that
+high system load may contribute to space those reads even more.
+
+If time between reads is enough to fill the queue and lose an event,
+the driver will switch to startup mode and next time you read it,
+synthetic events (JS_EVENT_INIT) will be generated to inform you of
+the actual state of the joystick.
+
+
+.. note::
+
+ As of version 1.2.8, the queue is circular and able to hold 64
+ events. You can increment this size bumping up JS_BUFF_SIZE in
+ joystick.h and recompiling the driver.
+
+
+In the above code, you might as well want to read more than one event
+at a time using the typical read(2) functionality. For that, you would
+replace the read above with something like::
+
+	struct js_event mybuffer[0xff];
+	int i = read (fd, mybuffer, sizeof(mybuffer));
+
+In this case, read would return -1 if the queue was empty, or some
+other value in which the number of events read would be i /
+sizeof(js_event)  Again, if the buffer was full, it's a good idea to
+process the events and keep reading it until you empty the driver queue.
+
+
+IOCTLs
+======
+
+The joystick driver defines the following ioctl(2) operations::
+
+				/* function			3rd arg  */
+	#define JSIOCGAXES	/* get number of axes		char	 */
+	#define JSIOCGBUTTONS	/* get number of buttons	char	 */
+	#define JSIOCGVERSION	/* get driver version		int	 */
+	#define JSIOCGNAME(len) /* get identifier string	char	 */
+	#define JSIOCSCORR	/* set correction values	&js_corr */
+	#define JSIOCGCORR	/* get correction values	&js_corr */
+
+For example, to read the number of axes::
+
+	char number_of_axes;
+	ioctl (fd, JSIOCGAXES, &number_of_axes);
+
+
+JSIOGCVERSION
+-------------
+
+JSIOGCVERSION is a good way to check in run-time whether the running
+driver is 1.0+ and supports the event interface. If it is not, the
+IOCTL will fail. For a compile-time decision, you can test the
+JS_VERSION symbol::
+
+	#ifdef JS_VERSION
+	#if JS_VERSION > 0xsomething
+
+
+JSIOCGNAME
+----------
+
+JSIOCGNAME(len) allows you to get the name string of the joystick - the same
+as is being printed at boot time. The 'len' argument is the length of the
+buffer provided by the application asking for the name. It is used to avoid
+possible overrun should the name be too long::
+
+	char name[128];
+	if (ioctl(fd, JSIOCGNAME(sizeof(name)), name) < 0)
+		strncpy(name, "Unknown", sizeof(name));
+	printf("Name: %s\n", name);
+
+
+JSIOC[SG]CORR
+-------------
+
+For usage on JSIOC[SG]CORR I suggest you to look into jscal.c  They are
+not needed in a normal program, only in joystick calibration software
+such as jscal or kcmjoy. These IOCTLs and data types aren't considered
+to be in the stable part of the API, and therefore may change without
+warning in following releases of the driver.
+
+Both JSIOCSCORR and JSIOCGCORR expect &js_corr to be able to hold
+information for all axis. That is, struct js_corr corr[MAX_AXIS];
+
+struct js_corr is defined as::
+
+	struct js_corr {
+		__s32 coef[8];
+		__u16 prec;
+		__u16 type;
+	};
+
+and ``type``::
+
+	#define JS_CORR_NONE            0x00    /* returns raw values */
+	#define JS_CORR_BROKEN          0x01    /* broken line */
+
+
+Backward compatibility
+======================
+
+The 0.x joystick driver API is quite limited and its usage is deprecated.
+The driver offers backward compatibility, though. Here's a quick summary::
+
+	struct JS_DATA_TYPE js;
+	while (1) {
+		if (read (fd, &js, JS_RETURN) != JS_RETURN) {
+			/* error */
+		}
+		usleep (1000);
+	}
+
+As you can figure out from the example, the read returns immediately,
+with the actual state of the joystick::
+
+	struct JS_DATA_TYPE {
+		int buttons;    /* immediate button state */
+		int x;          /* immediate x axis value */
+		int y;          /* immediate y axis value */
+	};
+
+and JS_RETURN is defined as::
+
+	#define JS_RETURN       sizeof(struct JS_DATA_TYPE)
+
+To test the state of the buttons,
+
+::
+
+	first_button_state  = js.buttons & 1;
+	second_button_state = js.buttons & 2;
+
+The axis values do not have a defined range in the original 0.x driver,
+except for that the values are non-negative. The 1.2.8+ drivers use a
+fixed range for reporting the values, 1 being the minimum, 128 the
+center, and 255 maximum value.
+
+The v0.8.0.2 driver also had an interface for 'digital joysticks', (now
+called Multisystem joysticks in this driver), under /dev/djsX. This driver
+doesn't try to be compatible with that interface.
+
+
+Final Notes
+===========
+
+::
+
+  ____/|	Comments, additions, and specially corrections are welcome.
+  \ o.O|	Documentation valid for at least version 1.2.8 of the joystick
+   =(_)=	driver and as usual, the ultimate source for documentation is
+     U		to "Use The Source Luke" or, at your convenience, Vojtech ;)
diff --git a/Documentation/input/joydev/joystick.rst b/Documentation/input/joydev/joystick.rst
new file mode 100644
index 000000000000..b90705eb69b1
--- /dev/null
+++ b/Documentation/input/joydev/joystick.rst
@@ -0,0 +1,583 @@
+.. include:: <isonum.txt>
+
+Introduction
+============
+
+The joystick driver for Linux provides support for a variety of joysticks
+and similar devices. It is based on a larger project aiming to support all
+input devices in Linux.
+
+The mailing list for the project is:
+
+	linux-input@vger.kernel.org
+
+send "subscribe linux-input" to majordomo@vger.kernel.org to subscribe to it.
+
+Usage
+=====
+
+For basic usage you just choose the right options in kernel config and
+you should be set.
+
+Utilities
+---------
+
+For testing and other purposes (for example serial devices), there is a set
+of utilities, such as ``jstest``, ``jscal``, and ``evtest``,
+usually packaged as ``joystick``, ``input-utils``, ``evtest``, and so on.
+
+``inputattach`` utility is required if your joystick is connected to a
+serial port.
+
+Device nodes
+------------
+
+For applications to be able to use the joysticks, device nodes should be
+created in /dev. Normally it is done automatically by the system, but
+it can also be done by hand::
+
+    cd /dev
+    rm js*
+    mkdir input
+    mknod input/js0 c 13 0
+    mknod input/js1 c 13 1
+    mknod input/js2 c 13 2
+    mknod input/js3 c 13 3
+    ln -s input/js0 js0
+    ln -s input/js1 js1
+    ln -s input/js2 js2
+    ln -s input/js3 js3
+
+For testing with inpututils it's also convenient to create these::
+
+    mknod input/event0 c 13 64
+    mknod input/event1 c 13 65
+    mknod input/event2 c 13 66
+    mknod input/event3 c 13 67
+
+Modules needed
+--------------
+
+For all joystick drivers to function, you'll need the userland interface
+module in kernel, either loaded or compiled in::
+
+	modprobe joydev
+
+For gameport joysticks, you'll have to load the gameport driver as well::
+
+	modprobe ns558
+
+And for serial port joysticks, you'll need the serial input line
+discipline module loaded and the inputattach utility started::
+
+	modprobe serport
+	inputattach -xxx /dev/tts/X &
+
+In addition to that, you'll need the joystick driver module itself, most
+usually you'll have an analog joystick::
+
+	modprobe analog
+
+For automatic module loading, something like this might work - tailor to
+your needs::
+
+	alias tty-ldisc-2 serport
+	alias char-major-13 input
+	above input joydev ns558 analog
+	options analog map=gamepad,none,2btn
+
+Verifying that it works
+-----------------------
+
+For testing the joystick driver functionality, there is the jstest
+program in the utilities package. You run it by typing::
+
+	jstest /dev/input/js0
+
+And it should show a line with the joystick values, which update as you
+move the stick, and press its buttons. The axes should all be zero when the
+joystick is in the center position. They should not jitter by themselves to
+other close values, and they also should be steady in any other position of
+the stick. They should have the full range from -32767 to 32767. If all this
+is met, then it's all fine, and you can play the games. :)
+
+If it's not, then there might be a problem. Try to calibrate the joystick,
+and if it still doesn't work, read the drivers section of this file, the
+troubleshooting section, and the FAQ.
+
+Calibration
+-----------
+
+For most joysticks you won't need any manual calibration, since the
+joystick should be autocalibrated by the driver automagically. However, with
+some analog joysticks, that either do not use linear resistors, or if you
+want better precision, you can use the jscal program::
+
+	jscal -c /dev/input/js0
+
+included in the joystick package to set better correction coefficients than
+what the driver would choose itself.
+
+After calibrating the joystick you can verify if you like the new
+calibration using the jstest command, and if you do, you then can save the
+correction coefficients into a file::
+
+	jscal -p /dev/input/js0 > /etc/joystick.cal
+
+And add a line to your rc script executing that file::
+
+	source /etc/joystick.cal
+
+This way, after the next reboot your joystick will remain calibrated. You
+can also add the ``jscal -p`` line to your shutdown script.
+
+HW specific driver information
+==============================
+
+In this section each of the separate hardware specific drivers is described.
+
+Analog joysticks
+----------------
+
+The analog.c uses the standard analog inputs of the gameport, and thus
+supports all standard joysticks and gamepads. It uses a very advanced
+routine for this, allowing for data precision that can't be found on any
+other system.
+
+It also supports extensions like additional hats and buttons compatible
+with CH Flightstick Pro, ThrustMaster FCS or 6 and 8 button gamepads. Saitek
+Cyborg 'digital' joysticks are also supported by this driver, because
+they're basically souped up CHF sticks.
+
+However the only types that can be autodetected are:
+
+* 2-axis, 4-button joystick
+* 3-axis, 4-button joystick
+* 4-axis, 4-button joystick
+* Saitek Cyborg 'digital' joysticks
+
+For other joystick types (more/less axes, hats, and buttons) support
+you'll need to specify the types either on the kernel command line or on the
+module command line, when inserting analog into the kernel. The
+parameters are::
+
+	analog.map=<type1>,<type2>,<type3>,....
+
+'type' is type of the joystick from the table below, defining joysticks
+present on gameports in the system, starting with gameport0, second 'type'
+entry defining joystick on gameport1 and so on.
+
+	========= =====================================================
+	Type      Meaning
+	========= =====================================================
+	none      No analog joystick on that port
+	auto      Autodetect joystick
+	2btn      2-button n-axis joystick
+	y-joy     Two 2-button 2-axis joysticks on an Y-cable
+	y-pad     Two 2-button 2-axis gamepads on an Y-cable
+	fcs       Thrustmaster FCS compatible joystick
+	chf       Joystick with a CH Flightstick compatible hat
+	fullchf   CH Flightstick compatible with two hats and 6 buttons
+	gamepad   4/6-button n-axis gamepad
+	gamepad8  8-button 2-axis gamepad
+	========= =====================================================
+
+In case your joystick doesn't fit in any of the above categories, you can
+specify the type as a number by combining the bits in the table below. This
+is not recommended unless you really know what are you doing. It's not
+dangerous, but not simple either.
+
+	==== =========================
+	Bit  Meaning
+	==== =========================
+	 0   Axis X1
+	 1   Axis Y1
+	 2   Axis X2
+	 3   Axis Y2
+	 4   Button A
+	 5   Button B
+	 6   Button C
+	 7   Button D
+	 8   CHF Buttons X and Y
+	 9   CHF Hat 1
+	10   CHF Hat 2
+	11   FCS Hat
+	12   Pad Button X
+	13   Pad Button Y
+	14   Pad Button U
+	15   Pad Button V
+	16   Saitek F1-F4 Buttons
+	17   Saitek Digital Mode
+	19   GamePad
+	20   Joy2 Axis X1
+	21   Joy2 Axis Y1
+	22   Joy2 Axis X2
+	23   Joy2 Axis Y2
+	24   Joy2 Button A
+	25   Joy2 Button B
+	26   Joy2 Button C
+	27   Joy2 Button D
+	31   Joy2 GamePad
+	==== =========================
+
+Microsoft SideWinder joysticks
+------------------------------
+
+Microsoft 'Digital Overdrive' protocol is supported by the sidewinder.c
+module. All currently supported joysticks:
+
+* Microsoft SideWinder 3D Pro
+* Microsoft SideWinder Force Feedback Pro
+* Microsoft SideWinder Force Feedback Wheel
+* Microsoft SideWinder FreeStyle Pro
+* Microsoft SideWinder GamePad (up to four, chained)
+* Microsoft SideWinder Precision Pro
+* Microsoft SideWinder Precision Pro USB
+
+are autodetected, and thus no module parameters are needed.
+
+There is one caveat with the 3D Pro. There are 9 buttons reported,
+although the joystick has only 8. The 9th button is the mode switch on the
+rear side of the joystick. However, moving it, you'll reset the joystick,
+and make it unresponsive for about a one third of a second. Furthermore, the
+joystick will also re-center itself, taking the position it was in during
+this time as a new center position. Use it if you want, but think first.
+
+The SideWinder Standard is not a digital joystick, and thus is supported
+by the analog driver described above.
+
+Logitech ADI devices
+--------------------
+
+Logitech ADI protocol is supported by the adi.c module. It should support
+any Logitech device using this protocol. This includes, but is not limited
+to:
+
+* Logitech CyberMan 2
+* Logitech ThunderPad Digital
+* Logitech WingMan Extreme Digital
+* Logitech WingMan Formula
+* Logitech WingMan Interceptor
+* Logitech WingMan GamePad
+* Logitech WingMan GamePad USB
+* Logitech WingMan GamePad Extreme
+* Logitech WingMan Extreme Digital 3D
+
+ADI devices are autodetected, and the driver supports up to two (any
+combination of) devices on a single gameport, using an Y-cable or chained
+together.
+
+Logitech WingMan Joystick, Logitech WingMan Attack, Logitech WingMan
+Extreme and Logitech WingMan ThunderPad are not digital joysticks and are
+handled by the analog driver described above. Logitech WingMan Warrior and
+Logitech Magellan are supported by serial drivers described below.  Logitech
+WingMan Force and Logitech WingMan Formula Force are supported by the
+I-Force driver described below. Logitech CyberMan is not supported yet.
+
+Gravis GrIP
+-----------
+
+Gravis GrIP protocol is supported by the grip.c module. It currently
+supports:
+
+* Gravis GamePad Pro
+* Gravis BlackHawk Digital
+* Gravis Xterminator
+* Gravis Xterminator DualControl
+
+All these devices are autodetected, and you can even use any combination
+of up to two of these pads either chained together or using an Y-cable on a
+single gameport.
+
+GrIP MultiPort isn't supported yet. Gravis Stinger is a serial device and is
+supported by the stinger driver. Other Gravis joysticks are supported by the
+analog driver.
+
+FPGaming A3D and MadCatz A3D
+----------------------------
+
+The Assassin 3D protocol created by FPGaming, is used both by FPGaming
+themselves and is licensed to MadCatz. A3D devices are supported by the
+a3d.c module. It currently supports:
+
+* FPGaming Assassin 3D
+* MadCatz Panther
+* MadCatz Panther XL
+
+All these devices are autodetected. Because the Assassin 3D and the Panther
+allow connecting analog joysticks to them, you'll need to load the analog
+driver as well to handle the attached joysticks.
+
+The trackball should work with USB mousedev module as a normal mouse. See
+the USB documentation for how to setup an USB mouse.
+
+ThrustMaster DirectConnect (BSP)
+--------------------------------
+
+The TM DirectConnect (BSP) protocol is supported by the tmdc.c
+module. This includes, but is not limited to:
+
+* ThrustMaster Millennium 3D Interceptor
+* ThrustMaster 3D Rage Pad
+* ThrustMaster Fusion Digital Game Pad
+
+Devices not directly supported, but hopefully working are:
+
+* ThrustMaster FragMaster
+* ThrustMaster Attack Throttle
+
+If you have one of these, contact me.
+
+TMDC devices are autodetected, and thus no parameters to the module
+are needed. Up to two TMDC devices can be connected to one gameport, using
+an Y-cable.
+
+Creative Labs Blaster
+---------------------
+
+The Blaster protocol is supported by the cobra.c module. It supports only
+the:
+
+* Creative Blaster GamePad Cobra
+
+Up to two of these can be used on a single gameport, using an Y-cable.
+
+Genius Digital joysticks
+------------------------
+
+The Genius digitally communicating joysticks are supported by the gf2k.c
+module. This includes:
+
+* Genius Flight2000 F-23 joystick
+* Genius Flight2000 F-31 joystick
+* Genius G-09D gamepad
+
+Other Genius digital joysticks are not supported yet, but support can be
+added fairly easily.
+
+InterAct Digital joysticks
+--------------------------
+
+The InterAct digitally communicating joysticks are supported by the
+interact.c module. This includes:
+
+* InterAct HammerHead/FX gamepad
+* InterAct ProPad8 gamepad
+
+Other InterAct digital joysticks are not supported yet, but support can be
+added fairly easily.
+
+PDPI Lightning 4 gamecards
+--------------------------
+
+PDPI Lightning 4 gamecards are supported by the lightning.c module.
+Once the module is loaded, the analog driver can be used to handle the
+joysticks. Digitally communicating joystick will work only on port 0, while
+using Y-cables, you can connect up to 8 analog joysticks to a single L4
+card, 16 in case you have two in your system.
+
+Trident 4DWave / Aureal Vortex
+------------------------------
+
+Soundcards with a Trident 4DWave DX/NX or Aureal Vortex/Vortex2 chipsets
+provide an "Enhanced Game Port" mode where the soundcard handles polling the
+joystick.  This mode is supported by the pcigame.c module. Once loaded the
+analog driver can use the enhanced features of these gameports..
+
+Crystal SoundFusion
+-------------------
+
+Soundcards with Crystal SoundFusion chipsets provide an "Enhanced Game
+Port", much like the 4DWave or Vortex above. This, and also the normal mode
+for the port of the SoundFusion is supported by the cs461x.c module.
+
+SoundBlaster Live!
+------------------
+
+The Live! has a special PCI gameport, which, although it doesn't provide
+any "Enhanced" stuff like 4DWave and friends, is quite a bit faster than
+its ISA counterparts. It also requires special support, hence the
+emu10k1-gp.c module for it instead of the normal ns558.c one.
+
+SoundBlaster 64 and 128 - ES1370 and ES1371, ESS Solo1 and S3 SonicVibes
+------------------------------------------------------------------------
+
+These PCI soundcards have specific gameports. They are handled by the
+sound drivers themselves. Make sure you select gameport support in the
+joystick menu and sound card support in the sound menu for your appropriate
+card.
+
+Amiga
+-----
+
+Amiga joysticks, connected to an Amiga, are supported by the amijoy.c
+driver. Since they can't be autodetected, the driver has a command line:
+
+	amijoy.map=<a>,<b>
+
+a and b define the joysticks connected to the JOY0DAT and JOY1DAT ports of
+the Amiga.
+
+	====== ===========================
+	Value  Joystick type
+	====== ===========================
+	  0    None
+	  1    1-button digital joystick
+	====== ===========================
+
+No more joystick types are supported now, but that should change in the
+future if I get an Amiga in the reach of my fingers.
+
+Game console and 8-bit pads and joysticks
+-----------------------------------------
+
+These pads and joysticks are not designed for PCs and other computers
+Linux runs on, and usually require a special connector for attaching
+them through a parallel port.
+
+See :ref:`joystick-parport` for more info.
+
+SpaceTec/LabTec devices
+-----------------------
+
+SpaceTec serial devices communicate using the SpaceWare protocol. It is
+supported by the spaceorb.c and spaceball.c drivers. The devices currently
+supported by spaceorb.c are:
+
+* SpaceTec SpaceBall Avenger
+* SpaceTec SpaceOrb 360
+
+Devices currently supported by spaceball.c are:
+
+* SpaceTec SpaceBall 4000 FLX
+
+In addition to having the spaceorb/spaceball and serport modules in the
+kernel, you also need to attach a serial port to it. to do that, run the
+inputattach program::
+
+	inputattach --spaceorb /dev/tts/x &
+
+or::
+
+	inputattach --spaceball /dev/tts/x &
+
+where /dev/tts/x is the serial port which the device is connected to. After
+doing this, the device will be reported and will start working.
+
+There is one caveat with the SpaceOrb. The button #6, the on the bottom
+side of the orb, although reported as an ordinary button, causes internal
+recentering of the spaceorb, moving the zero point to the position in which
+the ball is at the moment of pressing the button. So, think first before
+you bind it to some other function.
+
+SpaceTec SpaceBall 2003 FLX and 3003 FLX are not supported yet.
+
+Logitech SWIFT devices
+----------------------
+
+The SWIFT serial protocol is supported by the warrior.c module. It
+currently supports only the:
+
+* Logitech WingMan Warrior
+
+but in the future, Logitech CyberMan (the original one, not CM2) could be
+supported as well. To use the module, you need to run inputattach after you
+insert/compile the module into your kernel::
+
+	inputattach --warrior /dev/tts/x &
+
+/dev/tts/x is the serial port your Warrior is attached to.
+
+Magellan / Space Mouse
+----------------------
+
+The Magellan (or Space Mouse), manufactured by LogiCad3d (formerly Space
+Systems), for many other companies (Logitech, HP, ...) is supported by the
+joy-magellan module. It currently supports only the:
+
+* Magellan 3D
+* Space Mouse
+
+models, the additional buttons on the 'Plus' versions are not supported yet.
+
+To use it, you need to attach the serial port to the driver using the::
+
+	inputattach --magellan /dev/tts/x &
+
+command. After that the Magellan will be detected, initialized, will beep,
+and the /dev/input/jsX device should become usable.
+
+I-Force devices
+---------------
+
+All I-Force devices are supported by the iforce module. This includes:
+
+* AVB Mag Turbo Force
+* AVB Top Shot Pegasus
+* AVB Top Shot Force Feedback Racing Wheel
+* Logitech WingMan Force
+* Logitech WingMan Force Wheel
+* Guillemot Race Leader Force Feedback
+* Guillemot Force Feedback Racing Wheel
+* Thrustmaster Motor Sport GT
+
+To use it, you need to attach the serial port to the driver using the::
+
+	inputattach --iforce /dev/tts/x &
+
+command. After that the I-Force device will be detected, and the
+/dev/input/jsX device should become usable.
+
+In case you're using the device via the USB port, the inputattach command
+isn't needed.
+
+The I-Force driver now supports force feedback via the event interface.
+
+Please note that Logitech WingMan 3D devices are _not_ supported by this
+module, rather by hid. Force feedback is not supported for those devices.
+Logitech gamepads are also hid devices.
+
+Gravis Stinger gamepad
+----------------------
+
+The Gravis Stinger serial port gamepad, designed for use with laptop
+computers, is supported by the stinger.c module. To use it, attach the
+serial port to the driver using::
+
+	inputattach --stinger /dev/tty/x &
+
+where x is the number of the serial port.
+
+Troubleshooting
+===============
+
+There is quite a high probability that you run into some problems. For
+testing whether the driver works, if in doubt, use the jstest utility in
+some of its modes. The most useful modes are "normal" - for the 1.x
+interface, and "old" for the "0.x" interface. You run it by typing::
+
+	jstest --normal /dev/input/js0
+	jstest --old    /dev/input/js0
+
+Additionally you can do a test with the evtest utility::
+
+	evtest /dev/input/event0
+
+Oh, and read the FAQ! :)
+
+FAQ
+===
+
+:Q: Running 'jstest /dev/input/js0' results in "File not found" error. What's the
+    cause?
+:A: The device files don't exist. Create them (see section 2.2).
+
+:Q: Is it possible to connect my old Atari/Commodore/Amiga/console joystick
+    or pad that uses a 9-pin D-type cannon connector to the serial port of my
+    PC?
+:A: Yes, it is possible, but it'll burn your serial port or the pad. It
+    won't work, of course.
+
+:Q: My joystick doesn't work with Quake / Quake 2. What's the cause?
+:A: Quake / Quake 2 don't support joystick. Use joy2key to simulate keypresses
+    for them.