cachepc-linux

Fork of AMDESE/linux with modifications for CachePC side-channel attack
git clone https://git.sinitax.com/sinitax/cachepc-linux
Log | Files | Refs | README | LICENSE | sfeed.txt

joystick.rst (18697B)


      1.. include:: <isonum.txt>
      2
      3.. _joystick-doc:
      4
      5Introduction
      6============
      7
      8The joystick driver for Linux provides support for a variety of joysticks
      9and similar devices. It is based on a larger project aiming to support all
     10input devices in Linux.
     11
     12The mailing list for the project is:
     13
     14	linux-input@vger.kernel.org
     15
     16send "subscribe linux-input" to majordomo@vger.kernel.org to subscribe to it.
     17
     18Usage
     19=====
     20
     21For basic usage you just choose the right options in kernel config and
     22you should be set.
     23
     24Utilities
     25---------
     26
     27For testing and other purposes (for example serial devices), there is a set
     28of utilities, such as ``jstest``, ``jscal``, and ``evtest``,
     29usually packaged as ``joystick``, ``input-utils``, ``evtest``, and so on.
     30
     31``inputattach`` utility is required if your joystick is connected to a
     32serial port.
     33
     34Device nodes
     35------------
     36
     37For applications to be able to use the joysticks, device nodes should be
     38created in /dev. Normally it is done automatically by the system, but
     39it can also be done by hand::
     40
     41    cd /dev
     42    rm js*
     43    mkdir input
     44    mknod input/js0 c 13 0
     45    mknod input/js1 c 13 1
     46    mknod input/js2 c 13 2
     47    mknod input/js3 c 13 3
     48    ln -s input/js0 js0
     49    ln -s input/js1 js1
     50    ln -s input/js2 js2
     51    ln -s input/js3 js3
     52
     53For testing with inpututils it's also convenient to create these::
     54
     55    mknod input/event0 c 13 64
     56    mknod input/event1 c 13 65
     57    mknod input/event2 c 13 66
     58    mknod input/event3 c 13 67
     59
     60Modules needed
     61--------------
     62
     63For all joystick drivers to function, you'll need the userland interface
     64module in kernel, either loaded or compiled in::
     65
     66	modprobe joydev
     67
     68For gameport joysticks, you'll have to load the gameport driver as well::
     69
     70	modprobe ns558
     71
     72And for serial port joysticks, you'll need the serial input line
     73discipline module loaded and the inputattach utility started::
     74
     75	modprobe serport
     76	inputattach -xxx /dev/tts/X &
     77
     78In addition to that, you'll need the joystick driver module itself, most
     79usually you'll have an analog joystick::
     80
     81	modprobe analog
     82
     83For automatic module loading, something like this might work - tailor to
     84your needs::
     85
     86	alias tty-ldisc-2 serport
     87	alias char-major-13 input
     88	above input joydev ns558 analog
     89	options analog map=gamepad,none,2btn
     90
     91Verifying that it works
     92-----------------------
     93
     94For testing the joystick driver functionality, there is the jstest
     95program in the utilities package. You run it by typing::
     96
     97	jstest /dev/input/js0
     98
     99And it should show a line with the joystick values, which update as you
    100move the stick, and press its buttons. The axes should all be zero when the
    101joystick is in the center position. They should not jitter by themselves to
    102other close values, and they also should be steady in any other position of
    103the stick. They should have the full range from -32767 to 32767. If all this
    104is met, then it's all fine, and you can play the games. :)
    105
    106If it's not, then there might be a problem. Try to calibrate the joystick,
    107and if it still doesn't work, read the drivers section of this file, the
    108troubleshooting section, and the FAQ.
    109
    110Calibration
    111-----------
    112
    113For most joysticks you won't need any manual calibration, since the
    114joystick should be autocalibrated by the driver automagically. However, with
    115some analog joysticks, that either do not use linear resistors, or if you
    116want better precision, you can use the jscal program::
    117
    118	jscal -c /dev/input/js0
    119
    120included in the joystick package to set better correction coefficients than
    121what the driver would choose itself.
    122
    123After calibrating the joystick you can verify if you like the new
    124calibration using the jstest command, and if you do, you then can save the
    125correction coefficients into a file::
    126
    127	jscal -p /dev/input/js0 > /etc/joystick.cal
    128
    129And add a line to your rc script executing that file::
    130
    131	source /etc/joystick.cal
    132
    133This way, after the next reboot your joystick will remain calibrated. You
    134can also add the ``jscal -p`` line to your shutdown script.
    135
    136Hardware-specific driver information
    137====================================
    138
    139In this section each of the separate hardware specific drivers is described.
    140
    141Analog joysticks
    142----------------
    143
    144The analog.c driver uses the standard analog inputs of the gameport, and thus
    145supports all standard joysticks and gamepads. It uses a very advanced
    146routine for this, allowing for data precision that can't be found on any
    147other system.
    148
    149It also supports extensions like additional hats and buttons compatible
    150with CH Flightstick Pro, ThrustMaster FCS or 6 and 8 button gamepads. Saitek
    151Cyborg 'digital' joysticks are also supported by this driver, because
    152they're basically souped up CHF sticks.
    153
    154However the only types that can be autodetected are:
    155
    156* 2-axis, 4-button joystick
    157* 3-axis, 4-button joystick
    158* 4-axis, 4-button joystick
    159* Saitek Cyborg 'digital' joysticks
    160
    161For other joystick types (more/less axes, hats, and buttons) support
    162you'll need to specify the types either on the kernel command line or on the
    163module command line, when inserting analog into the kernel. The
    164parameters are::
    165
    166	analog.map=<type1>,<type2>,<type3>,....
    167
    168'type' is type of the joystick from the table below, defining joysticks
    169present on gameports in the system, starting with gameport0, second 'type'
    170entry defining joystick on gameport1 and so on.
    171
    172	========= =====================================================
    173	Type      Meaning
    174	========= =====================================================
    175	none      No analog joystick on that port
    176	auto      Autodetect joystick
    177	2btn      2-button n-axis joystick
    178	y-joy     Two 2-button 2-axis joysticks on an Y-cable
    179	y-pad     Two 2-button 2-axis gamepads on an Y-cable
    180	fcs       Thrustmaster FCS compatible joystick
    181	chf       Joystick with a CH Flightstick compatible hat
    182	fullchf   CH Flightstick compatible with two hats and 6 buttons
    183	gamepad   4/6-button n-axis gamepad
    184	gamepad8  8-button 2-axis gamepad
    185	========= =====================================================
    186
    187In case your joystick doesn't fit in any of the above categories, you can
    188specify the type as a number by combining the bits in the table below. This
    189is not recommended unless you really know what are you doing. It's not
    190dangerous, but not simple either.
    191
    192	==== =========================
    193	Bit  Meaning
    194	==== =========================
    195	 0   Axis X1
    196	 1   Axis Y1
    197	 2   Axis X2
    198	 3   Axis Y2
    199	 4   Button A
    200	 5   Button B
    201	 6   Button C
    202	 7   Button D
    203	 8   CHF Buttons X and Y
    204	 9   CHF Hat 1
    205	10   CHF Hat 2
    206	11   FCS Hat
    207	12   Pad Button X
    208	13   Pad Button Y
    209	14   Pad Button U
    210	15   Pad Button V
    211	16   Saitek F1-F4 Buttons
    212	17   Saitek Digital Mode
    213	19   GamePad
    214	20   Joy2 Axis X1
    215	21   Joy2 Axis Y1
    216	22   Joy2 Axis X2
    217	23   Joy2 Axis Y2
    218	24   Joy2 Button A
    219	25   Joy2 Button B
    220	26   Joy2 Button C
    221	27   Joy2 Button D
    222	31   Joy2 GamePad
    223	==== =========================
    224
    225Microsoft SideWinder joysticks
    226------------------------------
    227
    228Microsoft 'Digital Overdrive' protocol is supported by the sidewinder.c
    229module. All currently supported joysticks:
    230
    231* Microsoft SideWinder 3D Pro
    232* Microsoft SideWinder Force Feedback Pro
    233* Microsoft SideWinder Force Feedback Wheel
    234* Microsoft SideWinder FreeStyle Pro
    235* Microsoft SideWinder GamePad (up to four, chained)
    236* Microsoft SideWinder Precision Pro
    237* Microsoft SideWinder Precision Pro USB
    238
    239are autodetected, and thus no module parameters are needed.
    240
    241There is one caveat with the 3D Pro. There are 9 buttons reported,
    242although the joystick has only 8. The 9th button is the mode switch on the
    243rear side of the joystick. However, moving it, you'll reset the joystick,
    244and make it unresponsive for about a one third of a second. Furthermore, the
    245joystick will also re-center itself, taking the position it was in during
    246this time as a new center position. Use it if you want, but think first.
    247
    248The SideWinder Standard is not a digital joystick, and thus is supported
    249by the analog driver described above.
    250
    251Logitech ADI devices
    252--------------------
    253
    254Logitech ADI protocol is supported by the adi.c module. It should support
    255any Logitech device using this protocol. This includes, but is not limited
    256to:
    257
    258* Logitech CyberMan 2
    259* Logitech ThunderPad Digital
    260* Logitech WingMan Extreme Digital
    261* Logitech WingMan Formula
    262* Logitech WingMan Interceptor
    263* Logitech WingMan GamePad
    264* Logitech WingMan GamePad USB
    265* Logitech WingMan GamePad Extreme
    266* Logitech WingMan Extreme Digital 3D
    267
    268ADI devices are autodetected, and the driver supports up to two (any
    269combination of) devices on a single gameport, using a Y-cable or chained
    270together.
    271
    272Logitech WingMan Joystick, Logitech WingMan Attack, Logitech WingMan
    273Extreme and Logitech WingMan ThunderPad are not digital joysticks and are
    274handled by the analog driver described above. Logitech WingMan Warrior and
    275Logitech Magellan are supported by serial drivers described below.  Logitech
    276WingMan Force and Logitech WingMan Formula Force are supported by the
    277I-Force driver described below. Logitech CyberMan is not supported yet.
    278
    279Gravis GrIP
    280-----------
    281
    282Gravis GrIP protocol is supported by the grip.c module. It currently
    283supports:
    284
    285* Gravis GamePad Pro
    286* Gravis BlackHawk Digital
    287* Gravis Xterminator
    288* Gravis Xterminator DualControl
    289
    290All these devices are autodetected, and you can even use any combination
    291of up to two of these pads either chained together or using a Y-cable on a
    292single gameport.
    293
    294GrIP MultiPort isn't supported yet. Gravis Stinger is a serial device and is
    295supported by the stinger driver. Other Gravis joysticks are supported by the
    296analog driver.
    297
    298FPGaming A3D and MadCatz A3D
    299----------------------------
    300
    301The Assassin 3D protocol created by FPGaming, is used both by FPGaming
    302themselves and is licensed to MadCatz. A3D devices are supported by the
    303a3d.c module. It currently supports:
    304
    305* FPGaming Assassin 3D
    306* MadCatz Panther
    307* MadCatz Panther XL
    308
    309All these devices are autodetected. Because the Assassin 3D and the Panther
    310allow connecting analog joysticks to them, you'll need to load the analog
    311driver as well to handle the attached joysticks.
    312
    313The trackball should work with USB mousedev module as a normal mouse. See
    314the USB documentation for how to setup a USB mouse.
    315
    316ThrustMaster DirectConnect (BSP)
    317--------------------------------
    318
    319The TM DirectConnect (BSP) protocol is supported by the tmdc.c
    320module. This includes, but is not limited to:
    321
    322* ThrustMaster Millennium 3D Interceptor
    323* ThrustMaster 3D Rage Pad
    324* ThrustMaster Fusion Digital Game Pad
    325
    326Devices not directly supported, but hopefully working are:
    327
    328* ThrustMaster FragMaster
    329* ThrustMaster Attack Throttle
    330
    331If you have one of these, contact me.
    332
    333TMDC devices are autodetected, and thus no parameters to the module
    334are needed. Up to two TMDC devices can be connected to one gameport, using
    335a Y-cable.
    336
    337Creative Labs Blaster
    338---------------------
    339
    340The Blaster protocol is supported by the cobra.c module. It supports only
    341the:
    342
    343* Creative Blaster GamePad Cobra
    344
    345Up to two of these can be used on a single gameport, using a Y-cable.
    346
    347Genius Digital joysticks
    348------------------------
    349
    350The Genius digitally communicating joysticks are supported by the gf2k.c
    351module. This includes:
    352
    353* Genius Flight2000 F-23 joystick
    354* Genius Flight2000 F-31 joystick
    355* Genius G-09D gamepad
    356
    357Other Genius digital joysticks are not supported yet, but support can be
    358added fairly easily.
    359
    360InterAct Digital joysticks
    361--------------------------
    362
    363The InterAct digitally communicating joysticks are supported by the
    364interact.c module. This includes:
    365
    366* InterAct HammerHead/FX gamepad
    367* InterAct ProPad8 gamepad
    368
    369Other InterAct digital joysticks are not supported yet, but support can be
    370added fairly easily.
    371
    372PDPI Lightning 4 gamecards
    373--------------------------
    374
    375PDPI Lightning 4 gamecards are supported by the lightning.c module.
    376Once the module is loaded, the analog driver can be used to handle the
    377joysticks. Digitally communicating joystick will work only on port 0, while
    378using Y-cables, you can connect up to 8 analog joysticks to a single L4
    379card, 16 in case you have two in your system.
    380
    381Trident 4DWave / Aureal Vortex
    382------------------------------
    383
    384Soundcards with a Trident 4DWave DX/NX or Aureal Vortex/Vortex2 chipset
    385provide an "Enhanced Game Port" mode where the soundcard handles polling the
    386joystick.  This mode is supported by the pcigame.c module. Once loaded the
    387analog driver can use the enhanced features of these gameports..
    388
    389Crystal SoundFusion
    390-------------------
    391
    392Soundcards with Crystal SoundFusion chipsets provide an "Enhanced Game
    393Port", much like the 4DWave or Vortex above. This, and also the normal mode
    394for the port of the SoundFusion is supported by the cs461x.c module.
    395
    396SoundBlaster Live!
    397------------------
    398
    399The Live! has a special PCI gameport, which, although it doesn't provide
    400any "Enhanced" stuff like 4DWave and friends, is quite a bit faster than
    401its ISA counterparts. It also requires special support, hence the
    402emu10k1-gp.c module for it instead of the normal ns558.c one.
    403
    404SoundBlaster 64 and 128 - ES1370 and ES1371, ESS Solo1 and S3 SonicVibes
    405------------------------------------------------------------------------
    406
    407These PCI soundcards have specific gameports. They are handled by the
    408sound drivers themselves. Make sure you select gameport support in the
    409joystick menu and sound card support in the sound menu for your appropriate
    410card.
    411
    412Amiga
    413-----
    414
    415Amiga joysticks, connected to an Amiga, are supported by the amijoy.c
    416driver. Since they can't be autodetected, the driver has a command line:
    417
    418	amijoy.map=<a>,<b>
    419
    420a and b define the joysticks connected to the JOY0DAT and JOY1DAT ports of
    421the Amiga.
    422
    423	====== ===========================
    424	Value  Joystick type
    425	====== ===========================
    426	  0    None
    427	  1    1-button digital joystick
    428	====== ===========================
    429
    430No more joystick types are supported now, but that should change in the
    431future if I get an Amiga in the reach of my fingers.
    432
    433Game console and 8-bit pads and joysticks
    434-----------------------------------------
    435
    436These pads and joysticks are not designed for PCs and other computers
    437Linux runs on, and usually require a special connector for attaching
    438them through a parallel port.
    439
    440See :ref:`joystick-parport` for more info.
    441
    442SpaceTec/LabTec devices
    443-----------------------
    444
    445SpaceTec serial devices communicate using the SpaceWare protocol. It is
    446supported by the spaceorb.c and spaceball.c drivers. The devices currently
    447supported by spaceorb.c are:
    448
    449* SpaceTec SpaceBall Avenger
    450* SpaceTec SpaceOrb 360
    451
    452Devices currently supported by spaceball.c are:
    453
    454* SpaceTec SpaceBall 4000 FLX
    455
    456In addition to having the spaceorb/spaceball and serport modules in the
    457kernel, you also need to attach a serial port to it. To do that, run the
    458inputattach program::
    459
    460	inputattach --spaceorb /dev/tts/x &
    461
    462or::
    463
    464	inputattach --spaceball /dev/tts/x &
    465
    466where /dev/tts/x is the serial port which the device is connected to. After
    467doing this, the device will be reported and will start working.
    468
    469There is one caveat with the SpaceOrb. The button #6, the one on the bottom
    470side of the orb, although reported as an ordinary button, causes internal
    471recentering of the spaceorb, moving the zero point to the position in which
    472the ball is at the moment of pressing the button. So, think first before
    473you bind it to some other function.
    474
    475SpaceTec SpaceBall 2003 FLX and 3003 FLX are not supported yet.
    476
    477Logitech SWIFT devices
    478----------------------
    479
    480The SWIFT serial protocol is supported by the warrior.c module. It
    481currently supports only the:
    482
    483* Logitech WingMan Warrior
    484
    485but in the future, Logitech CyberMan (the original one, not CM2) could be
    486supported as well. To use the module, you need to run inputattach after you
    487insert/compile the module into your kernel::
    488
    489	inputattach --warrior /dev/tts/x &
    490
    491/dev/tts/x is the serial port your Warrior is attached to.
    492
    493Magellan / Space Mouse
    494----------------------
    495
    496The Magellan (or Space Mouse), manufactured by LogiCad3d (formerly Space
    497Systems), for many other companies (Logitech, HP, ...) is supported by the
    498joy-magellan module. It currently supports only the:
    499
    500* Magellan 3D
    501* Space Mouse
    502
    503models; the additional buttons on the 'Plus' versions are not supported yet.
    504
    505To use it, you need to attach the serial port to the driver using the::
    506
    507	inputattach --magellan /dev/tts/x &
    508
    509command. After that the Magellan will be detected, initialized, will beep,
    510and the /dev/input/jsX device should become usable.
    511
    512I-Force devices
    513---------------
    514
    515All I-Force devices are supported by the iforce module. This includes:
    516
    517* AVB Mag Turbo Force
    518* AVB Top Shot Pegasus
    519* AVB Top Shot Force Feedback Racing Wheel
    520* Logitech WingMan Force
    521* Logitech WingMan Force Wheel
    522* Guillemot Race Leader Force Feedback
    523* Guillemot Force Feedback Racing Wheel
    524* Thrustmaster Motor Sport GT
    525
    526To use it, you need to attach the serial port to the driver using the::
    527
    528	inputattach --iforce /dev/tts/x &
    529
    530command. After that the I-Force device will be detected, and the
    531/dev/input/jsX device should become usable.
    532
    533In case you're using the device via the USB port, the inputattach command
    534isn't needed.
    535
    536The I-Force driver now supports force feedback via the event interface.
    537
    538Please note that Logitech WingMan 3D devices are _not_ supported by this
    539module, rather by hid. Force feedback is not supported for those devices.
    540Logitech gamepads are also hid devices.
    541
    542Gravis Stinger gamepad
    543----------------------
    544
    545The Gravis Stinger serial port gamepad, designed for use with laptop
    546computers, is supported by the stinger.c module. To use it, attach the
    547serial port to the driver using::
    548
    549	inputattach --stinger /dev/tty/x &
    550
    551where x is the number of the serial port.
    552
    553Troubleshooting
    554===============
    555
    556There is quite a high probability that you run into some problems. For
    557testing whether the driver works, if in doubt, use the jstest utility in
    558some of its modes. The most useful modes are "normal" - for the 1.x
    559interface, and "old" for the "0.x" interface. You run it by typing::
    560
    561	jstest --normal /dev/input/js0
    562	jstest --old    /dev/input/js0
    563
    564Additionally you can do a test with the evtest utility::
    565
    566	evtest /dev/input/event0
    567
    568Oh, and read the FAQ! :)
    569
    570FAQ
    571===
    572
    573:Q: Running 'jstest /dev/input/js0' results in "File not found" error. What's the
    574    cause?
    575:A: The device files don't exist. Create them (see section 2.2).
    576
    577:Q: Is it possible to connect my old Atari/Commodore/Amiga/console joystick
    578    or pad that uses a 9-pin D-type Cannon connector to the serial port of my
    579    PC?
    580:A: Yes, it is possible, but it'll burn your serial port or the pad. It
    581    won't work, of course.
    582
    583:Q: My joystick doesn't work with Quake / Quake 2. What's the cause?
    584:A: Quake / Quake 2 don't support joystick. Use joy2key to simulate keypresses
    585    for them.