From 1da177e4c3f41524e886b7f1b8a0c1fc7321cac2 Mon Sep 17 00:00:00 2001 From: Linus Torvalds Date: Sat, 16 Apr 2005 15:20:36 -0700 Subject: Linux-2.6.12-rc2 Initial git repository build. I'm not bothering with the full history, even though we have it. We can create a separate "historical" git archive of that later if we want to, and in the meantime it's about 3.2GB when imported into git - space that would just make the early git days unnecessarily complicated, when we don't have a lot of good infrastructure for it. Let it rip! --- Documentation/input/amijoy.txt | 184 +++++++ Documentation/input/atarikbd.txt | 709 +++++++++++++++++++++++++++ Documentation/input/cd32.txt | 19 + Documentation/input/cs461x.txt | 45 ++ Documentation/input/ff.txt | 227 +++++++++ Documentation/input/gameport-programming.txt | 189 +++++++ Documentation/input/iforce-protocol.txt | 254 ++++++++++ Documentation/input/input-programming.txt | 281 +++++++++++ Documentation/input/input.txt | 312 ++++++++++++ Documentation/input/interactive.fig | 42 ++ Documentation/input/joystick-api.txt | 316 ++++++++++++ Documentation/input/joystick-parport.txt | 542 ++++++++++++++++++++ Documentation/input/joystick.txt | 588 ++++++++++++++++++++++ Documentation/input/shape.fig | 65 +++ Documentation/input/xpad.txt | 116 +++++ 15 files changed, 3889 insertions(+) create mode 100644 Documentation/input/amijoy.txt create mode 100644 Documentation/input/atarikbd.txt create mode 100644 Documentation/input/cd32.txt create mode 100644 Documentation/input/cs461x.txt create mode 100644 Documentation/input/ff.txt create mode 100644 Documentation/input/gameport-programming.txt create mode 100644 Documentation/input/iforce-protocol.txt create mode 100644 Documentation/input/input-programming.txt create mode 100644 Documentation/input/input.txt create mode 100644 Documentation/input/interactive.fig create mode 100644 Documentation/input/joystick-api.txt create mode 100644 Documentation/input/joystick-parport.txt create mode 100644 Documentation/input/joystick.txt create mode 100644 Documentation/input/shape.fig create mode 100644 Documentation/input/xpad.txt (limited to 'Documentation/input') diff --git a/Documentation/input/amijoy.txt b/Documentation/input/amijoy.txt new file mode 100644 index 00000000000..3b8b2d43a68 --- /dev/null +++ b/Documentation/input/amijoy.txt @@ -0,0 +1,184 @@ +Amiga 4-joystick parport extension +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Parallel port pins: + + (2) - Up1 (6) - Up2 + (3) - Down1 (7) - Down2 + (4) - Left1 (8) - Left2 + (5) - Right1 (9) - Right2 +(13) - Fire1 (11) - Fire2 +(18) - Gnd1 (18) - Gnd2 + +Amiga digital joystick pinout +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +(1) - Up +(2) - Down +(3) - Left +(4) - Right +(5) - n/c +(6) - Fire button +(7) - +5V (50mA) +(8) - Gnd +(9) - Thumb button + +Amiga mouse pinout +~~~~~~~~~~~~~~~~~~ +(1) - V-pulse +(2) - H-pulse +(3) - VQ-pulse +(4) - HQ-pulse +(5) - Middle button +(6) - Left button +(7) - +5V (50mA) +(8) - Gnd +(9) - Right button + +Amiga analog joystick pinout +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +(1) - Top button +(2) - Top2 button +(3) - Trigger button +(4) - Thumb button +(5) - Analog X +(6) - n/c +(7) - +5V (50mA) +(8) - Gnd +(9) - Analog Y + +Amiga lightpen pinout +~~~~~~~~~~~~~~~~~~~~~ +(1) - n/c +(2) - n/c +(3) - n/c +(4) - n/c +(5) - Touch button +(6) - /Beamtrigger +(7) - +5V (50mA) +(8) - Gnd +(9) - Stylus button + +------------------------------------------------------------------------------- + +NAME rev ADDR type chip Description +JOY0DAT 00A R Denise Joystick-mouse 0 data (left vert, horiz) +JOY1DAT 00C R Denise Joystick-mouse 1 data (right vert,horiz) + + These addresses each read a 16 bit register. These in turn + are loaded from the MDAT serial stream and are clocked in on + the rising edge of SCLK. MLD output is used to parallel load + the external parallel-to-serial converter.This in turn is + loaded with the 4 quadrature inputs from each of two game + controller ports (8 total) plus 8 miscellaneous control bits + which are new for LISA and can be read in upper 8 bits of + LISAID. + Register bits are as follows: + Mouse counter usage (pins 1,3 =Yclock, pins 2,4 =Xclock) + + BIT# 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00 +JOY0DAT Y7 Y6 Y5 Y4 Y3 Y2 Y1 Y0 X7 X6 X5 X4 X3 X2 X1 X0 +JOY1DAT Y7 Y6 Y5 Y4 Y3 Y2 Y1 Y0 X7 X6 X5 X4 X3 X2 X1 X0 + + 0=LEFT CONTROLLER PAIR, 1=RIGHT CONTROLLER PAIR. + (4 counters total).The bit usage for both left and right + addresses is shown below. Each 6 bit counter (Y7-Y2,X7-X2) is + clocked by 2 of the signals input from the mouse serial + stream. Starting with first bit recived: + + +-------------------+-----------------------------------------+ + | Serial | Bit Name | Description | + +--------+----------+-----------------------------------------+ + | 0 | M0H | JOY0DAT Horizontal Clock | + | 1 | M0HQ | JOY0DAT Horizontal Clock (quadrature) | + | 2 | M0V | JOY0DAT Vertical Clock | + | 3 | M0VQ | JOY0DAT Vertical Clock (quadrature) | + | 4 | M1V | JOY1DAT Horizontall Clock | + | 5 | M1VQ | JOY1DAT Horizontall Clock (quadrature) | + | 6 | M1V | JOY1DAT Vertical Clock | + | 7 | M1VQ | JOY1DAT Vertical Clock (quadrature) | + +--------+----------+-----------------------------------------+ + + Bits 1 and 0 of each counter (Y1-Y0,X1-X0) may be + read to determine the state of the related input signal pair. + This allows these pins to double as joystick switch inputs. + Joystick switch closures can be deciphered as follows: + + +------------+------+---------------------------------+ + | Directions | Pin# | Counter bits | + +------------+------+---------------------------------+ + | Forward | 1 | Y1 xor Y0 (BIT#09 xor BIT#08) | + | Left | 3 | Y1 | + | Back | 2 | X1 xor X0 (BIT#01 xor BIT#00) | + | Right | 4 | X1 | + +------------+------+---------------------------------+ + +------------------------------------------------------------------------------- + +NAME rev ADDR type chip Description +JOYTEST 036 W Denise Write to all 4 joystick-mouse counters at once. + + Mouse counter write test data: + BIT# 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00 + JOYxDAT Y7 Y6 Y5 Y4 Y3 Y2 xx xx X7 X6 X5 X4 X3 X2 xx xx + JOYxDAT Y7 Y6 Y5 Y4 Y3 Y2 xx xx X7 X6 X5 X4 X3 X2 xx xx + +------------------------------------------------------------------------------- + +NAME rev ADDR type chip Description +POT0DAT h 012 R Paula Pot counter data left pair (vert, horiz) +POT1DAT h 014 R Paula Pot counter data right pair (vert,horiz) + + These addresses each read a pair of 8 bit pot counters. + (4 counters total). The bit assignment for both + addresses is shown below. The counters are stopped by signals + from 2 controller connectors (left-right) with 2 pins each. + + BIT# 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00 + RIGHT Y7 Y6 Y5 Y4 Y3 Y2 Y1 Y0 X7 X6 X5 X4 X3 X2 X1 X0 + LEFT Y7 Y6 Y5 Y4 Y3 Y2 Y1 Y0 X7 X6 X5 X4 X3 X2 X1 X0 + + +--------------------------+-------+ + | CONNECTORS | PAULA | + +-------+------+-----+-----+-------+ + | Loc. | Dir. | Sym | pin | pin | + +-------+------+-----+-----+-------+ + | RIGHT | Y | RX | 9 | 33 | + | RIGHT | X | RX | 5 | 32 | + | LEFT | Y | LY | 9 | 36 | + | LEFT | X | LX | 5 | 35 | + +-------+------+-----+-----+-------+ + + With normal (NTSC or PAL) horiz. line rate, the pots will + give a full scale (FF) reading with about 500kohms in one + frame time. With proportionally faster horiz line times, + the counters will count proportionally faster. + This should be noted when doing variable beam displays. + +------------------------------------------------------------------------------- + +NAME rev ADDR type chip Description +POTGO 034 W Paula Pot port (4 bit) bi-direction and data, and pot counter start. + +------------------------------------------------------------------------------- + +NAME rev ADDR type chip Description +POTINP 016 R Paula Pot pin data read + + This register controls a 4 bit bi-direction I/O port + that shares the same 4 pins as the 4 pot counters above. + + +-------+----------+---------------------------------------------+ + | BIT# | FUNCTION | DESCRIPTION | + +-------+----------+---------------------------------------------+ + | 15 | OUTRY | Output enable for Paula pin 33 | + | 14 | DATRY | I/O data Paula pin 33 | + | 13 | OUTRX | Output enable for Paula pin 32 | + | 12 | DATRX | I/O data Paula pin 32 | + | 11 | OUTLY | Out put enable for Paula pin 36 | + | 10 | DATLY | I/O data Paula pin 36 | + | 09 | OUTLX | Output enable for Paula pin 35 | + | 08 | DATLX | I/O data Paula pin 35 | + | 07-01 | X | Not used | + | 00 | START | Start pots (dump capacitors,start counters) | + +-------+----------+---------------------------------------------+ + +------------------------------------------------------------------------------- diff --git a/Documentation/input/atarikbd.txt b/Documentation/input/atarikbd.txt new file mode 100644 index 00000000000..8fb896c7411 --- /dev/null +++ b/Documentation/input/atarikbd.txt @@ -0,0 +1,709 @@ +Intelligent Keyboard (ikbd) Protocol + + +1. Introduction + +The Atari Corp. Intelligent Keyboard (ikbd) is a general purpose keyboard +controller that is flexible enough that it can be used in a variety of +products without modification. The keyboard, with its microcontroller, +provides a convenient connection point for a mouse and switch-type joysticks. +The ikbd processor also maintains a time-of-day clock with one second +resolution. +The ikbd has been designed to be general enough that it can be used with a +ariety of new computer products. Product variations in a number of +keyswitches, mouse resolution, etc. can be accommodated. +The ikbd communicates with the main processor over a high speed bi-directional +serial interface. It can function in a variety of modes to facilitate +different applications of the keyboard, joysticks, or mouse. Limited use of +the controller is possible in applications in which only a unidirectional +communications medium is available by carefully designing the default modes. + +3. Keyboard + +The keyboard always returns key make/break scan codes. The ikbd generates +keyboard scan codes for each key press and release. The key scan make (key +closure) codes start at 1, and are defined in Appendix A. For example, the +ISO key position in the scan code table should exist even if no keyswitch +exists in that position on a particular keyboard. The break code for each key +is obtained by ORing 0x80 with the make code. + +The special codes 0xF6 through 0xFF are reserved for use as follows: + 0xF6 status report + 0xF7 absolute mouse position record + 0xF8-0xFB relative mouse position records(lsbs determind by + mouse button states) + 0xFC time-of-day + 0xFD joystick report (both sticks) + 0xFE joystick 0 event + 0xFF joystick 1 event + +The two shift keys return different scan codes in this mode. The ENTER key +and the RETurn key are also distinct. + +4. Mouse + +The mouse port should be capable of supporting a mouse with resolution of +approximately 200 counts (phase changes or 'clicks') per inch of travel. The +mouse should be scanned at a rate that will permit accurate tracking at +velocities up to 10 inches per second. +The ikbd can report mouse motion in three distinctly different ways. It can +report relative motion, absolute motion in a coordinate system maintained +within the ikbd, or by converting mouse motion into keyboard cursor control +key equivalents. +The mouse buttons can be treated as part of the mouse or as additional +keyboard keys. + +4.1 Relative Position Reporting + +In relative position mode, the ikbd will return relative mouse position +records whenever a mouse event occurs. A mouse event consists of a mouse +button being pressed or released, or motion in either axis exceeding a +settable threshold of motion. Regardless of the threshold, all bits of +resolution are returned to the host computer. +Note that the ikbd may return mouse relative position reports with +significantly more than the threshold delta x or y. This may happen since no +relative mouse motion events will be generated: (a) while the keyboard has +been 'paused' ( the event will be stored until keyboard communications is +resumed) (b) while any event is being transmitted. + +The relative mouse position record is a three byte record of the form +(regardless of keyboard mode): + %111110xy ; mouse position record flag + ; where y is the right button state + ; and x is the left button state + X ; delta x as twos complement integer + Y ; delta y as twos complement integer + +Note that the value of the button state bits should be valid even if the +MOUSE BUTTON ACTION has set the buttons to act like part of the keyboard. +If the accumulated motion before the report packet is generated exceeds the ++127...-128 range, the motion is broken into multiple packets. +Note that the sign of the delta y reported is a function of the Y origin +selected. + +4.2 Absolute Position reporting + +The ikbd can also maintain absolute mouse position. Commands exist for +reseting the mouse position, setting X/Y scaling, and interrogating the +current mouse position. + +4.3 Mouse Cursor Key Mode + +The ikbd can translate mouse motion into the equivalent cursor keystrokes. +The number of mouse clicks per keystroke is independently programmable in +each axis. The ikbd internally maintains mouse motion information to the +highest resolution available, and merely generates a pair of cursor key events +for each multiple of the scale factor. +Mouse motion produces the cursor key make code immediately followed by the +break code for the appropriate cursor key. The mouse buttons produce scan +codes above those normally assigned for the largest envisioned keyboard (i.e. +LEFT=0x74 & RIGHT=0x75). + +5. Joystick + +5.1 Joystick Event Reporting + +In this mode, the ikbd generates a record whever the joystick position is +changed (i.e. for each opening or closing of a joystick switch or trigger). + +The joystick event record is two bytes of the form: + %1111111x ; Joystick event marker + ; where x is Joystick 0 or 1 + %x000yyyy ; where yyyy is the stick position + ; and x is the trigger + +5.2 Joystick Interrogation + +The current state of the joystick ports may be interrogated at any time in +this mode by sending an 'Interrogate Joystick' command to the ikbd. + +The ikbd response to joystick interrogation is a three byte report of the form + 0xFD ; joystick report header + %x000yyyy ; Joystick 0 + %x000yyyy ; Joystick 1 + ; where x is the trigger + ; and yyy is the stick position + +5.3 Joystick Monitoring + +A mode is available that devotes nearly all of the keyboard communications +time to reporting the state of the joystick ports at a user specifiable rate. +It remains in this mode until reset or commanded into another mode. The PAUSE +command in this mode not only stop the output but also temporarily stops +scanning the joysticks (samples are not queued). + +5.4 Fire Button Monitoring + +A mode is provided to permit monitoring a single input bit at a high rate. In +this mode the ikbd monitors the state of the Joystick 1 fire button at the +maximum rate permitted by the serial communication channel. The data is packed +8 bits per byte for transmission to the host. The ikbd remains in this mode +until reset or commanded into another mode. The PAUSE command in this mode not +only stops the output but also temporarily stops scanning the button (samples +are not queued). + +5.5 Joystick Key Code Mode + +The ikbd may be commanded to translate the use of either joystick into the +equivalent cursor control keystroke(s). The ikbd provides a single breakpoint +velocity joystick cursor. +Joystick events produce the make code, immediately followed by the break code +for the appropriate cursor motion keys. The trigger or fire buttons of the +joysticks produce pseudo key scan codes above those used by the largest key +matrix envisioned (i.e. JOYSTICK0=0x74, JOYSTICK1=0x75). + +6. Time-of-Day Clock + +The ikbd also maintains a time-of-day clock for the system. Commands are +available to set and interrogate the timer-of-day clock. Time-keeping is +maintained down to a resolution of one second. + +7. Status Inquiries + +The current state of ikbd modes and parameters may be found by sending status +inquiry commands that correspond to the ikbd set commands. + +8. Power-Up Mode + +The keyboard controller will perform a simple self-test on power-up to detect +major controller faults (ROM checksum and RAM test) and such things as stuck +keys. Any keys down at power-up are presumed to be stuck, and their BREAK +(sic) code is returned (which without the preceding MAKE code is a flag for a +keyboard error). If the controller self-test completes without error, the code +0xF0 is returned. (This code will be used to indicate the version/rlease of +the ikbd controller. The first release of the ikbd is version 0xF0, should +there be a second release it will be 0xF1, and so on.) +The ikbd defaults to a mouse position reporting with threshold of 1 unit in +either axis and the Y=0 origin at the top of the screen, and joystick event +reporting mode for joystick 1, with both buttons being logically assigned to +the mouse. After any joystick command, the ikbd assumes that joysticks are +connected to both Joystick0 and Joystick1. Any mouse command (except MOUSE +DISABLE) then causes port 0 to again be scanned as if it were a mouse, and +both buttons are logically connected to it. If a mouse diable command is +received while port 0 is presumed to be a mouse, the button is logically +assigned to Joystick1 ( until the mouse is reenabled by another mouse command). + +9. ikbd Command Set + +This section contains a list of commands that can be sent to the ikbd. Command +codes (such as 0x00) which are not specified should perform no operation +(NOPs). + +9.1 RESET + + 0x80 + 0x01 + +N.B. The RESET command is the only two byte command understood by the ikbd. +Any byte following an 0x80 command byte other than 0x01 is ignored (and causes +the 0x80 to be ignored). +A reset may also be caused by sending a break lasting at least 200mS to the +ikbd. +Executing the RESET command returns the keyboard to its default (power-up) +mode and parameter settings. It does not affect the time-of-day clock. +The RESET command or function causes the ikbd to perform a simple self-test. +If the test is successful, the ikbd will send the code of 0xF0 within 300mS +of receipt of the RESET command (or the end of the break, or power-up). The +ikbd will then scan the key matrix for any stuck (closed) keys. Any keys found +closed will cause the break scan code to be generated (the break code arriving +without being preceded by the make code is a flag for a key matrix error). + +9.2. SET MOUSE BUTTON ACTION + + 0x07 + %00000mss ; mouse button action + ; (m is presumed = 1 when in MOUSE KEYCODE mode) + ; mss=0xy, mouse button press or release causes mouse + ; position report + ; where y=1, mouse key press causes absolute report + ; and x=1, mouse key release causes absolute report + ; mss=100, mouse buttons act like keys + +This command sets how the ikbd should treat the buttons on the mouse. The +default mouse button action mode is %00000000, the buttons are treated as part +of the mouse logically. +When buttons act like keys, LEFT=0x74 & RIGHT=0x75. + +9.3 SET RELATIVE MOUSE POSITION REPORTING + + 0x08 + +Set relative mouse position reporting. (DEFAULT) Mouse position packets are +generated asynchronously by the ikbd whenever motion exceeds the setable +threshold in either axis (see SET MOUSE THRESHOLD). Depending upon the mouse +key mode, mouse position reports may also be generated when either mouse +button is pressed or released. Otherwise the mouse buttons behave as if they +were keyboard keys. + +9.4 SET ABSOLUTE MOUSE POSITIONING + + 0x09 + XMSB ; X maximum (in scaled mouse clicks) + XLSB + YMSB ; Y maximum (in scaled mouse clicks) + YLSB + +Set absolute mouse position maintenance. Resets the ikbd maintained X and Y +coordinates. +In this mode, the value of the internally maintained coordinates does NOT wrap +between 0 and large positive numbers. Excess motion below 0 is ignored. The +command sets the maximum positive value that can be attained in the scaled +coordinate system. Motion beyond that value is also ignored. + +9.5 SET MOUSE KEYCODE MOSE + + 0x0A + deltax ; distance in X clicks to return (LEFT) or (RIGHT) + deltay ; distance in Y clicks to return (UP) or (DOWN) + +Set mouse monitoring routines to return cursor motion keycodes instead of +either RELATIVE or ABSOLUTE motion records. The ikbd returns the appropriate +cursor keycode after mouse travel exceeding the user specified deltas in +either axis. When the keyboard is in key scan code mode, mouse motion will +cause the make code immediately followed by the break code. Note that this +command is not affected by the mouse motion origin. + +9..6 SET MOUSE THRESHOLD + + 0x0B + X ; x threshold in mouse ticks (positive integers) + Y ; y threshold in mouse ticks (positive integers) + +This command sets the threshold before a mouse event is generated. Note that +it does NOT affect the resolution of the data returned to the host. This +command is valid only in RELATIVE MOUSE POSITIONING mode. The thresholds +default to 1 at RESET (or power-up). + +9.7 SET MOUSE SCALE + + 0x0C + X ; horizontal mouse ticks per internel X + Y ; vertical mouse ticks per internel Y + +This command sets the scale factor for the ABSOLUTE MOUSE POSITIONING mode. +In this mode, the specified number of mouse phase changes ('clicks') must +occur before the internally maintained coordinate is changed by one +(independently scaled for each axis). Remember that the mouse position +information is available only by interrogating the ikbd in the ABSOLUTE MOUSE +POSITIONING mode unless the ikbd has been commanded to report on button press +or release (see SET MOSE BUTTON ACTION). + +9.8 INTERROGATE MOUSE POSITION + + 0x0D + Returns: + 0xF7 ; absolute mouse position header + BUTTONS + 0000dcba ; where a is right button down since last interrogation + ; b is right button up since last + ; c is left button down since last + ; d is left button up since last + XMSB ; X coordinate + XLSB + YMSB ; Y coordinate + YLSB + +The INTERROGATE MOUSE POSITION command is valid when in the ABSOLUTE MOUSE +POSITIONING mode, regardless of the setting of the MOUSE BUTTON ACTION. + +9.9 LOAD MOUSE POSITION + + 0x0E + 0x00 ; filler + XMSB ; X coordinate + XLSB ; (in scaled coordinate system) + YMSB ; Y coordinate + YLSB + +This command allows the user to preset the internally maintained absolute +mouse position. + +9.10 SET Y=0 AT BOTTOM + + 0x0F + +This command makes the origin of the Y axis to be at the bottom of the +logical coordinate system internel to the ikbd for all relative or absolute +mouse motion. This causes mouse motion toward the user to be negative in sign +and away from the user to be positive. + +9.11 SET Y=0 AT TOP + + 0x10 + +Makes the origin of the Y axis to be at the top of the logical coordinate +system within the ikbd for all relative or absolute mouse motion. (DEFAULT) +This causes mouse motion toward the user to be positive in sign and away from +the user to be negative. + +9.12 RESUME + + 0x11 + +Resume sending data to the host. Since any command received by the ikbd after +its output has been paused also causes an implicit RESUME this command can be +thought of as a NO OPERATION command. If this command is received by the ikbd +and it is not PAUSED, it is simply ignored. + +9.13 DISABLE MOUSE + + 0x12 + +All mouse event reporting is disabled (and scanning may be internally +disabled). Any valid mouse mode command resumes mouse motion monitoring. (The +valid mouse mode commands are SET RELATIVE MOUSE POSITION REPORTING, SET +ABSOLUTE MOUSE POSITIONING, and SET MOUSE KEYCODE MODE. ) +N.B. If the mouse buttons have been commanded to act like keyboard keys, this +command DOES affect their actions. + +9.14 PAUSE OUTPUT + + 0x13 + +Stop sending data to the host until another valid command is received. Key +matrix activity is still monitored and scan codes or ASCII characters enqueued +(up to the maximum supported by the microcontroller) to be sent when the host +allows the output to be resumed. If in the JOYSTICK EVENT REPORTING mode, +joystick events are also queued. +Mouse motion should be accumulated while the output is paused. If the ikbd is +in RELATIVE MOUSE POSITIONING REPORTING mode, motion is accumulated beyond the +normal threshold limits to produce the minimum number of packets necessary for +transmission when output is resumed. Pressing or releasing either mouse button +causes any accumulated motion to be immediately queued as packets, if the +mouse is in RELATIVE MOUSE POSITION REPORTING mode. +Because of the limitations of the microcontroller memory this command should +be used sparingly, and the output should not be shut of for more than +milliseconds at a time. +The output is stopped only at the end of the current 'even'. If the PAUSE +OUTPUT command is received in the middle of a multiple byte report, the packet +will still be transmitted to conclusion and then the PAUSE will take effect. +When the ikbd is in either the JOYSTICK MONITORING mode or the FIRE BUTTON +MONITORING mode, the PAUSE OUTPUT command also temporarily stops the +monitoring process (i.e. the samples are not enqueued for transmission). + +0.15 SET JOYSTICK EVENT REPORTING + + 0x14 + +Enter JOYSTICK EVENT REPORTING mode (DEFAULT). Each opening or closure of a +joystick switch or trigger causes a joystick event record to be generated. + +9.16 SET JOYSTICK INTERROGATION MODE + + 0x15 + +Disables JOYSTICK EVENT REPORTING. Host must send individual JOYSTICK +INTERROGATE commands to sense joystick state. + +9.17 JOYSTICK INTERROGATE + + 0x16 + +Return a record indicating the current state of the joysticks. This command +is valid in either the JOYSTICK EVENT REPORTING mode or the JOYSTICK +INTERROGATION MODE. + +9.18 SET JOYSTICK MONITORING + + 0x17 + rate ; time between samples in hundreths of a second + Returns: (in packets of two as long as in mode) + %000000xy ; where y is JOYSTICK1 Fire button + ; and x is JOYSTICK0 Fire button + %nnnnmmmm ; where m is JOYSTICK1 state + ; and n is JOYSTICK0 state + +Sets the ikbd to do nothing but monitor the serial command lne, maintain the +time-of-day clock, and monitor the joystick. The rate sets the interval +between joystick samples. +N.B. The user should not set the rate higher than the serial communications +channel will allow the 2 bytes packets to be transmitted. + +9.19 SET FIRE BUTTON MONITORING + + 0x18 + Returns: (as long as in mode) + %bbbbbbbb ; state of the JOYSTICK1 fire button packed + ; 8 bits per byte, the first sample if the MSB + +Set the ikbd to do nothing but monitor the serial command line, maintain the +time-of-day clock, and monitor the fire button on Joystick 1. The fire button +is scanned at a rate that causes 8 samples to be made in the time it takes for +the previous byte to be sent to the host (i.e. scan rate = 8/10 * baud rate). +The sample interval should be as constant as possible. + +9.20 SET JOYSTICK KEYCODE MODE + + 0x19 + RX ; length of time (in tenths of seconds) until + ; horizontal velocity breakpoint is reached + RY ; length of time (in tenths of seconds) until + ; vertical velocity breakpoint is reached + TX ; length (in tenths of seconds) of joystick closure + ; until horizontal cursor key is generated before RX + ; has elapsed + TY ; length (in tenths of seconds) of joystick closure + ; until vertical cursor key is generated before RY + ; has elapsed + VX ; length (in tenths of seconds) of joystick closure + ; until horizontal cursor keystokes are generated + ; after RX has elapsed + VY ; length (in tenths of seconds) of joystick closure + ; until vertical cursor keystokes are generated + ; after RY has elapsed + +In this mode, joystick 0 is scanned in a way that simulates cursor keystrokes. +On initial closure, a keystroke pair (make/break) is generated. Then up to Rn +tenths of seconds later, keystroke pairs are generated every Tn tenths of +seconds. After the Rn breakpoint is reached, keystroke pairs are generated +every Vn tenths of seconds. This provides a velocity (auto-repeat) breakpoint +feature. +Note that by setting RX and/or Ry to zero, the velocity feature can be +disabled. The values of TX and TY then become meaningless, and the generation +of cursor 'keystrokes' is set by VX and VY. + +9.21 DISABLE JOYSTICKS + + 0x1A + +Disable the generation of any joystick events (and scanning may be internally +disabled). Any valid joystick mode command resumes joystick monitoring. (The +joystick mode commands are SET JOYSTICK EVENT REPORTING, SET JOYSTICK +INTERROGATION MODE, SET JOYSTICK MONITORING, SET FIRE BUTTON MONITORING, and +SET JOYSTICK KEYCODE MODE.) + +9.22 TIME-OF-DAY CLOCK SET + + 0x1B + YY ; year (2 least significant digits) + MM ; month + DD ; day + hh ; hour + mm ; minute + ss ; second + +All time-of-day data should be sent to the ikbd in packed BCD format. +Any digit that is not a valid BCD digit should be treated as a 'don't care' +and not alter that particular field of the date or time. This permits setting +only some subfields of the time-of-day clock. + +9.23 INTERROGATE TIME-OF-DAT CLOCK + + 0x1C + Returns: + 0xFC ; time-of-day event header + YY ; year (2 least significant digits) + MM ; month + DD ; day + hh ; hour + mm ; minute + ss ; second + + All time-of-day is sent in packed BCD format. + +9.24 MEMORY LOAD + + 0x20 + ADRMSB ; address in controller + ADRLSB ; memory to be loaded + NUM ; number of bytes (0-128) + { data } + +This command permits the host to load arbitrary values into the ikbd +controller memory. The time between data bytes must be less than 20ms. + +9.25 MEMORY READ + + 0x21 + ADRMSB ; address in controller + ADRLSB ; memory to be read + Returns: + 0xF6 ; status header + 0x20 ; memory access + { data } ; 6 data bytes starting at ADR + +This comand permits the host to read from the ikbd controller memory. + +9.26 CONTROLLER EXECUTE + + 0x22 + ADRMSB ; address of subroutine in + ADRLSB ; controller memory to be called + +This command allows the host to command the execution of a subroutine in the +ikbd controller memory. + +9.27 STATUS INQUIRIES + + Status commands are formed by inclusively ORing 0x80 with the + relevant SET command. + + Example: + 0x88 (or 0x89 or 0x8A) ; request mouse mode + Returns: + 0xF6 ; status response header + mode ; 0x08 is RELATIVE + ; 0x09 is ABSOLUTE + ; 0x0A is KEYCODE + param1 ; 0 is RELATIVE + ; XMSB maximum if ABSOLUTE + ; DELTA X is KEYCODE + param2 ; 0 is RELATIVE + ; YMSB maximum if ABSOLUTE + ; DELTA Y is KEYCODE + param3 ; 0 if RELATIVE + ; or KEYCODE + ; YMSB is ABSOLUTE + param4 ; 0 if RELATIVE + ; or KEYCODE + ; YLSB is ABSOLUTE + 0 ; pad + 0 + +The STATUS INQUIRY commands request the ikbd to return either the current mode +or the parameters associated with a given command. All status reports are +padded to form 8 byte long return packets. The responses to the status +requests are designed so that the host may store them away (after stripping +off the status report header byte) and later send them back as commands to +ikbd to restore its state. The 0 pad bytes will be treated as NOPs by the +ikbd. + + Valid STATUS INQUIRY commands are: + + 0x87 mouse button action + 0x88 mouse mode + 0x89 + 0x8A + 0x8B mnouse threshold + 0x8C mouse scale + 0x8F mouse vertical coordinates + 0x90 ( returns 0x0F Y=0 at bottom + 0x10 Y=0 at top ) + 0x92 mouse enable/disable + ( returns 0x00 enabled) + 0x12 disabled ) + 0x94 joystick mode + 0x95 + 0x96 + 0x9A joystick enable/disable + ( returns 0x00 enabled + 0x1A disabled ) + +It is the (host) programmer's responsibility to have only one unanswered +inquiry in process at a time. +STATUS INQUIRY commands are not valid if the ikbd is in JOYSTICK MONITORING +mode or FIRE BUTTON MONITORING mode. + + +10. SCAN CODES + +The key scan codes return by the ikbd are chosen to simplify the +implementaion of GSX. + +GSX Standard Keyboard Mapping. + +Hex Keytop +01 Esc +02 1 +03 2 +04 3 +05 4 +06 5 +07 6 +08 7 +09 8 +0A 9 +0B 0 +0C - +0D == +0E BS +0F TAB +10 Q +11 W +12 E +13 R +14 T +15 Y +16 U +17 I +18 O +19 P +1A [ +1B ] +1C RET +1D CTRL +1E A +1F S +20 D +21 F +22 G +23 H +24 J +25 K +26 L +27 ; +28 ' +29 ` +2A (LEFT) SHIFT +2B \ +2C Z +2D X +2E C +2F V +30 B +31 N +32 M +33 , +34 . +35 / +36 (RIGHT) SHIFT +37 { NOT USED } +38 ALT +39 SPACE BAR +3A CAPS LOCK +3B F1 +3C F2 +3D F3 +3E F4 +3F F5 +40 F6 +41 F7 +42 F8 +43 F9 +44 F10 +45 { NOT USED } +46 { NOT USED } +47 HOME +48 UP ARROW +49 { NOT USED } +4A KEYPAD - +4B LEFT ARROW +4C { NOT USED } +4D RIGHT ARROW +4E KEYPAD + +4F { NOT USED } +50 DOWN ARROW +51 { NOT USED } +52 INSERT +53 DEL +54 { NOT USED } +5F { NOT USED } +60 ISO KEY +61 UNDO +62 HELP +63 KEYPAD ( +64 KEYPAD / +65 KEYPAD * +66 KEYPAD * +67 KEYPAD 7 +68 KEYPAD 8 +69 KEYPAD 9 +6A KEYPAD 4 +6B KEYPAD 5 +6C KEYPAD 6 +6D KEYPAD 1 +6E KEYPAD 2 +6F KEYPAD 3 +70 KEYPAD 0 +71 KEYPAD . +72 KEYPAD ENTER diff --git a/Documentation/input/cd32.txt b/Documentation/input/cd32.txt new file mode 100644 index 00000000000..a003d9b41ec --- /dev/null +++ b/Documentation/input/cd32.txt @@ -0,0 +1,19 @@ +I have written a small patch that let's me use my Amiga CD32 +joypad connected to the parallel port. Thought I'd share it with you so +you can add it to the list of supported joysticks (hopefully someone will +find it useful). + +It needs the following wiring: + +CD32 pad | Parallel port +---------------------------- +1 (Up) | 2 (D0) +2 (Down) | 3 (D1) +3 (Left) | 4 (D2) +4 (Right) | 5 (D3) +5 (Fire3) | 14 (AUTOFD) +6 (Fire1) | 17 (SELIN) +7 (+5V) | 1 (STROBE) +8 (Gnd) | 18 (Gnd) +9 (Fire2) | 7 (D5) + diff --git a/Documentation/input/cs461x.txt b/Documentation/input/cs461x.txt new file mode 100644 index 00000000000..6181747a14d --- /dev/null +++ b/Documentation/input/cs461x.txt @@ -0,0 +1,45 @@ +Preface. + +This is a new low-level driver to support analog joystick attached to +Crystal SoundFusion CS4610/CS4612/CS4615. This code is based upon +Vortex/Solo drivers as an example of decoration style, and ALSA +0.5.8a kernel drivers as an chipset documentation and samples. + +This version does not have cooked mode support; the basic code +is present here, but have not tested completely. The button analysis +is completed in this mode, but the axis movement is not. + +Raw mode works fine with analog joystick front-end driver and cs461x +driver as a backend. I've tested this driver with CS4610, 4-axis and +4-button joystick; I mean the jstest utility. Also I've tried to +play in xracer game using joystick, and the result is better than +keyboard only mode. + +The sensitivity and calibrate quality have not been tested; the two +reasons are performed: the same hardware cannot work under Win95 (blue +screen in VJOYD); I have no documentation on my chip; and the existing +behavior in my case was not raised the requirement of joystick calibration. +So the driver have no code to perform hardware related calibration. + +The patch contains minor changes of Config.in and Makefile files. All +needed code have been moved to one separate file cs461x.c like ns558.c +This driver have the basic support for PCI devices only; there is no +ISA or PnP ISA cards supported. AFAIK the ns558 have support for Crystal +ISA and PnP ISA series. + +The driver works witn ALSA drivers simultaneously. For exmple, the xracer +uses joystick as input device and PCM device as sound output in one time. +There are no sound or input collisions detected. The source code have +comments about them; but I've found the joystick can be initialized +separately of ALSA modules. So, you canm use only one joystick driver +without ALSA drivers. The ALSA drivers are not needed to compile or +run this driver. + +There are no debug information print have been placed in source, and no +specific options required to work this driver. The found chipset parameters +are printed via printk(KERN_INFO "..."), see the /var/log/messages to +inspect cs461x: prefixed messages to determine possible card detection +errors. + +Regards, +Viktor diff --git a/Documentation/input/ff.txt b/Documentation/input/ff.txt new file mode 100644 index 00000000000..efa7dd6751f --- /dev/null +++ b/Documentation/input/ff.txt @@ -0,0 +1,227 @@ +Force feedback for Linux. +By Johann Deneux on 2001/04/22. +You may redistribute this file. Please remember to include shape.fig and +interactive.fig as well. +---------------------------------------------------------------------------- + +0. Introduction +~~~~~~~~~~~~~~~ +This document describes how to use force feedback devices under Linux. The +goal is not to support these devices as if they were simple input-only devices +(as it is already the case), but to really enable the rendering of force +effects. +At the moment, only I-Force devices are supported, and not officially. That +means I had to find out how the protocol works on my own. Of course, the +information I managed to grasp is far from being complete, and I can not +guarranty that this driver will work for you. +This document only describes the force feedback part of the driver for I-Force +devices. Please read joystick.txt before reading further this document. + +2. Instructions to the user +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Here are instructions on how to compile and use the driver. In fact, this +driver is the normal iforce, input and evdev drivers written by Vojtech +Pavlik, plus additions to support force feedback. + +Before you start, let me WARN you that some devices shake violently during the +initialisation phase. This happens for example with my "AVB Top Shot Pegasus". +To stop this annoying behaviour, move you joystick to its limits. Anyway, you +should keep a hand on your device, in order to avoid it to brake down if +something goes wrong. + +At the kernel's compilation: + - Enable IForce/Serial + - Enable Event interface + +Compile the modules, install them. + +You also need inputattach. + +You then need to insert the modules into the following order: +% modprobe joydev +% modprobe serport # Only for serial +% modprobe iforce +% modprobe evdev +% ./inputattach -ifor $2 & # Only for serial +If you are using USB, you don't need the inputattach step. + +Please check that you have all the /dev/input entries needed: +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 + +mknod input/event0 c 13 64 +mknod input/event1 c 13 65 +mknod input/event2 c 13 66 +mknod input/event3 c 13 67 + +2.1 Does it work ? +~~~~~~~~~~~~~~~~~~ +There is an utility called fftest that will allow you to test the driver. +% fftest /dev/input/eventXX + +3. Instructions to the developper +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + All interactions are done using the event API. That is, you can use ioctl() +and write() on /dev/input/eventXX. + This information is subject to change. + +3.1 Querying device capabilities +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +#include +#include + +unsigned long features[1 + FF_MAX/sizeof(unsigned long)]; +int ioctl(int file_descriptor, int request, unsigned long *features); + +"request" must be EVIOCGBIT(EV_FF, size of features array in bytes ) + +Returns the features supported by the device. features is a bitfield with the +following bits: +- FF_X has an X axis (usually joysticks) +- FF_Y has an Y axis (usually joysticks) +- FF_WHEEL has a wheel (usually sterring wheels) +- FF_CONSTANT can render constant force effects +- FF_PERIODIC can render periodic effects (sine, triangle, square...) +- FF_RAMP can render ramp effects +- FF_SPRING can simulate the presence of a spring +- FF_FRICTION can simulate friction +- FF_DAMPER can simulate damper effects +- FF_RUMBLE rumble effects (normally the only effect supported by rumble + pads) +- FF_INERTIA can simulate inertia + + +int ioctl(int fd, EVIOCGEFFECTS, int *n); + +Returns the number of effects the device can keep in its memory. + +3.2 Uploading effects to the device +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +#include +#include + +int ioctl(int file_descriptor, int request, struct ff_effect *effect); + +"request" must be EVIOCSFF. + +"effect" points to a structure describing the effect to upload. The effect is +uploaded, but not played. +The content of effect may be modified. In particular, its field "id" is set +to the unique id assigned by the driver. This data is required for performing +some operations (removing an effect, controlling the playback). +This if field must be set to -1 by the user in order to tell the driver to +allocate a new effect. +See for a description of the ff_effect stuct. You should also +find help in a few sketches, contained in files shape.fig and interactive.fig. +You need xfig to visualize these files. + +3.3 Removing an effect from the device +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +int ioctl(int fd, EVIOCRMFF, effect.id); + +This makes room for new effects in the device's memory. Please note this won't +stop the effect if it was playing. + +3.4 Controlling the playback of effects +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Control of playing is done with write(). Below is an example: + +#include +#include + + struct input_event play; + struct input_event stop; + struct ff_effect effect; + int fd; +... + fd = open("/dev/input/eventXX", O_RDWR); +... + /* Play three times */ + play.type = EV_FF; + play.code = effect.id; + play.value = 3; + + write(fd, (const void*) &play, sizeof(play)); +... + /* Stop an effect */ + stop.type = EV_FF; + stop.code = effect.id; + stop.value = 0; + + write(fd, (const void*) &play, sizeof(stop)); + +3.5 Setting the gain +~~~~~~~~~~~~~~~~~~~~ +Not all devices have the same strength. Therefore, users should set a gain +factor depending on how strong they want effects to be. This setting is +persistent across access to the driver, so you should not care about it if +you are writing games, as another utility probably already set this for you. + +/* Set the gain of the device +int gain; /* between 0 and 100 */ +struct input_event ie; /* structure used to communicate with the driver */ + +ie.type = EV_FF; +ie.code = FF_GAIN; +ie.value = 0xFFFFUL * gain / 100; + +if (write(fd, &ie, sizeof(ie)) == -1) + perror("set gain"); + +3.6 Enabling/Disabling autocenter +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The autocenter feature quite disturbs the rendering of effects in my opinion, +and I think it should be an effect, which computation depends on the game +type. But you can enable it if you want. + +int autocenter; /* between 0 and 100 */ +struct input_event ie; + +ie.type = EV_FF; +ie.code = FF_AUTOCENTER; +ie.value = 0xFFFFUL * autocenter / 100; + +if (write(fd, &ie, sizeof(ie)) == -1) + perror("set auto-center"); + +A value of 0 means "no auto-center". + +3.7 Dynamic update of an effect +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Proceed as if you wanted to upload a new effect, except that instead of +setting the id field to -1, you set it to the wanted effect id. +Normally, the effect is not stopped and restarted. However, depending on the +type of device, not all parameters can be dynamically updated. For example, +the direction of an effect cannot be updated with iforce devices. In this +case, the driver stops the effect, up-load it, and restart it. + + +3.8 Information about the status of effects +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Every time the status of an effect is changed, an event is sent. The values +and meanings of the fields of the event are as follows: +struct input_event { +/* When the status of the effect changed */ + struct timeval time; + +/* Set to EV_FF_STATUS */ + unsigned short type; + +/* Contains the id of the effect */ + unsigned short code; + +/* Indicates the status */ + unsigned int value; +}; + +FF_STATUS_STOPPED The effect stopped playing +FF_STATUS_PLAYING The effect started to play diff --git a/Documentation/input/gameport-programming.txt b/Documentation/input/gameport-programming.txt new file mode 100644 index 00000000000..1ba3d322e0a --- /dev/null +++ b/Documentation/input/gameport-programming.txt @@ -0,0 +1,189 @@ +$Id: gameport-programming.txt,v 1.3 2001/04/24 13:51:37 vojtech Exp $ + +Programming gameport drivers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. A basic classic gameport +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If the gameport doesn't provide more than the inb()/outb() functionality, +the code needed to register it with the joystick drivers is simple: + + struct gameport gameport; + + gameport.io = MY_IO_ADDRESS; + gameport_register_port(&gameport); + +Make sure struct gameport is initialized to 0 in all other fields. The +gameport generic code will take care of the rest. + +If your hardware supports more than one io address, and your driver can +choose which one program the hardware to, starting from the more exotic +addresses is preferred, because the likelyhood of clashing with the standard +0x201 address is smaller. + +Eg. if your driver supports addresses 0x200, 0x208, 0x210 and 0x218, then +0x218 would be the address of first choice. + +If your hardware supports a gameport address that is not mapped to ISA io +space (is above 0x1000), use that one, and don't map the ISA mirror. + +Also, always request_region() on the whole io space occupied by the +gameport. Although only one ioport is really used, the gameport usually +occupies from one to sixteen addresses in the io space. + +Please also consider enabling the gameport on the card in the ->open() +callback if the io is mapped to ISA space - this way it'll occupy the io +space only when something really is using it. Disable it again in the +->close() callback. You also can select the io address in the ->open() +callback, so that it doesn't fail if some of the possible addresses are +already occupied by other gameports. + +2. Memory mapped gameport +~~~~~~~~~~~~~~~~~~~~~~~~~ + +When a gameport can be accessed through MMIO, this way is preferred, because +it is faster, allowing more reads per second. Registering such a gameport +isn't as easy as a basic IO one, but not so much complex: + + struct gameport gameport; + + void my_trigger(struct gameport *gameport) + { + my_mmio = 0xff; + } + + unsigned char my_read(struct gameport *gameport) + { + return my_mmio; + } + + gameport.read = my_read; + gameport.trigger = my_trigger; + gameport_register_port(&gameport); + +3. Cooked mode gameport +~~~~~~~~~~~~~~~~~~~~~~~ + +There are gameports that can report the axis values as numbers, that means +the driver doesn't have to measure them the old way - an ADC is built into +the gameport. To register a cooked gameport: + + struct gameport gameport; + + int my_cooked_read(struct gameport *gameport, int *axes, int *buttons) + { + int i; + + for (i = 0; i < 4; i++) + axes[i] = my_mmio[i]; + buttons[i] = my_mmio[4]; + } + + int my_open(struct gameport *gameport, int mode) + { + return -(mode != GAMEPORT_MODE_COOKED); + } + + gameport.cooked_read = my_cooked_read; + gameport.open = my_open; + gameport.fuzz = 8; + gameport_register_port(&gameport); + +The only confusing thing here is the fuzz value. Best determined by +experimentation, it is the amount of noise in the ADC data. Perfect +gameports can set this to zero, most common have fuzz between 8 and 32. +See analog.c and input.c for handling of fuzz - the fuzz value determines +the size of a gaussian filter window that is used to eliminate the noise +in the data. + +4. More complex gameports +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Gameports can support both raw and cooked modes. In that case combine either +examples 1+2 or 1+3. Gameports can support internal calibration - see below, +and also lightning.c and analog.c on how that works. If your driver supports +more than one gameport instance simultaneously, use the ->private member of +the gameport struct to point to your data. + +5. Unregistering a gameport +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Simple: + +gameport_unregister_port(&gameport); + +6. The gameport structure +~~~~~~~~~~~~~~~~~~~~~~~~~ + +struct gameport { + + void *private; + +A private pointer for free use in the gameport driver. (Not the joystick +driver!) + + int number; + +Number assigned to the gameport when registered. Informational purpose only. + + int io; + +I/O address for use with raw mode. You have to either set this, or ->read() +to some value if your gameport supports raw mode. + + int speed; + +Raw mode speed of the gameport reads in thousands of reads per second. + + int fuzz; + +If the gameport supports cooked mode, this should be set to a value that +represents the amount of noise in the data. See section 3. + + void (*trigger)(struct gameport *); + +Trigger. This function should trigger the ns558 oneshots. If set to NULL, +outb(0xff, io) will be used. + + unsigned char (*read)(struct gameport *); + +Read the buttons and ns558 oneshot bits. If set to NULL, inb(io) will be +used instead. + + int (*cooked_read)(struct gameport *, int *axes, int *buttons); + +If the gameport supports cooked mode, it should point this to its cooked +read function. It should fill axes[0..3] with four values of the joystick axes +and buttons[0] with four bits representing the buttons. + + int (*calibrate)(struct gameport *, int *axes, int *max); + +Function for calibrating the ADC hardware. When called, axes[0..3] should be +pre-filled by cooked data by the caller, max[0..3] should be pre-filled with +expected maximums for each axis. The calibrate() function should set the +sensitivity of the ADC hardware so that the maximums fit in its range and +recompute the axes[] values to match the new sensitivity or re-read them from +the hardware so that they give valid values. + + int (*open)(struct gameport *, int mode); + +Open() serves two purposes. First a driver either opens the port in raw or +in cooked mode, the open() callback can decide which modes are supported. +Second, resource allocation can happen here. The port can also be enabled +here. Prior to this call, other fields of the gameport struct (namely the io +member) need not to be valid. + + void (*close)(struct gameport *); + +Close() should free the resources allocated by open, possibly disabling the +gameport. + + struct gameport_dev *dev; + struct gameport *next; + +For internal use by the gameport layer. + +}; + +Enjoy! diff --git a/Documentation/input/iforce-protocol.txt b/Documentation/input/iforce-protocol.txt new file mode 100644 index 00000000000..95df4ca70e7 --- /dev/null +++ b/Documentation/input/iforce-protocol.txt @@ -0,0 +1,254 @@ +** Introduction +This document describes what I managed to discover about the protocol used to +specify force effects to I-Force 2.0 devices. None of this information comes +from Immerse. That's why you should not trust what is written in this +document. This document is intended to help understanding the protocol. +This is not a reference. Comments and corrections are welcome. To contact me, +send an email to: deneux@ifrance.com + +** WARNING ** +I may not be held responsible for any dammage or harm caused if you try to +send data to your I-Force device based on what you read in this document. + +** Preliminary Notes: +All values are hexadecimal with big-endian encoding (msb on the left). Beware, +values inside packets are encoded using little-endian. Bytes whose roles are +unknown are marked ??? Information that needs deeper inspection is marked (?) + +** General form of a packet ** +This is how packets look when the device uses the rs232 to communicate. +2B OP LEN DATA CS +CS is the checksum. It is equal to the exclusive or of all bytes. + +When using USB: +OP DATA +The 2B, LEN and CS fields have disappeared, probably because USB handles frames and +data corruption is handled or unsignificant. + +First, I describe effects that are sent by the device to the computer + +** Device input state +This packet is used to indicate the state of each button and the value of each +axis +OP= 01 for a joystick, 03 for a wheel +LEN= Varies from device to device +00 X-Axis lsb +01 X-Axis msb +02 Y-Axis lsb, or gas pedal for a wheel +03 Y-Axis msb, or brake pedal for a wheel +04 Throttle +05 Buttons +06 Lower 4 bits: Buttons + Upper 4 bits: Hat +07 Rudder + +** Device effects states +OP= 02 +LEN= Varies +00 ? Bit 1 (Value 2) is the value of the deadman switch +01 Bit 8 is set if the effect is playing. Bits 0 to 7 are the effect id. +02 ?? +03 Address of parameter block changed (lsb) +04 Address of parameter block changed (msb) +05 Address of second parameter block changed (lsb) +... depending on the number of parameter blocks updated + +** Force effect ** +OP= 01 +LEN= 0e +00 Channel (when playing several effects at the same time, each must be assigned a channel) +01 Wave form + Val 00 Constant + Val 20 Square + Val 21 Triangle + Val 22 Sine + Val 23 Sawtooth up + Val 24 Sawtooth down + Val 40 Spring (Force = f(pos)) + Val 41 Friction (Force = f(velocity)) and Inertia (Force = f(acceleration)) + + +02 Axes affected and trigger + Bits 4-7: Val 2 = effect along one axis. Byte 05 indicates direction + Val 4 = X axis only. Byte 05 must contain 5a + Val 8 = Y axis only. Byte 05 must contain b4 + Val c = X and Y axes. Bytes 05 must contain 60 + Bits 0-3: Val 0 = No trigger + Val x+1 = Button x triggers the effect + When the whole byte is 0, cancel the previously set trigger + +03-04 Duration of effect (little endian encoding, in ms) + +05 Direction of effect, if applicable. Else, see 02 for value to assign. + +06-07 Minimum time between triggering. + +08-09 Address of periodicity or magnitude parameters +0a-0b Address of attack and fade parameters, or ffff if none. +*or* +08-09 Address of interactive parameters for X-axis, or ffff if not applicable +0a-0b Address of interactive parameters for Y-axis, or ffff if not applicable + +0c-0d Delay before execution of effect (little endian encoding, in ms) + + +** Time based parameters ** + +*** Attack and fade *** +OP= 02 +LEN= 08 +00-01 Address where to store the parameteres +02-03 Duration of attack (little endian encoding, in ms) +04 Level at end of attack. Signed byte. +05-06 Duration of fade. +07 Level at end of fade. + +*** Magnitude *** +OP= 03 +LEN= 03 +00-01 Address +02 Level. Signed byte. + +*** Periodicity *** +OP= 04 +LEN= 07 +00-01 Address +02 Magnitude. Signed byte. +03 Offset. Signed byte. +04 Phase. Val 00 = 0 deg, Val 40 = 90 degs. +05-06 Period (little endian encoding, in ms) + +** Interactive parameters ** +OP= 05 +LEN= 0a +00-01 Address +02 Positive Coeff +03 Negative Coeff +04+05 Offset (center) +06+07 Dead band (Val 01F4 = 5000 (decimal)) +08 Positive saturation (Val 0a = 1000 (decimal) Val 64 = 10000 (decimal)) +09 Negative saturation + +The encoding is a bit funny here: For coeffs, these are signed values. The +maximum value is 64 (100 decimal), the min is 9c. +For the offset, the minimum value is FE0C, the maximum value is 01F4. +For the deadband, the minimum value is 0, the max is 03E8. + +** Controls ** +OP= 41 +LEN= 03 +00 Channel +01 Start/Stop + Val 00: Stop + Val 01: Start and play once. + Val 41: Start and play n times (See byte 02 below) +02 Number of iterations n. + +** Init ** + +*** Querying features *** +OP= ff +Query command. Length varies according to the query type. +The general format of this packet is: +ff 01 QUERY [INDEX] CHECKSUM +reponses are of the same form: +FF LEN QUERY VALUE_QUERIED CHECKSUM2 +where LEN = 1 + length(VALUE_QUERIED) + +**** Query ram size **** +QUERY = 42 ('B'uffer size) +The device should reply with the same packet plus two additionnal bytes +containing the size of the memory: +ff 03 42 03 e8 CS would mean that the device has 1000 bytes of ram available. + +**** Query number of effects **** +QUERY = 4e ('N'umber of effects) +The device should respond by sending the number of effects that can be played +at the same time (one byte) +ff 02 4e 14 CS would stand for 20 effects. + +**** Vendor's id **** +QUERY = 4d ('M'anufacturer) +Query the vendors'id (2 bytes) + +**** Product id ***** +QUERY = 50 ('P'roduct) +Query the product id (2 bytes) + +**** Open device **** +QUERY = 4f ('O'pen) +No data returned. + +**** Close device ***** +QUERY = 43 ('C')lose +No data returned. + +**** Query effect **** +QUERY = 45 ('E') +Send effect type. +Returns nonzero if supported (2 bytes) + +**** Firmware Version **** +QUERY = 56 ('V'ersion) +Sends back 3 bytes - major, minor, subminor + +*** Initialisation of the device *** + +**** Set Control **** +!!! Device dependent, can be different on different models !!! +OP= 40 [] +LEN= 2 or 3 +00 Idx + Idx 00 Set dead zone (0..2048) + Idx 01 Ignore Deadman sensor (0..1) + Idx 02 Enable comm watchdog (0..1) + Idx 03 Set the strength of the spring (0..100) + Idx 04 Enable or disable the spring (0/1) + Idx 05 Set axis saturation threshold (0..2048) + +**** Set Effect State **** +OP= 42 +LEN= 1 +00 State + Bit 3 Pause force feedback + Bit 2 Enable force feedback + Bit 0 Stop all effects + +**** Set overall gain **** +OP= 43 +LEN= 1 +00 Gain + Val 00 = 0% + Val 40 = 50% + Val 80 = 100% + +** Parameter memory ** + +Each device has a certain amount of memory to store parameters of effects. +The amount of RAM may vary, I encountered values from 200 to 1000 bytes. Below +is the amount of memory apparently needed for every set of parameters: + - period : 0c + - magnitude : 02 + - attack and fade : 0e + - interactive : 08 + +** Appendix: How to study the protocol ? ** + +1. Generate effects using the force editor provided with the DirectX SDK, or use Immersion Studio (freely available at their web site in the developer section: www.immersion.com) +2. Start a soft spying RS232 or USB (depending on where you connected your joystick/wheel). I used ComPortSpy from fCoder (alpha version!) +3. Play the effect, and watch what happens on the spy screen. + +A few words about ComPortSpy: +At first glance, this soft seems, hum, well... buggy. In fact, data appear with a few seconds latency. Personnaly, I restart it every time I play an effect. +Remember it's free (as in free beer) and alpha! + +** URLS ** +Check www.immerse.com for Immersion Studio, and www.fcoder.com for ComPortSpy. + +** Author of this document ** +Johann Deneux +Home page at http://www.esil.univ-mrs.fr/~jdeneux/projects/ff/ + +Additions by Vojtech Pavlik. + +I-Force is trademark of Immersion Corp. diff --git a/Documentation/input/input-programming.txt b/Documentation/input/input-programming.txt new file mode 100644 index 00000000000..180e0689676 --- /dev/null +++ b/Documentation/input/input-programming.txt @@ -0,0 +1,281 @@ +$Id: input-programming.txt,v 1.4 2001/05/04 09:47:14 vojtech Exp $ + +Programming input drivers +~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Creating an input device driver +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1.0 The simplest example +~~~~~~~~~~~~~~~~~~~~~~~~ + +Here comes a very simple example of an input device driver. The device has +just one button and the button is accessible at i/o port BUTTON_PORT. When +pressed or released a BUTTON_IRQ happens. The driver could look like: + +#include +#include +#include + +#include +#include + +static void button_interrupt(int irq, void *dummy, struct pt_regs *fp) +{ + input_report_key(&button_dev, BTN_1, inb(BUTTON_PORT) & 1); + input_sync(&button_dev); +} + +static int __init button_init(void) +{ + if (request_irq(BUTTON_IRQ, button_interrupt, 0, "button", NULL)) { + printk(KERN_ERR "button.c: Can't allocate irq %d\n", button_irq); + return -EBUSY; + } + + button_dev.evbit[0] = BIT(EV_KEY); + button_dev.keybit[LONG(BTN_0)] = BIT(BTN_0); + + input_register_device(&button_dev); +} + +static void __exit button_exit(void) +{ + input_unregister_device(&button_dev); + free_irq(BUTTON_IRQ, button_interrupt); +} + +module_init(button_init); +module_exit(button_exit); + +1.1 What the example does +~~~~~~~~~~~~~~~~~~~~~~~~~ + +First it has to include the file, which interfaces to the +input subsystem. This provides all the definitions needed. + +In the _init function, which is called either upon module load or when +booting the kernel, it grabs the required resources (it should also check +for the presence of the device). + +Then it sets the input bitfields. This way the device driver tells the other +parts of the input systems what it is - what events can be generated or +accepted by this input device. Our example device can only generate EV_KEY type +events, and from those only BTN_0 event code. Thus we only set these two +bits. We could have used + + set_bit(EV_KEY, button_dev.evbit); + set_bit(BTN_0, button_dev.keybit); + +as well, but with more than single bits the first approach tends to be +shorter. + +Then the example driver registers the input device structure by calling + + input_register_device(&button_dev); + +This adds the button_dev structure to linked lists of the input driver and +calls device handler modules _connect functions to tell them a new input +device has appeared. Because the _connect functions may call kmalloc(, +GFP_KERNEL), which can sleep, input_register_device() must not be called +from an interrupt or with a spinlock held. + +While in use, the only used function of the driver is + + button_interrupt() + +which upon every interrupt from the button checks its state and reports it +via the + + input_report_key() + +call to the input system. There is no need to check whether the interrupt +routine isn't reporting two same value events (press, press for example) to +the input system, because the input_report_* functions check that +themselves. + +Then there is the + + input_sync() + +call to tell those who receive the events that we've sent a complete report. +This doesn't seem important in the one button case, but is quite important +for for example mouse movement, where you don't want the X and Y values +to be interpreted separately, because that'd result in a different movement. + +1.2 dev->open() and dev->close() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In case the driver has to repeatedly poll the device, because it doesn't +have an interrupt coming from it and the polling is too expensive to be done +all the time, or if the device uses a valuable resource (eg. interrupt), it +can use the open and close callback to know when it can stop polling or +release the interrupt and when it must resume polling or grab the interrupt +again. To do that, we would add this to our example driver: + +int button_used = 0; + +static int button_open(struct input_dev *dev) +{ + if (button_used++) + return 0; + + if (request_irq(BUTTON_IRQ, button_interrupt, 0, "button", NULL)) { + printk(KERN_ERR "button.c: Can't allocate irq %d\n", button_irq); + button_used--; + return -EBUSY; + } + + return 0; +} + +static void button_close(struct input_dev *dev) +{ + if (!--button_used) + free_irq(IRQ_AMIGA_VERTB, button_interrupt); +} + +static int __init button_init(void) +{ + ... + button_dev.open = button_open; + button_dev.close = button_close; + ... +} + +Note the button_used variable - we have to track how many times the open +function was called to know when exactly our device stops being used. + +The open() callback should return a 0 in case of success or any nonzero value +in case of failure. The close() callback (which is void) must always succeed. + +1.3 Basic event types +~~~~~~~~~~~~~~~~~~~~~ + +The most simple event type is EV_KEY, which is used for keys and buttons. +It's reported to the input system via: + + input_report_key(struct input_dev *dev, int code, int value) + +See linux/input.h for the allowable values of code (from 0 to KEY_MAX). +Value is interpreted as a truth value, ie any nonzero value means key +pressed, zero value means key released. The input code generates events only +in case the value is different from before. + +In addition to EV_KEY, there are two more basic event types: EV_REL and +EV_ABS. They are used for relative and absolute values supplied by the +device. A relative value may be for example a mouse movement in the X axis. +The mouse reports it as a relative difference from the last position, +because it doesn't have any absolute coordinate system to work in. Absolute +events are namely for joysticks and digitizers - devices that do work in an +absolute coordinate systems. + +Having the device report EV_REL buttons is as simple as with EV_KEY, simply +set the corresponding bits and call the + + input_report_rel(struct input_dev *dev, int code, int value) + +function. Events are generated only for nonzero value. + +However EV_ABS requires a little special care. Before calling +input_register_device, you have to fill additional fields in the input_dev +struct for each absolute axis your device has. If our button device had also +the ABS_X axis: + + button_dev.absmin[ABS_X] = 0; + button_dev.absmax[ABS_X] = 255; + button_dev.absfuzz[ABS_X] = 4; + button_dev.absflat[ABS_X] = 8; + +This setting would be appropriate for a joystick X axis, with the minimum of +0, maximum of 255 (which the joystick *must* be able to reach, no problem if +it sometimes reports more, but it must be able to always reach the min and +max values), with noise in the data up to +- 4, and with a center flat +position of size 8. + +If you don't need absfuzz and absflat, you can set them to zero, which mean +that the thing is precise and always returns to exactly the center position +(if it has any). + +1.4 The void *private field +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This field in the input structure can be used to point to any private data +structures in the input device driver, in case the driver handles more than +one device. You'll need it in the open and close callbacks. + +1.5 NBITS(), LONG(), BIT() +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These three macros from input.h help some bitfield computations: + + NBITS(x) - returns the length of a bitfield array in longs for x bits + LONG(x) - returns the index in the array in longs for bit x + BIT(x) - returns the index in a long for bit x + +1.6 The number, id* and name fields +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The dev->number is assigned by the input system to the input device when it +is registered. It has no use except for identifying the device to the user +in system messages. + +The dev->name should be set before registering the input device by the input +device driver. It's a string like 'Generic button device' containing a +user friendly name of the device. + +The id* fields contain the bus ID (PCI, USB, ...), vendor ID and device ID +of the device. The bus IDs are defined in input.h. The vendor and device ids +are defined in pci_ids.h, usb_ids.h and similar include files. These fields +should be set by the input device driver before registering it. + +The idtype field can be used for specific information for the input device +driver. + +The id and name fields can be passed to userland via the evdev interface. + +1.7 The keycode, keycodemax, keycodesize fields +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These two fields will be used for any input devices that report their data +as scancodes. If not all scancodes can be known by autodetection, they may +need to be set by userland utilities. The keycode array then is an array +used to map from scancodes to input system keycodes. The keycode max will +contain the size of the array and keycodesize the size of each entry in it +(in bytes). + +1.8 Key autorepeat +~~~~~~~~~~~~~~~~~~ + +... is simple. It is handled by the input.c module. Hardware autorepeat is +not used, because it's not present in many devices and even where it is +present, it is broken sometimes (at keyboards: Toshiba notebooks). To enable +autorepeat for your device, just set EV_REP in dev->evbit. All will be +handled by the input system. + +1.9 Other event types, handling output events +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The other event types up to now are: + +EV_LED - used for the keyboard LEDs. +EV_SND - used for keyboard beeps. + +They are very similar to for example key events, but they go in the other +direction - from the system to the input device driver. If your input device +driver can handle these events, it has to set the respective bits in evbit, +*and* also the callback routine: + + button_dev.event = button_event; + +int button_event(struct input_dev *dev, unsigned int type, unsigned int code, int value); +{ + if (type == EV_SND && code == SND_BELL) { + outb(value, BUTTON_BELL); + return 0; + } + return -1; +} + +This callback routine can be called from an interrupt or a BH (although that +isn't a rule), and thus must not sleep, and must not take too long to finish. diff --git a/Documentation/input/input.txt b/Documentation/input/input.txt new file mode 100644 index 00000000000..47137e75fdb --- /dev/null +++ b/Documentation/input/input.txt @@ -0,0 +1,312 @@ + Linux Input drivers v1.0 + (c) 1999-2001 Vojtech Pavlik + Sponsored by SuSE + $Id: input.txt,v 1.8 2002/05/29 03:15:01 bradleym Exp $ +---------------------------------------------------------------------------- + +0. Disclaimer +~~~~~~~~~~~~~ + This program is free software; you can redistribute it and/or modify it +under the terms of the GNU General Public License as published by the Free +Software Foundation; either version 2 of the License, or (at your option) +any later version. + + This program is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for +more details. + + You should have received a copy of the GNU General Public License along +with this program; if not, write to the Free Software Foundation, Inc., 59 +Temple Place, Suite 330, Boston, MA 02111-1307 USA + + Should you need to contact me, the author, you can do so either by e-mail +- mail your message to , or by paper mail: Vojtech Pavlik, +Simunkova 1594, Prague 8, 182 00 Czech Republic + + For your convenience, the GNU General Public License version 2 is included +in the package: See the file COPYING. + +1. Introduction +~~~~~~~~~~~~~~~ + This is a collection of drivers that is designed to support all input +devices under Linux. While it is currently used only on for USB input +devices, future use (say 2.5/2.6) is expected to expand to replace +most of the existing input system, which is why it lives in +drivers/input/ instead of drivers/usb/. + + The centre of the input drivers is the input module, which must be +loaded before any other of the input modules - it serves as a way of +communication between two groups of modules: + +1.1 Device drivers +~~~~~~~~~~~~~~~~~~ + These modules talk to the hardware (for example via USB), and provide +events (keystrokes, mouse movements) to the input module. + +1.2 Event handlers +~~~~~~~~~~~~~~~~~~ + These modules get events from input and pass them where needed via +various interfaces - keystrokes to the kernel, mouse movements via a +simulated PS/2 interface to GPM and X and so on. + +2. Simple Usage +~~~~~~~~~~~~~~~ + For the most usual configuration, with one USB mouse and one USB keyboard, +you'll have to load the following modules (or have them built in to the +kernel): + + input + mousedev + keybdev + usbcore + uhci_hcd or ohci_hcd or ehci_hcd + usbhid + + After this, the USB keyboard will work straight away, and the USB mouse +will be available as a character device on major 13, minor 63: + + crw-r--r-- 1 root root 13, 63 Mar 28 22:45 mice + + This device has to be created, unless you use devfs, in which case it's +created automatically. The commands to do create it by hand are: + + cd /dev + mkdir input + mknod input/mice c 13 63 + + After that you have to point GPM (the textmode mouse cut&paste tool) and +XFree to this device to use it - GPM should be called like: + + gpm -t ps2 -m /dev/input/mice + + And in X: + + Section "Pointer" + Protocol "ImPS/2" + Device "/dev/input/mice" + ZAxisMapping 4 5 + EndSection + + When you do all of the above, you can use your USB mouse and keyboard. + +3. Detailed Description +~~~~~~~~~~~~~~~~~~~~~~~ +3.1 Device drivers +~~~~~~~~~~~~~~~~~~ + Device drivers are the modules that generate events. The events are +however not useful without being handled, so you also will need to use some +of the modules from section 3.2. + +3.1.1 usbhid +~~~~~~~~~~~~ + usbhid is the largest and most complex driver of the whole suite. It +handles all HID devices, and because there is a very wide variety of them, +and because the USB HID specification isn't simple, it needs to be this big. + + Currently, it handles USB mice, joysticks, gamepads, steering wheels +keyboards, trackballs and digitizers. + + However, USB uses HID also for monitor controls, speaker controls, UPSs, +LCDs and many other purposes. + + The monitor and speaker controls should be easy to add to the hid/input +interface, but for the UPSs and LCDs it doesn't make much sense. For this, +the hiddev interface was designed. See Documentation/usb/hiddev.txt +for more information about it. + + The usage of the usbhid module is very simple, it takes no parameters, +detects everything automatically and when a HID device is inserted, it +detects it appropriately. + + However, because the devices vary wildly, you might happen to have a +device that doesn't work well. In that case #define DEBUG at the beginning +of hid-core.c and send me the syslog traces. + +3.1.2 usbmouse +~~~~~~~~~~~~~~ + For embedded systems, for mice with broken HID descriptors and just any +other use when the big usbhid wouldn't be a good choice, there is the +usbmouse driver. It handles USB mice only. It uses a simpler HIDBP +protocol. This also means the mice must support this simpler protocol. Not +all do. If you don't have any strong reason to use this module, use usbhid +instead. + +3.1.3 usbkbd +~~~~~~~~~~~~ + Much like usbmouse, this module talks to keyboards with a simplified +HIDBP protocol. It's smaller, but doesn't support any extra special keys. +Use usbhid instead if there isn't any special reason to use this. + +3.1.4 wacom +~~~~~~~~~~~ + This is a driver for Wacom Graphire and Intuos tablets. Not for Wacom +PenPartner, that one is handled by the HID driver. Although the Intuos and +Graphire tablets claim that they are HID tablets as well, they are not and +thus need this specific driver. + +3.1.5 iforce +~~~~~~~~~~~~ + A driver for I-Force joysticks and wheels, both over USB and RS232. +It includes ForceFeedback support now, even though Immersion +Corp. considers the protocol a trade secret and won't disclose a word +about it. + +3.2 Event handlers +~~~~~~~~~~~~~~~~~~ + Event handlers distrubite the events from the devices to userland and +kernel, as needed. + +3.2.1 keybdev +~~~~~~~~~~~~~ + keybdev is currently a rather ugly hack that translates the input +events into architecture-specific keyboard raw mode (Xlated AT Set2 on +x86), and passes them into the handle_scancode function of the +keyboard.c module. This works well enough on all architectures that +keybdev can generate rawmode on, other architectures can be added to +it. + + The right way would be to pass the events to keyboard.c directly, +best if keyboard.c would itself be an event handler. This is done in +the input patch, available on the webpage mentioned below. + +3.2.2 mousedev +~~~~~~~~~~~~~~ + mousedev is also a hack to make programs that use mouse input +work. It takes events from either mice or digitizers/tablets and makes +a PS/2-style (a la /dev/psaux) mouse device available to the +userland. Ideally, the programs could use a more reasonable interface, +for example evdev + + Mousedev devices in /dev/input (as shown above) are: + + crw-r--r-- 1 root root 13, 32 Mar 28 22:45 mouse0 + crw-r--r-- 1 root root 13, 33 Mar 29 00:41 mouse1 + crw-r--r-- 1 root root 13, 34 Mar 29 00:41 mouse2 + crw-r--r-- 1 root root 13, 35 Apr 1 10:50 mouse3 + ... + ... + crw-r--r-- 1 root root 13, 62 Apr 1 10:50 mouse30 + crw-r--r-- 1 root root 13, 63 Apr 1 10:50 mice + +Each 'mouse' device is assigned to a single mouse or digitizer, except +the last one - 'mice'. This single character device is shared by all +mice and digitizers, and even if none are connected, the device is +present. This is useful for hotplugging USB mice, so that programs +can open the device even when no mice are present. + + CONFIG_INPUT_MOUSEDEV_SCREEN_[XY] in the kernel configuration are +the size of your screen (in pixels) in XFree86. This is needed if you +want to use your digitizer in X, because its movement is sent to X +via a virtual PS/2 mouse and thus needs to be scaled +accordingly. These values won't be used if you use a mouse only. + + Mousedev will generate either PS/2, ImPS/2 (Microsoft IntelliMouse) or +ExplorerPS/2 (IntelliMouse Explorer) protocols, depending on what the +program reading the data wishes. You can set GPM and X to any of +these. You'll need ImPS/2 if you want to make use of a wheel on a USB +mouse and ExplorerPS/2 if you want to use extra (up to 5) buttons. + +3.2.3 joydev +~~~~~~~~~~~~ + Joydev implements v0.x and v1.x Linux joystick api, much like +drivers/char/joystick/joystick.c used to in earlier versions. See +joystick-api.txt in the Documentation subdirectory for details. As +soon as any joystick is connected, it can be accessed in /dev/input +on: + + crw-r--r-- 1 root root 13, 0 Apr 1 10:50 js0 + crw-r--r-- 1 root root 13, 1 Apr 1 10:50 js1 + crw-r--r-- 1 root root 13, 2 Apr 1 10:50 js2 + crw-r--r-- 1 root root 13, 3 Apr 1 10:50 js3 + ... + +And so on up to js31. + +3.2.4 evdev +~~~~~~~~~~~ + evdev is the generic input event interface. It passes the events +generated in the kernel straight to the program, with timestamps. The +API is still evolving, but should be useable now. It's described in +section 5. + + This should be the way for GPM and X to get keyboard and mouse mouse +events. It allows for multihead in X without any specific multihead +kernel support. The event codes are the same on all architectures and +are hardware independent. + + The devices are in /dev/input: + + crw-r--r-- 1 root root 13, 64 Apr 1 10:49 event0 + crw-r--r-- 1 root root 13, 65 Apr 1 10:50 event1 + crw-r--r-- 1 root root 13, 66 Apr 1 10:50 event2 + crw-r--r-- 1 root root 13, 67 Apr 1 10:50 event3 + ... + +And so on up to event31. + +4. Verifying if it works +~~~~~~~~~~~~~~~~~~~~~~~~ + Typing a couple keys on the keyboard should be enough to check that +a USB keyboard works and is correctly connected to the kernel keyboard +driver. + + Doing a cat /dev/input/mouse0 (c, 13, 32) will verify that a mouse +is also emulated, characters should appear if you move it. + + You can test the joystick emulation with the 'jstest' utility, +available in the joystick package (see Documentation/input/joystick.txt). + + You can test the event devices with the 'evtest' utility available +in the LinuxConsole project CVS archive (see the URL below). + +5. Event interface +~~~~~~~~~~~~~~~~~~ + Should you want to add event device support into any application (X, gpm, +svgalib ...) I will be happy to provide you any help I +can. Here goes a description of the current state of things, which is going +to be extended, but not changed incompatibly as time goes: + + You can use blocking and nonblocking reads, also select() on the +/dev/input/eventX devices, and you'll always get a whole number of input +events on a read. Their layout is: + +struct input_event { + struct timeval time; + unsigned short type; + unsigned short code; + unsigned int value; +}; + + 'time' is the timestamp, it returns the time at which the event happened. +Type is for example EV_REL for relative momement, REL_KEY for a keypress or +release. More types are defined in include/linux/input.h. + + 'code' is event code, for example REL_X or KEY_BACKSPACE, again a complete +list is in include/linux/input.h. + + 'value' is the value the event carries. Either a relative change for +EV_REL, absolute new value for EV_ABS (joysticks ...), or 0 for EV_KEY for +release, 1 for keypress and 2 for autorepeat. + +6. Contacts +~~~~~~~~~~~ + This effort has its home page at: + + http://www.suse.cz/development/input/ + +You'll find both the latest HID driver and the complete Input driver +there as well as information how to access the CVS repository for +latest revisions of the drivers. + + There is also a mailing list for this: + + majordomo@atrey.karlin.mff.cuni.cz + +Send "subscribe linux-input" to subscribe to it. + +The input changes are also being worked on as part of the LinuxConsole +project, see: + + http://sourceforge.net/projects/linuxconsole/ + diff --git a/Documentation/input/interactive.fig b/Documentation/input/interactive.fig new file mode 100644 index 00000000000..1e7de387723 --- /dev/null +++ b/Documentation/input/interactive.fig @@ -0,0 +1,42 @@ +#FIG 3.2 +Landscape +Center +Inches +Letter +100.00 +Single +-2 +1200 2 +2 1 0 2 0 7 50 0 -1 6.000 0 0 -1 0 0 6 + 1200 3600 1800 3600 2400 4800 3000 4800 4200 5700 4800 5700 +2 2 0 1 0 7 50 0 -1 4.000 0 0 -1 0 0 5 + 1200 3150 4800 3150 4800 6300 1200 6300 1200 3150 +2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 + 1200 4800 4800 4800 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 4 + 2400 4800 2400 6525 1950 7125 1950 7800 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 4 + 3000 4800 3000 6525 3600 7125 3600 7800 +2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 0 1 3 + 0 0 1.00 60.00 120.00 + 3825 5400 4125 5100 5400 5100 +2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 0 1 3 + 0 0 1.00 60.00 120.00 + 2100 4200 2400 3900 5400 3900 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 + 4800 5700 5400 5700 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 + 1800 3600 5400 3600 +2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 0 1 3 + 0 0 1.00 60.00 120.00 + 2700 4800 2700 4425 5400 4425 +2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 1 2 + 0 0 1.00 60.00 120.00 + 0 0 1.00 60.00 120.00 + 1950 7800 3600 7800 +4 1 0 50 0 0 12 0.0000 4 135 810 2775 7725 Dead band\001 +4 0 0 50 0 0 12 0.0000 4 180 1155 5400 5700 right saturation\001 +4 0 0 50 0 0 12 0.0000 4 135 1065 5400 3600 left saturation\001 +4 0 0 50 0 0 12 0.0000 4 180 2505 5400 3900 left coeff ( positive in that case )\001 +4 0 0 50 0 0 12 0.0000 4 180 2640 5475 5100 right coeff ( negative in that case )\001 +4 0 0 50 0 0 12 0.0000 4 105 480 5400 4425 center\001 diff --git a/Documentation/input/joystick-api.txt b/Documentation/input/joystick-api.txt new file mode 100644 index 00000000000..acbd32b8845 --- /dev/null +++ b/Documentation/input/joystick-api.txt @@ -0,0 +1,316 @@ + Joystick API Documentation -*-Text-*- + + Ragnar Hojland Espinosa + + + 7 Aug 1998 + + $Id: joystick-api.txt,v 1.2 2001/05/08 21:21:23 vojtech Exp $ + +1. 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 check the initial state of the +joystick. + +By default, the device is opened in blocking mode. + + int fd = open ("/dev/js0", O_RDONLY); + + +2. Event Reading +~~~~~~~~~~~~~~~~ + + struct js_event e; + read (fd, &e, sizeof(struct js_event)); + +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(struct js_event), unless +you wanted to read more than one event per read as described in section 3.1. + + +2.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 */ + + +2.2 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, + + 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. + + +2.3 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. + + +2.4 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. + + +3. 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) + + +3.1 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(struct js_event)) > 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. + +[As for 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(struct 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. + + +4. 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); + + +4.1 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 + + +4.2 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); + + +4.3 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 */ + + +5. 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. + + +6. 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 ;) + + - Ragnar +EOF diff --git a/Documentation/input/joystick-parport.txt b/Documentation/input/joystick-parport.txt new file mode 100644 index 00000000000..88a011c9f98 --- /dev/null +++ b/Documentation/input/joystick-parport.txt @@ -0,0 +1,542 @@ + Linux Joystick parport drivers v2.0 + (c) 1998-2000 Vojtech Pavlik + (c) 1998 Andree Borrmann + Sponsored by SuSE + $Id: joystick-parport.txt,v 1.6 2001/09/25 09:31:32 vojtech Exp $ +---------------------------------------------------------------------------- + +0. Disclaimer +~~~~~~~~~~~~~ + Any information in this file is provided as-is, without any guarantee that +it will be true. So, use it at your own risk. The possible damages that can +happen include burning your parallel port, and/or the sticks and joystick +and maybe even more. Like when a lightning kills you it is not our problem. + +1. Intro +~~~~~~~~ + The joystick parport drivers are used for joysticks and gamepads not +originally designed for PCs and other computers Linux runs on. Because of +that, PCs usually lack the right ports to connect these devices to. Parallel +port, because of its ability to change single bits at will, and providing +both output and input bits is the most suitable port on the PC for +connecting such devices. + +2. Devices supported +~~~~~~~~~~~~~~~~~~~~ + Many console and 8-bit computer gamepads and joysticks are supported. The +following subsections discuss usage of each. + +2.1 NES and SNES +~~~~~~~~~~~~~~~~ + The Nintendo Entertainment System and Super Nintendo Entertainment System +gamepads are widely available, and easy to get. Also, they are quite easy to +connect to a PC, and don't need much processing speed (108 us for NES and +165 us for SNES, compared to about 1000 us for PC gamepads) to communicate +with them. + + All NES and SNES use the same synchronous serial protocol, clocked from +the computer's side (and thus timing insensitive). To allow up to 5 NES +and/or SNES gamepads connected to the parallel port at once, the output +lines of the parallel port are shared, while one of 5 available input lines +is assigned to each gamepad. + + This protocol is handled by the gamecon.c driver, so that's the one +you'll use for NES and SNES gamepads. + + The main problem with PC parallel ports is that they don't have +5V power +source on any of their pins. So, if you want a reliable source of power +for your pads, use either keyboard or joystick port, and make a pass-through +cable. You can also pull the power directly from the power supply (the red +wire is +5V). + + If you want to use the parallel port only, you can take the power is from +some data pin. For most gamepad and parport implementations only one pin is +needed, and I'd recommend pin 9 for that, the highest data bit. On the other +hand, if you are not planning to use anything else than NES / SNES on the +port, anything between and including pin 4 and pin 9 will work. + +(pin 9) -----> Power + + Unfortunately, there are pads that need a lot more of power, and parallel +ports that can't give much current through the data pins. If this is your +case, you'll need to use diodes (as a prevention of destroying your parallel +port), and combine the currents of two or more data bits together. + + Diodes +(pin 9) ----|>|-------+------> Power + | +(pin 8) ----|>|-------+ + | +(pin 7) ----|>|-------+ + | + : + | +(pin 4) ----|>|-------+ + + Ground is quite easy. On PC's parallel port the ground is on any of the +pins from pin 18 to pin 25. So use any pin of these you like for the ground. + +(pin 18) -----> Ground + + NES and SNES pads have two input bits, Clock and Latch, which drive the +serial transfer. These are connected to pins 2 and 3 of the parallel port, +respectively. + +(pin 2) -----> Clock +(pin 3) -----> Latch + + And the last thing is the NES / SNES data wire. Only that isn't shared and +each pad needs its own data pin. The parallel port pins are: + +(pin 10) -----> Pad 1 data +(pin 11) -----> Pad 2 data +(pin 12) -----> Pad 3 data +(pin 13) -----> Pad 4 data +(pin 15) -----> Pad 5 data + + Note that pin 14 is not used, since it is not an input pin on the parallel +port. + + This is everything you need on the PC's side of the connection, now on to +the gamepads side. The NES and SNES have different connectors. Also, there +are quite a lot of NES clones, and because Nintendo used proprietary +connectors for their machines, the cloners couldn't and used standard D-Cannon +connectors. Anyway, if you've got a gamepad, and it has buttons A, B, Turbo +A, Turbo B, Select and Start, and is connected through 5 wires, then it is +either a NES or NES clone and will work with this connection. SNES gamepads +also use 5 wires, but have more buttons. They will work as well, of course. + +Pinout for NES gamepads Pinout for SNES gamepads + + +----> Power +-----------------------\ + | 7 | o o o o | x x o | 1 + 5 +---------+ 7 +-----------------------/ + | x x o \ | | | | | + | o o o o | | | | | +-> Ground + 4 +------------+ 1 | | | +------------> Data + | | | | | | +---------------> Latch + | | | +-> Ground | +------------------> Clock + | | +----> Clock +---------------------> Power + | +-------> Latch + +----------> Data + +Pinout for NES clone (db9) gamepads Pinout for NES clone (db15) gamepads + + +---------> Clock +-----------------> Data + | +-------> Latch | +---> Ground + | | +-----> Data | | + | | | ___________________ + _____________ 8 \ o x x x x x x o / 1 + 5 \ x o o o x / 1 \ o x x o x x o / + \ x o x o / 15 `~~~~~~~~~~~~~' 9 + 9 `~~~~~~~' 6 | | | + | | | | +----> Clock + | +----> Power | +----------> Latch + +--------> Ground +----------------> Power + +2.2 Multisystem joysticks +~~~~~~~~~~~~~~~~~~~~~~~~~ + In the era of 8-bit machines, there was something like de-facto standard +for joystick ports. They were all digital, and all used D-Cannon 9 pin +connectors (db9). Because of that, a single joystick could be used without +hassle on Atari (130, 800XE, 800XL, 2600, 7200), Amiga, Commodore C64, +Amstrad CPC, Sinclair ZX Spectrum and many other machines. That's why these +joysticks are called "Multisystem". + + Now their pinout: + + +---------> Right + | +-------> Left + | | +-----> Down + | | | +---> Up + | | | | + _____________ +5 \ x o o o o / 1 + \ x o x o / + 9 `~~~~~~~' 6 + | | + | +----> Button + +--------> Ground + + However, as time passed, extensions to this standard developed, and these +were not compatible with each other: + + + Atari 130, 800/XL/XE MSX + + +-----------> Power + +---------> Right | +---------> Right + | +-------> Left | | +-------> Left + | | +-----> Down | | | +-----> Down + | | | +---> Up | | | | +---> Up + | | | | | | | | | + _____________ _____________ +5 \ x o o o o / 1 5 \ o o o o o / 1 + \ x o o o / \ o o o o / + 9 `~~~~~~~' 6 9 `~~~~~~~' 6 + | | | | | | | + | | +----> Button | | | +----> Button 1 + | +------> Power | | +------> Button 2 + +--------> Ground | +--------> Output 3 + +----------> Ground + + Amstrad CPC Commodore C64 + + +-----------> Analog Y + +---------> Right | +---------> Right + | +-------> Left | | +-------> Left + | | +-----> Down | | | +-----> Down + | | | +---> Up | | | | +---> Up + | | | | | | | | | + _____________ _____________ +5 \ x o o o o / 1 5 \ o o o o o / 1 + \ x o o o / \ o o o o / + 9 `~~~~~~~' 6 9 `~~~~~~~' 6 + | | | | | | | + | | +----> Button 1 | | | +----> Button + | +------> Button 2 | | +------> Power + +--------> Ground | +--------> Ground + +----------> Analog X + + Sinclair Spectrum +2A/+3 Amiga 1200 + + +-----------> Up +-----------> Button 3 + | +---------> Fire | +---------> Right + | | | | +-------> Left + | | +-----> Ground | | | +-----> Down + | | | | | | | +---> Up + | | | | | | | | + _____________ _____________ +5 \ o o x o x / 1 5 \ o o o o o / 1 + \ o o o o / \ o o o o / + 9 `~~~~~~~' 6 9 `~~~~~~~' 6 + | | | | | | | | + | | | +----> Right | | | +----> Button 1 + | | +------> Left | | +------> Power + | +--------> Ground | +--------> Ground + +----------> Down +----------> Button 2 + + And there were many others. + +2.2.1 Multisystem joysticks using db9.c +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + For the Multisystem joysticks, and their derivatives, the db9.c driver +was written. It allows only one joystick / gamepad per parallel port, but +the interface is easy to build and works with almost anything. + + For the basic 1-button Multisystem joystick you connect its wires to the +parallel port like this: + +(pin 1) -----> Power +(pin 18) -----> Ground + +(pin 2) -----> Up +(pin 3) -----> Down +(pin 4) -----> Left +(pin 5) -----> Right +(pin 6) -----> Button 1 + + However, if the joystick is switch based (eg. clicks when you move it), +you might or might not, depending on your parallel port, need 10 kOhm pullup +resistors on each of the direction and button signals, like this: + +(pin 2) ------------+------> Up + Resistor | +(pin 1) --[10kOhm]--+ + + Try without, and if it doesn't work, add them. For TTL based joysticks / +gamepads the pullups are not needed. + + For joysticks with two buttons you connect the second button to pin 7 on +the parallel port. + +(pin 7) -----> Button 2 + + And that's it. + + On a side note, if you have already built a different adapter for use with +the digital joystick driver 0.8.0.2, this is also supported by the db9.c +driver, as device type 8. (See section 3.2) + +2.2.2 Multisystem joysticks using gamecon.c +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + For some people just one joystick per parallel port is not enough, and/or +want to use them on one parallel port together with NES/SNES/PSX pads. This is +possible using the gamecon.c. It supports up to 5 devices of the above types, +including 1 and 2 buttons Multisystem joysticks. + + However, there is nothing for free. To allow more sticks to be used at +once, you need the sticks to be purely switch based (that is non-TTL), and +not to need power. Just a plain simple six switches inside. If your +joystick can do more (eg. turbofire) you'll need to disable it totally first +if you want to use gamecon.c. + + Also, the connection is a bit more complex. You'll need a bunch of diodes, +and one pullup resistor. First, you connect the Directions and the button +the same as for db9, however with the diodes inbetween. + + Diodes +(pin 2) -----|<|----> Up +(pin 3) -----|<|----> Down +(pin 4) -----|<|----> Left +(pin 5) -----|<|----> Right +(pin 6) -----|<|----> Button 1 + + For two button sticks you also connect the other button. + +(pin 7) -----|<|----> Button 2 + + And finally, you connect the Ground wire of the joystick, like done in +this little schematic to Power and Data on the parallel port, as described +for the NES / SNES pads in section 2.1 of this file - that is, one data pin +for each joystick. The power source is shared. + +Data ------------+-----> Ground + Resistor | +Power --[10kOhm]--+ + + And that's all, here we go! + +2.2.3 Multisystem joysticks using turbografx.c +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + The TurboGraFX interface, designed by + + Steffen Schwenke + + allows up to 7 Multisystem joysticks connected to the parallel port. In +Steffen's version, there is support for up to 5 buttons per joystick. However, +since this doesn't work reliably on all parallel ports, the turbografx.c driver +supports only one button per joystick. For more information on how to build the +interface, see + + http://www2.burg-halle.de/~schwenke/parport.html + +2.3 Sony Playstation +~~~~~~~~~~~~~~~~~~~~ + + The PSX controller is supported by the gamecon.c. Pinout of the PSX +controller (compatible with DirectPadPro): + + +---------+---------+---------+ +9 | o o o | o o o | o o o | 1 parallel + \________|_________|________/ port pins + | | | | | | + | | | | | +--------> Clock --- (4) + | | | | +------------> Select --- (3) + | | | +---------------> Power --- (5-9) + | | +------------------> Ground --- (18-25) + | +-------------------------> Command --- (2) + +----------------------------> Data --- (one of 10,11,12,13,15) + + The driver supports these controllers: + + * Standard PSX Pad + * NegCon PSX Pad + * Analog PSX Pad (red mode) + * Analog PSX Pad (green mode) + * PSX Rumble Pad + * PSX DDR Pad + +2.4 Sega +~~~~~~~~ + All the Sega controllers are more or less based on the standard 2-button +Multisystem joystick. However, since they don't use switches and use TTL +logic, the only driver usable with them is the db9.c driver. + +2.4.1 Sega Master System +~~~~~~~~~~~~~~~~~~~~~~~~ + The SMS gamepads are almost exactly the same as normal 2-button +Multisystem joysticks. Set the driver to Multi2 mode, use the corresponding +parallel port pins, and the following schematic: + + +-----------> Power + | +---------> Right + | | +-------> Left + | | | +-----> Down + | | | | +---> Up + | | | | | + _____________ +5 \ o o o o o / 1 + \ o o x o / + 9 `~~~~~~~' 6 + | | | + | | +----> Button 1 + | +--------> Ground + +----------> Button 2 + +2.4.2 Sega Genesis aka MegaDrive +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + The Sega Genesis (in Europe sold as Sega MegaDrive) pads are an extension +to the Sega Master System pads. They use more buttons (3+1, 5+1, 6+1). Use +the following schematic: + + +-----------> Power + | +---------> Right + | | +-------> Left + | | | +-----> Down + | | | | +---> Up + | | | | | + _____________ +5 \ o o o o o / 1 + \ o o o o / + 9 `~~~~~~~' 6 + | | | | + | | | +----> Button 1 + | | +------> Select + | +--------> Ground + +----------> Button 2 + + The Select pin goes to pin 14 on the parallel port. + +(pin 14) -----> Select + + The rest is the same as for Multi2 joysticks using db9.c + +2.4.3 Sega Saturn +~~~~~~~~~~~~~~~~~ + Sega Saturn has eight buttons, and to transfer that, without hacks like +Genesis 6 pads use, it needs one more select pin. Anyway, it is still +handled by the db9.c driver. Its pinout is very different from anything +else. Use this schematic: + + +-----------> Select 1 + | +---------> Power + | | +-------> Up + | | | +-----> Down + | | | | +---> Ground + | | | | | + _____________ +5 \ o o o o o / 1 + \ o o o o / + 9 `~~~~~~~' 6 + | | | | + | | | +----> Select 2 + | | +------> Right + | +--------> Left + +----------> Power + + Select 1 is pin 14 on the parallel port, Select 2 is pin 16 on the +parallel port. + +(pin 14) -----> Select 1 +(pin 16) -----> Select 2 + + The other pins (Up, Down, Right, Left, Power, Ground) are the same as for +Multi joysticks using db9.c + +3. The drivers +~~~~~~~~~~~~~~ + There are three drivers for the parallel port interfaces. Each, as +described above, allows to connect a different group of joysticks and pads. +Here are described their command lines: + +3.1 gamecon.c +~~~~~~~~~~~~~ + Using gamecon.c you can connect up to five devices to one parallel port. It +uses the following kernel/module command line: + + gamecon.map=port,pad1,pad2,pad3,pad4,pad5 + + Where 'port' the number of the parport interface (eg. 0 for parport0). + + And 'pad1' to 'pad5' are pad types connected to different data input pins +(10,11,12,13,15), as described in section 2.1 of this file. + + The types are: + + Type | Joystick/Pad + -------------------- + 0 | None + 1 | SNES pad + 2 | NES pad + 4 | Multisystem 1-button joystick + 5 | Multisystem 2-button joystick + 6 | N64 pad + 7 | Sony PSX controller + 8 | Sony PSX DDR controller + + The exact type of the PSX controller type is autoprobed when used so +hot swapping should work (but is not recomended). + + Should you want to use more than one of parallel ports at once, you can use +gamecon.map2 and gamecon.map3 as additional command line parameters for two +more parallel ports. + + There are two options specific to PSX driver portion. gamecon.psx_delay sets +the command delay when talking to the controllers. The default of 25 should +work but you can try lowering it for better performace. If your pads don't +respond try raising it untill they work. Setting the type to 8 allows the +driver to be used with Dance Dance Revolution or similar games. Arrow keys are +registered as key presses instead of X and Y axes. + +3.2 db9.c +~~~~~~~~~ + Apart from making an interface, there is nothing difficult on using the +db9.c driver. It uses the following kernel/module command line: + + db9.dev=port,type + + Where 'port' is the number of the parport interface (eg. 0 for parport0). + + Caveat here: This driver only works on bidirectional parallel ports. If +your parallel port is recent enough, you should have no trouble with this. +Old parallel ports may not have this feature. + + 'Type' is the type of joystick or pad attached: + + Type | Joystick/Pad + -------------------- + 0 | None + 1 | Multisystem 1-button joystick + 2 | Multisystem 2-button joystick + 3 | Genesis pad (3+1 buttons) + 5 | Genesis pad (5+1 buttons) + 6 | Genesis pad (6+2 buttons) + 7 | Saturn pad (8 buttons) + 8 | Multisystem 1-button joystick (v0.8.0.2 pin-out) + 9 | Two Multisystem 1-button joysticks (v0.8.0.2 pin-out) + 10 | Amiga CD32 pad + + Should you want to use more than one of these joysticks/pads at once, you +can use db9.dev2 and db9.dev3 as additional command line parameters for two +more joysticks/pads. + +3.3 turbografx.c +~~~~~~~~~~~~~~~~ + The turbografx.c driver uses a very simple kernel/module command line: + + turbografx.map=port,js1,js2,js3,js4,js5,js6,js7 + + Where 'port' is the number of the parport interface (eg. 0 for parport0). + + 'jsX' is the number of buttons the Multisystem joysticks connected to the +interface ports 1-7 have. For a standard multisystem joystick, this is 1. + + Should you want to use more than one of these interfaces at once, you can +use turbografx.map2 and turbografx.map3 as additional command line parameters +for two more interfaces. + +3.4 PC parallel port pinout +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .----------------------------------------. + At the PC: \ 13 12 11 10 9 8 7 6 5 4 3 2 1 / + \ 25 24 23 22 21 20 19 18 17 16 15 14 / + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Pin | Name | Description + ~~~~~~|~~~~~~~~~|~~~~~~~~~~ + 1 | /STROBE | Strobe + 2-9 | D0-D7 | Data Bit 0-7 + 10 | /ACK | Acknowledge + 11 | BUSY | Busy + 12 | PE | Paper End + 13 | SELIN | Select In + 14 | /AUTOFD | Autofeed + 15 | /ERROR | Error + 16 | /INIT | Initialize + 17 | /SEL | Select + 18-25 | GND | Signal Ground + +3.5 End +~~~~~~~ + That's all, folks! Have fun! diff --git a/Documentation/input/joystick.txt b/Documentation/input/joystick.txt new file mode 100644 index 00000000000..d53b857a371 --- /dev/null +++ b/Documentation/input/joystick.txt @@ -0,0 +1,588 @@ + Linux Joystick driver v2.0.0 + (c) 1996-2000 Vojtech Pavlik + Sponsored by SuSE + $Id: joystick.txt,v 1.12 2002/03/03 12:13:07 jdeneux Exp $ +---------------------------------------------------------------------------- + +0. Disclaimer +~~~~~~~~~~~~~ + This program is free software; you can redistribute it and/or modify it +under the terms of the GNU General Public License as published by the Free +Software Foundation; either version 2 of the License, or (at your option) +any later version. + + This program is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for +more details. + + You should have received a copy of the GNU General Public License along +with this program; if not, write to the Free Software Foundation, Inc., 59 +Temple Place, Suite 330, Boston, MA 02111-1307 USA + + Should you need to contact me, the author, you can do so either by e-mail +- mail your message to , or by paper mail: Vojtech Pavlik, +Simunkova 1594, Prague 8, 182 00 Czech Republic + + For your convenience, the GNU General Public License version 2 is included +in the package: See the file COPYING. + +1. Intro +~~~~~~~~ + 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. + + Should you encounter any problems while using the driver, or joysticks +this driver can't make complete use of, I'm very interested in hearing about +them. Bug reports and success stories are also welcome. + + The input project website is at: + + http://www.suse.cz/development/input/ + http://atrey.karlin.mff.cuni.cz/~vojtech/input/ + + There is also a mailing list for the driver at: + + listproc@atrey.karlin.mff.cuni.cz + +send "subscribe linux-joystick Your Name" to subscribe to it. + +2. Usage +~~~~~~~~ + For basic usage you just choose the right options in kernel config and +you should be set. + +2.1 inpututils +~~~~~~~~~~~~~~ +For testing and other purposes (for example serial devices), a set of +utilities is available at the abovementioned website. I suggest you download +and install it before going on. + +2.2 Device nodes +~~~~~~~~~~~~~~~~ +For applications to be able to use the joysticks, in you don't use devfs, +you'll have to manually create these nodes in /dev: + +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 + +2.4 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 + +2.5 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/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. + +2.6. 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/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/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. + + +3. HW specific driver information +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +In this section each of the separate hardware specific drivers is described. + +3.1 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=,,,.... + + '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 + +3.2 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. + +3.3 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. + +3.4 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. + +3.5 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. + +3.6 ThrustMaster DirectConnect (BSP) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + The TM DirectConnect (BSP) protocol is supported by the tmdc.c +module. This includes, but is not limited to: + +* ThrustMaster Millenium 3D Inceptor +* 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. + +3.7 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. + +3.8 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. + +3.9 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. + +3.10 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. + +3.11 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.. + +3.13 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. + +3.14 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 +it's ISA counterparts. It also requires special support, hence the +emu10k1-gp.c module for it instead of the normal ns558.c one. + +3.15 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. + +3.16 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 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. + +3.17 Game console and 8-bit pads and joysticks +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +See joystick-parport.txt for more info. + +3.18 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. + +3.19 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. + +3.20 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. + +3.21 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. + +3.22 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. + +4. 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! :) + +5. FAQ +~~~~~~ +Q: Running 'jstest /dev/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. + +6. Programming 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. diff --git a/Documentation/input/shape.fig b/Documentation/input/shape.fig new file mode 100644 index 00000000000..c22bff83d06 --- /dev/null +++ b/Documentation/input/shape.fig @@ -0,0 +1,65 @@ +#FIG 3.2 +Landscape +Center +Inches +Letter +100.00 +Single +-2 +1200 2 +2 1 0 2 0 7 50 0 -1 0.000 0 0 -1 0 0 6 + 4200 3600 4200 3075 4950 2325 7425 2325 8250 3150 8250 3600 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 + 4200 3675 4200 5400 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 + 8250 3675 8250 5400 +2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 + 3675 3600 8700 3600 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 + 8775 3600 10200 3600 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 + 8325 3150 9075 3150 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 + 7500 2325 10200 2325 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 + 3600 3600 3000 3600 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 + 4125 3075 3000 3075 +2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 1 2 + 0 0 1.00 60.00 120.00 + 0 0 1.00 60.00 120.00 + 4200 5400 8175 5400 +2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 1 2 + 0 0 1.00 60.00 120.00 + 0 0 1.00 60.00 120.00 + 10125 2325 10125 3600 +2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 1 2 + 0 0 1.00 60.00 120.00 + 0 0 1.00 60.00 120.00 + 3000 3150 3000 3600 +2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 1 2 + 0 0 1.00 60.00 120.00 + 0 0 1.00 60.00 120.00 + 9075 3150 9075 3600 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 + 4950 2325 4950 1200 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 + 7425 2325 7425 1200 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 4 + 4200 3075 4200 2400 3600 1800 3600 1200 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 4 + 8250 3150 8250 2475 8775 1950 8775 1200 +2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 1 2 + 0 0 1.00 60.00 120.00 + 0 0 1.00 60.00 120.00 + 3600 1275 4950 1275 +2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 1 2 + 0 0 1.00 60.00 120.00 + 0 0 1.00 60.00 120.00 + 7425 1275 8700 1275 +4 1 0 50 0 0 12 0.0000 4 135 1140 6075 5325 Effect duration\001 +4 0 0 50 0 0 12 0.0000 4 180 1305 10200 3000 Effect magnitude\001 +4 0 0 50 0 0 12 0.0000 4 135 780 9150 3450 Fade level\001 +4 1 0 50 0 0 12 0.0000 4 180 1035 4275 1200 Attack length\001 +4 1 0 50 0 0 12 0.0000 4 180 885 8175 1200 Fade length\001 +4 2 0 50 0 0 12 0.0000 4 135 930 2925 3375 Attack level\001 diff --git a/Documentation/input/xpad.txt b/Documentation/input/xpad.txt new file mode 100644 index 00000000000..b9111a703ce --- /dev/null +++ b/Documentation/input/xpad.txt @@ -0,0 +1,116 @@ +xpad - Linux USB driver for X-Box gamepads + +This is the very first release of a driver for X-Box gamepads. +Basically, this was hacked away in just a few hours, so don't expect +miracles. +In particular, there is currently NO support for the rumble pack. +You won't find many ff-aware linux applications anyway. + + +0. Status +--------- + +For now, this driver has only been tested on just one Linux-Box. +This one is running a 2.4.18 kernel with usb-uhci on an amd athlon 600. + +The jstest-program from joystick-1.2.15 (jstest-version 2.1.0) reports +8 axes and 10 buttons. + +Alls 8 axes work, though they all have the same range (-32768..32767) +and the zero-setting is not correct for the triggers (I don't know if that +is some limitation of jstest, since the input device setup should be fine. I +didn't have a look at jstest itself yet). + +All of the 10 buttons work (in digital mode). The six buttons on the +right side (A, B, X, Y, black, white) are said to be "analog" and +report their values as 8 bit unsigned, not sure what this is good for. + +I tested the controller with quake3, and configuration and +in game functionality were OK. However, I find it rather difficult to +play first person shooters with a pad. Your mileage may vary. + + +1. USB adapter +-------------- + +Before you can actually use the driver, you need to get yourself an +adapter cable to connect the X-Box controller to your Linux-Box. + +Such a cable is pretty easy to build. The Controller itself is a USB compound +device (a hub with three ports for two expansion slots and the controller +device) with the only difference in a nonstandard connector (5 pins vs. 4 on +standard USB connector). + +You just need to solder a USB connector onto the cable and keep the +yellow wire unconnected. The other pins have the same order on both +connectors so there is no magic to it. Detailed info on these matters +can be found on the net ([1], [2], [3]). + +Thanks to the trip splitter found on the cable you don't even need to cut the +original one. You can buy an extension cable and cut that instead. That way, +you can still use the controller with your X-Box, if you have one ;) + + +2. driver installation +---------------------- + +Once you have the adapter cable and the controller is connected, you need +to load your USB subsystem and should cat /proc/bus/usb/devices. +There should be an entry like the one at the end [4]. + +Currently (as of version 0.0.4), the following three devices are included: + original Microsoft XBOX controller (US), vendor=0x045e, product=0x0202 + original Microsoft XBOX controller (Japan), vendor=0x045e, product=0x0285 + InterAct PowerPad Pro (Germany), vendor=0x05fd, product=0x107a + +If you have another controller that is not listed above and is not recognized +by the driver, please drop me a line with the appropriate info (that is, include +the name, vendor and product ID, as well as the country where you bought it; +sending the whole dump out of /proc/bus/usb/devices along would be even better). + +In theory, the driver should work with other controllers than mine +(InterAct PowerPad pro, bought in Germany) just fine, but I cannot test this +for I only have this one controller. + +If you compiled and installed the driver, test the functionality: +> modprobe xpad +> modprobe joydev +> jstest /dev/js0 + +There should be a single line showing 18 inputs (8 axes, 10 buttons), and +it's values should change if you move the sticks and push the buttons. + +It works? Voila, your done ;) + + +3. Thanks +--------- + +I have to thank ITO Takayuki for the detailed info on his site + http://euc.jp/periphs/xbox-controller.ja.html. + +His useful info and both the usb-skeleton as well as the iforce input driver +(Greg Kroah-Hartmann; Vojtech Pavlik) helped a lot in rapid prototyping +the basic functionality. + + +4. References +------------- + +1. http://euc.jp/periphs/xbox-controller.ja.html (ITO Takayuki) +2. http://xpad.xbox-scene.com/ +3. http://www.xboxhackz.com/Hackz-Reference.htm + +4. /proc/bus/usb/devices - dump from InterAct PowerPad Pro (Germany): + +T: Bus=01 Lev=03 Prnt=04 Port=00 Cnt=01 Dev#= 5 Spd=12 MxCh= 0 +D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS=32 #Cfgs= 1 +P: Vendor=05fd ProdID=107a Rev= 1.00 +C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA +I: If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=(none) +E: Ad=81(I) Atr=03(Int.) MxPS= 32 Ivl= 10ms +E: Ad=02(O) Atr=03(Int.) MxPS= 32 Ivl= 10ms + +-- +Marko Friedemann +2002-07-16 -- cgit v1.2.3-70-g09d2