diff options
Diffstat (limited to 'Documentation/input')
29 files changed, 0 insertions, 7411 deletions
diff --git a/Documentation/input/alps.txt b/Documentation/input/alps.txt deleted file mode 100644 index ae8ba9a74ce..00000000000 --- a/Documentation/input/alps.txt +++ /dev/null @@ -1,189 +0,0 @@ -ALPS Touchpad Protocol ----------------------- - -Introduction ------------- - -Currently the ALPS touchpad driver supports four protocol versions in use by -ALPS touchpads, called versions 1, 2, 3, and 4. Information about the various -protocol versions is contained in the following sections. - -Detection ---------- - -All ALPS touchpads should respond to the "E6 report" command sequence: -E8-E6-E6-E6-E9. An ALPS touchpad should respond with either 00-00-0A or -00-00-64 if no buttons are pressed. The bits 0-2 of the first byte will be 1s -if some buttons are pressed. - -If the E6 report is successful, the touchpad model is identified using the "E7 -report" sequence: E8-E7-E7-E7-E9. The response is the model signature and is -matched against known models in the alps_model_data_array. - -With protocol versions 3 and 4, the E7 report model signature is always -73-02-64. To differentiate between these versions, the response from the -"Enter Command Mode" sequence must be inspected as described below. - -Command Mode ------------- - -Protocol versions 3 and 4 have a command mode that is used to read and write -one-byte device registers in a 16-bit address space. The command sequence -EC-EC-EC-E9 places the device in command mode, and the device will respond -with 88-07 followed by a third byte. This third byte can be used to determine -whether the devices uses the version 3 or 4 protocol. - -To exit command mode, PSMOUSE_CMD_SETSTREAM (EA) is sent to the touchpad. - -While in command mode, register addresses can be set by first sending a -specific command, either EC for v3 devices or F5 for v4 devices. Then the -address is sent one nibble at a time, where each nibble is encoded as a -command with optional data. This enoding differs slightly between the v3 and -v4 protocols. - -Once an address has been set, the addressed register can be read by sending -PSMOUSE_CMD_GETINFO (E9). The first two bytes of the response contains the -address of the register being read, and the third contains the value of the -register. Registers are written by writing the value one nibble at a time -using the same encoding used for addresses. - -Packet Format -------------- - -In the following tables, the following notation is used. - - CAPITALS = stick, miniscules = touchpad - -?'s can have different meanings on different models, such as wheel rotation, -extra buttons, stick buttons on a dualpoint, etc. - -PS/2 packet format ------------------- - - byte 0: 0 0 YSGN XSGN 1 M R L - byte 1: X7 X6 X5 X4 X3 X2 X1 X0 - byte 2: Y7 Y6 Y5 Y4 Y3 Y2 Y1 Y0 - -Note that the device never signals overflow condition. - -ALPS Absolute Mode - Protocol Verion 1 --------------------------------------- - - byte 0: 1 0 0 0 1 x9 x8 x7 - byte 1: 0 x6 x5 x4 x3 x2 x1 x0 - byte 2: 0 ? ? l r ? fin ges - byte 3: 0 ? ? ? ? y9 y8 y7 - byte 4: 0 y6 y5 y4 y3 y2 y1 y0 - byte 5: 0 z6 z5 z4 z3 z2 z1 z0 - -ALPS Absolute Mode - Protocol Version 2 ---------------------------------------- - - byte 0: 1 ? ? ? 1 ? ? ? - byte 1: 0 x6 x5 x4 x3 x2 x1 x0 - byte 2: 0 x10 x9 x8 x7 ? fin ges - byte 3: 0 y9 y8 y7 1 M R L - byte 4: 0 y6 y5 y4 y3 y2 y1 y0 - byte 5: 0 z6 z5 z4 z3 z2 z1 z0 - -Dualpoint device -- interleaved packet format ---------------------------------------------- - - byte 0: 1 1 0 0 1 1 1 1 - byte 1: 0 x6 x5 x4 x3 x2 x1 x0 - byte 2: 0 x10 x9 x8 x7 0 fin ges - byte 3: 0 0 YSGN XSGN 1 1 1 1 - byte 4: X7 X6 X5 X4 X3 X2 X1 X0 - byte 5: Y7 Y6 Y5 Y4 Y3 Y2 Y1 Y0 - byte 6: 0 y9 y8 y7 1 m r l - byte 7: 0 y6 y5 y4 y3 y2 y1 y0 - byte 8: 0 z6 z5 z4 z3 z2 z1 z0 - -ALPS Absolute Mode - Protocol Version 3 ---------------------------------------- - -ALPS protocol version 3 has three different packet formats. The first two are -associated with touchpad events, and the third is associatd with trackstick -events. - -The first type is the touchpad position packet. - - byte 0: 1 ? x1 x0 1 1 1 1 - byte 1: 0 x10 x9 x8 x7 x6 x5 x4 - byte 2: 0 y10 y9 y8 y7 y6 y5 y4 - byte 3: 0 M R L 1 m r l - byte 4: 0 mt x3 x2 y3 y2 y1 y0 - byte 5: 0 z6 z5 z4 z3 z2 z1 z0 - -Note that for some devices the trackstick buttons are reported in this packet, -and on others it is reported in the trackstick packets. - -The second packet type contains bitmaps representing the x and y axes. In the -bitmaps a given bit is set if there is a finger covering that position on the -given axis. Thus the bitmap packet can be used for low-resolution multi-touch -data, although finger tracking is not possible. This packet also encodes the -number of contacts (f1 and f0 in the table below). - - byte 0: 1 1 x1 x0 1 1 1 1 - byte 1: 0 x8 x7 x6 x5 x4 x3 x2 - byte 2: 0 y7 y6 y5 y4 y3 y2 y1 - byte 3: 0 y10 y9 y8 1 1 1 1 - byte 4: 0 x14 x13 x12 x11 x10 x9 y0 - byte 5: 0 1 ? ? ? ? f1 f0 - -This packet only appears after a position packet with the mt bit set, and -usually only appears when there are two or more contacts (although -occassionally it's seen with only a single contact). - -The final v3 packet type is the trackstick packet. - - byte 0: 1 1 x7 y7 1 1 1 1 - byte 1: 0 x6 x5 x4 x3 x2 x1 x0 - byte 2: 0 y6 y5 y4 y3 y2 y1 y0 - byte 3: 0 1 0 0 1 0 0 0 - byte 4: 0 z4 z3 z2 z1 z0 ? ? - byte 5: 0 0 1 1 1 1 1 1 - -ALPS Absolute Mode - Protocol Version 4 ---------------------------------------- - -Protocol version 4 has an 8-byte packet format. - - byte 0: 1 ? x1 x0 1 1 1 1 - byte 1: 0 x10 x9 x8 x7 x6 x5 x4 - byte 2: 0 y10 y9 y8 y7 y6 y5 y4 - byte 3: 0 1 x3 x2 y3 y2 y1 y0 - byte 4: 0 ? ? ? 1 ? r l - byte 5: 0 z6 z5 z4 z3 z2 z1 z0 - byte 6: bitmap data (described below) - byte 7: bitmap data (described below) - -The last two bytes represent a partial bitmap packet, with 3 full packets -required to construct a complete bitmap packet. Once assembled, the 6-byte -bitmap packet has the following format: - - byte 0: 0 1 x7 x6 x5 x4 x3 x2 - byte 1: 0 x1 x0 y4 y3 y2 y1 y0 - byte 2: 0 0 ? x14 x13 x12 x11 x10 - byte 3: 0 x9 x8 y9 y8 y7 y6 y5 - byte 4: 0 0 0 0 0 0 0 0 - byte 5: 0 0 0 0 0 0 0 y10 - -There are several things worth noting here. - - 1) In the bitmap data, bit 6 of byte 0 serves as a sync byte to - identify the first fragment of a bitmap packet. - - 2) The bitmaps represent the same data as in the v3 bitmap packets, although - the packet layout is different. - - 3) There doesn't seem to be a count of the contact points anywhere in the v4 - protocol packets. Deriving a count of contact points must be done by - analyzing the bitmaps. - - 4) There is a 3 to 1 ratio of position packets to bitmap packets. Therefore - MT position can only be updated for every third ST position update, and - the count of contact points can only be updated every third packet as - well. - -So far no v4 devices with tracksticks have been encountered. diff --git a/Documentation/input/amijoy.txt b/Documentation/input/amijoy.txt deleted file mode 100644 index 7dc4f175943..00000000000 --- a/Documentation/input/amijoy.txt +++ /dev/null @@ -1,184 +0,0 @@ -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 received: - - +-------------------+-----------------------------------------+ - | 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 Horizontal Clock | - | 5 | M1VQ | JOY1DAT Horizontal 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/appletouch.txt b/Documentation/input/appletouch.txt deleted file mode 100644 index b13de3f8910..00000000000 --- a/Documentation/input/appletouch.txt +++ /dev/null @@ -1,85 +0,0 @@ -Apple Touchpad Driver (appletouch) ----------------------------------- - Copyright (C) 2005 Stelian Pop <stelian@popies.net> - -appletouch is a Linux kernel driver for the USB touchpad found on post -February 2005 and October 2005 Apple Aluminium Powerbooks. - -This driver is derived from Johannes Berg's appletrackpad driver[1], but it has -been improved in some areas: - * appletouch is a full kernel driver, no userspace program is necessary - * appletouch can be interfaced with the synaptics X11 driver, in order - to have touchpad acceleration, scrolling, etc. - -Credits go to Johannes Berg for reverse-engineering the touchpad protocol, -Frank Arnold for further improvements, and Alex Harper for some additional -information about the inner workings of the touchpad sensors. Michael -Hanselmann added support for the October 2005 models. - -Usage: ------- - -In order to use the touchpad in the basic mode, compile the driver and load -the module. A new input device will be detected and you will be able to read -the mouse data from /dev/input/mice (using gpm, or X11). - -In X11, you can configure the touchpad to use the synaptics X11 driver, which -will give additional functionalities, like acceleration, scrolling, 2 finger -tap for middle button mouse emulation, 3 finger tap for right button mouse -emulation, etc. In order to do this, make sure you're using a recent version of -the synaptics driver (tested with 0.14.2, available from [2]), and configure a -new input device in your X11 configuration file (take a look below for an -example). For additional configuration, see the synaptics driver documentation. - - Section "InputDevice" - Identifier "Synaptics Touchpad" - Driver "synaptics" - Option "SendCoreEvents" "true" - Option "Device" "/dev/input/mice" - Option "Protocol" "auto-dev" - Option "LeftEdge" "0" - Option "RightEdge" "850" - Option "TopEdge" "0" - Option "BottomEdge" "645" - Option "MinSpeed" "0.4" - Option "MaxSpeed" "1" - Option "AccelFactor" "0.02" - Option "FingerLow" "0" - Option "FingerHigh" "30" - Option "MaxTapMove" "20" - Option "MaxTapTime" "100" - Option "HorizScrollDelta" "0" - Option "VertScrollDelta" "30" - Option "SHMConfig" "on" - EndSection - - Section "ServerLayout" - ... - InputDevice "Mouse" - InputDevice "Synaptics Touchpad" - ... - EndSection - -Fuzz problems: --------------- - -The touchpad sensors are very sensitive to heat, and will generate a lot of -noise when the temperature changes. This is especially true when you power-on -the laptop for the first time. - -The appletouch driver tries to handle this noise and auto adapt itself, but it -is not perfect. If finger movements are not recognized anymore, try reloading -the driver. - -You can activate debugging using the 'debug' module parameter. A value of 0 -deactivates any debugging, 1 activates tracing of invalid samples, 2 activates -full tracing (each sample is being traced): - modprobe appletouch debug=1 - or - echo "1" > /sys/module/appletouch/parameters/debug - -Links: ------- - -[1]: http://johannes.sipsolutions.net/PowerBook/touchpad/ -[2]: http://web.archive.org/web/*/http://web.telia.com/~u89404340/touchpad/index.html diff --git a/Documentation/input/atarikbd.txt b/Documentation/input/atarikbd.txt deleted file mode 100644 index f3a3ba8847b..00000000000 --- a/Documentation/input/atarikbd.txt +++ /dev/null @@ -1,709 +0,0 @@ -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 -variety 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 determined 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 -resetting 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 whenever 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/release 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 disable 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 internal X - Y ; vertical mouse ticks per internal 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 internal 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 <tbd> -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 hundredths 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 line, 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 keystrokes are generated - ; after RX has elapsed - VY ; length (in tenths of seconds) of joystick closure - ; until vertical cursor keystrokes 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 command 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 returned by the ikbd are chosen to simplify the -implementation 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/bcm5974.txt b/Documentation/input/bcm5974.txt deleted file mode 100644 index 74d3876d6f3..00000000000 --- a/Documentation/input/bcm5974.txt +++ /dev/null @@ -1,65 +0,0 @@ -BCM5974 Driver (bcm5974) ------------------------- - Copyright (C) 2008-2009 Henrik Rydberg <rydberg@euromail.se> - -The USB initialization and package decoding was made by Scott Shawcroft as -part of the touchd user-space driver project: - Copyright (C) 2008 Scott Shawcroft (scott.shawcroft@gmail.com) - -The BCM5974 driver is based on the appletouch driver: - Copyright (C) 2001-2004 Greg Kroah-Hartman (greg@kroah.com) - Copyright (C) 2005 Johannes Berg (johannes@sipsolutions.net) - Copyright (C) 2005 Stelian Pop (stelian@popies.net) - Copyright (C) 2005 Frank Arnold (frank@scirocco-5v-turbo.de) - Copyright (C) 2005 Peter Osterlund (petero2@telia.com) - Copyright (C) 2005 Michael Hanselmann (linux-kernel@hansmi.ch) - Copyright (C) 2006 Nicolas Boichat (nicolas@boichat.ch) - -This driver adds support for the multi-touch trackpad on the new Apple -Macbook Air and Macbook Pro laptops. It replaces the appletouch driver on -those computers, and integrates well with the synaptics driver of the Xorg -system. - -Known to work on Macbook Air, Macbook Pro Penryn and the new unibody -Macbook 5 and Macbook Pro 5. - -Usage ------ - -The driver loads automatically for the supported usb device ids, and -becomes available both as an event device (/dev/input/event*) and as a -mouse via the mousedev driver (/dev/input/mice). - -USB Race --------- - -The Apple multi-touch trackpads report both mouse and keyboard events via -different interfaces of the same usb device. This creates a race condition -with the HID driver, which, if not told otherwise, will find the standard -HID mouse and keyboard, and claim the whole device. To remedy, the usb -product id must be listed in the mouse_ignore list of the hid driver. - -Debug output ------------- - -To ease the development for new hardware version, verbose packet output can -be switched on with the debug kernel module parameter. The range [1-9] -yields different levels of verbosity. Example (as root): - -echo -n 9 > /sys/module/bcm5974/parameters/debug - -tail -f /var/log/debug - -echo -n 0 > /sys/module/bcm5974/parameters/debug - -Trivia ------- - -The driver was developed at the ubuntu forums in June 2008 [1], and now has -a more permanent home at bitmath.org [2]. - -Links ------ - -[1] http://ubuntuforums.org/showthread.php?t=840040 -[2] http://bitmath.org/code/ diff --git a/Documentation/input/cd32.txt b/Documentation/input/cd32.txt deleted file mode 100644 index a003d9b41ec..00000000000 --- a/Documentation/input/cd32.txt +++ /dev/null @@ -1,19 +0,0 @@ -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/cma3000_d0x.txt b/Documentation/input/cma3000_d0x.txt deleted file mode 100644 index 29d088db4af..00000000000 --- a/Documentation/input/cma3000_d0x.txt +++ /dev/null @@ -1,115 +0,0 @@ -Kernel driver for CMA3000-D0x -============================ - -Supported chips: -* VTI CMA3000-D0x -Datasheet: - CMA3000-D0X Product Family Specification 8281000A.02.pdf - <http://www.vti.fi/en/> - -Author: Hemanth V <hemanthv@ti.com> - - -Description ------------ -CMA3000 Tri-axis accelerometer supports Motion detect, Measurement and -Free fall modes. - -Motion Detect Mode: Its the low power mode where interrupts are generated only -when motion exceeds the defined thresholds. - -Measurement Mode: This mode is used to read the acceleration data on X,Y,Z -axis and supports 400, 100, 40 Hz sample frequency. - -Free fall Mode: This mode is intended to save system resources. - -Threshold values: Chip supports defining threshold values for above modes -which includes time and g value. Refer product specifications for more details. - -CMA3000 chip supports mutually exclusive I2C and SPI interfaces for -communication, currently the driver supports I2C based communication only. -Initial configuration for bus mode is set in non volatile memory and can later -be modified through bus interface command. - -Driver reports acceleration data through input subsystem. It generates ABS_MISC -event with value 1 when free fall is detected. - -Platform data need to be configured for initial default values. - -Platform Data -------------- -fuzz_x: Noise on X Axis - -fuzz_y: Noise on Y Axis - -fuzz_z: Noise on Z Axis - -g_range: G range in milli g i.e 2000 or 8000 - -mode: Default Operating mode - -mdthr: Motion detect g range threshold value - -mdfftmr: Motion detect and free fall time threshold value - -ffthr: Free fall g range threshold value - -Input Interface --------------- -Input driver version is 1.0.0 -Input device ID: bus 0x18 vendor 0x0 product 0x0 version 0x0 -Input device name: "cma3000-accelerometer" -Supported events: - Event type 0 (Sync) - Event type 3 (Absolute) - Event code 0 (X) - Value 47 - Min -8000 - Max 8000 - Fuzz 200 - Event code 1 (Y) - Value -28 - Min -8000 - Max 8000 - Fuzz 200 - Event code 2 (Z) - Value 905 - Min -8000 - Max 8000 - Fuzz 200 - Event code 40 (Misc) - Value 0 - Min 0 - Max 1 - Event type 4 (Misc) - - -Register/Platform parameters Description ----------------------------------------- - -mode: - 0: power down mode - 1: 100 Hz Measurement mode - 2: 400 Hz Measurement mode - 3: 40 Hz Measurement mode - 4: Motion Detect mode (default) - 5: 100 Hz Free fall mode - 6: 40 Hz Free fall mode - 7: Power off mode - -grange: - 2000: 2000 mg or 2G Range - 8000: 8000 mg or 8G Range - -mdthr: - X: X * 71mg (8G Range) - X: X * 18mg (2G Range) - -mdfftmr: - X: (X & 0x70) * 100 ms (MDTMR) - (X & 0x0F) * 2.5 ms (FFTMR 400 Hz) - (X & 0x0F) * 10 ms (FFTMR 100 Hz) - -ffthr: - X: (X >> 2) * 18mg (2G Range) - X: (X & 0x0F) * 71 mg (8G Range) diff --git a/Documentation/input/cs461x.txt b/Documentation/input/cs461x.txt deleted file mode 100644 index 202e9dbacec..00000000000 --- a/Documentation/input/cs461x.txt +++ /dev/null @@ -1,45 +0,0 @@ -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 with ALSA drivers simultaneously. For example, 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 can 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/elantech.txt b/Documentation/input/elantech.txt deleted file mode 100644 index 5602eb71ad5..00000000000 --- a/Documentation/input/elantech.txt +++ /dev/null @@ -1,745 +0,0 @@ -Elantech Touchpad Driver -======================== - - Copyright (C) 2007-2008 Arjan Opmeer <arjan@opmeer.net> - - Extra information for hardware version 1 found and - provided by Steve Havelka - - Version 2 (EeePC) hardware support based on patches - received from Woody at Xandros and forwarded to me - by user StewieGriffin at the eeeuser.com forum - - -Contents -~~~~~~~~ - - 1. Introduction - 2. Extra knobs - 3. Differentiating hardware versions - 4. Hardware version 1 - 4.1 Registers - 4.2 Native relative mode 4 byte packet format - 4.3 Native absolute mode 4 byte packet format - 5. Hardware version 2 - 5.1 Registers - 5.2 Native absolute mode 6 byte packet format - 5.2.1 Parity checking and packet re-synchronization - 5.2.2 One/Three finger touch - 5.2.3 Two finger touch - 6. Hardware version 3 - 6.1 Registers - 6.2 Native absolute mode 6 byte packet format - 6.2.1 One/Three finger touch - 6.2.2 Two finger touch - 7. Hardware version 4 - 7.1 Registers - 7.2 Native absolute mode 6 byte packet format - 7.2.1 Status packet - 7.2.2 Head packet - 7.2.3 Motion packet - - - -1. Introduction - ~~~~~~~~~~~~ - -Currently the Linux Elantech touchpad driver is aware of two different -hardware versions unimaginatively called version 1 and version 2. Version 1 -is found in "older" laptops and uses 4 bytes per packet. Version 2 seems to -be introduced with the EeePC and uses 6 bytes per packet, and provides -additional features such as position of two fingers, and width of the touch. - -The driver tries to support both hardware versions and should be compatible -with the Xorg Synaptics touchpad driver and its graphical configuration -utilities. - -Additionally the operation of the touchpad can be altered by adjusting the -contents of some of its internal registers. These registers are represented -by the driver as sysfs entries under /sys/bus/serio/drivers/psmouse/serio? -that can be read from and written to. - -Currently only the registers for hardware version 1 are somewhat understood. -Hardware version 2 seems to use some of the same registers but it is not -known whether the bits in the registers represent the same thing or might -have changed their meaning. - -On top of that, some register settings have effect only when the touchpad is -in relative mode and not in absolute mode. As the Linux Elantech touchpad -driver always puts the hardware into absolute mode not all information -mentioned below can be used immediately. But because there is no freely -available Elantech documentation the information is provided here anyway for -completeness sake. - - -///////////////////////////////////////////////////////////////////////////// - - -2. Extra knobs - ~~~~~~~~~~~ - -Currently the Linux Elantech touchpad driver provides two extra knobs under -/sys/bus/serio/drivers/psmouse/serio? for the user. - -* debug - - Turn different levels of debugging ON or OFF. - - By echoing "0" to this file all debugging will be turned OFF. - - Currently a value of "1" will turn on some basic debugging and a value of - "2" will turn on packet debugging. For hardware version 1 the default is - OFF. For version 2 the default is "1". - - Turning packet debugging on will make the driver dump every packet - received to the syslog before processing it. Be warned that this can - generate quite a lot of data! - -* paritycheck - - Turns parity checking ON or OFF. - - By echoing "0" to this file parity checking will be turned OFF. Any - non-zero value will turn it ON. For hardware version 1 the default is ON. - For version 2 the default it is OFF. - - Hardware version 1 provides basic data integrity verification by - calculating a parity bit for the last 3 bytes of each packet. The driver - can check these bits and reject any packet that appears corrupted. Using - this knob you can bypass that check. - - Hardware version 2 does not provide the same parity bits. Only some basic - data consistency checking can be done. For now checking is disabled by - default. Currently even turning it on will do nothing. - -///////////////////////////////////////////////////////////////////////////// - -3. Differentiating hardware versions - ================================= - -To detect the hardware version, read the version number as param[0].param[1].param[2] - - 4 bytes version: (after the arrow is the name given in the Dell-provided driver) - 02.00.22 => EF013 - 02.06.00 => EF019 -In the wild, there appear to be more versions, such as 00.01.64, 01.00.21, -02.00.00, 02.00.04, 02.00.06. - - 6 bytes: - 02.00.30 => EF113 - 02.08.00 => EF023 - 02.08.XX => EF123 - 02.0B.00 => EF215 - 04.01.XX => Scroll_EF051 - 04.02.XX => EF051 -In the wild, there appear to be more versions, such as 04.03.01, 04.04.11. There -appears to be almost no difference, except for EF113, which does not report -pressure/width and has different data consistency checks. - -Probably all the versions with param[0] <= 01 can be considered as -4 bytes/firmware 1. The versions < 02.08.00, with the exception of 02.00.30, as -4 bytes/firmware 2. Everything >= 02.08.00 can be considered as 6 bytes. - -///////////////////////////////////////////////////////////////////////////// - -4. Hardware version 1 - ================== - -4.1 Registers - ~~~~~~~~~ - -By echoing a hexadecimal value to a register it contents can be altered. - -For example: - - echo -n 0x16 > reg_10 - -* reg_10 - - bit 7 6 5 4 3 2 1 0 - B C T D L A S E - - E: 1 = enable smart edges unconditionally - S: 1 = enable smart edges only when dragging - A: 1 = absolute mode (needs 4 byte packets, see reg_11) - L: 1 = enable drag lock (see reg_22) - D: 1 = disable dynamic resolution - T: 1 = disable tapping - C: 1 = enable corner tap - B: 1 = swap left and right button - -* reg_11 - - bit 7 6 5 4 3 2 1 0 - 1 0 0 H V 1 F P - - P: 1 = enable parity checking for relative mode - F: 1 = enable native 4 byte packet mode - V: 1 = enable vertical scroll area - H: 1 = enable horizontal scroll area - -* reg_20 - - single finger width? - -* reg_21 - - scroll area width (small: 0x40 ... wide: 0xff) - -* reg_22 - - drag lock time out (short: 0x14 ... long: 0xfe; - 0xff = tap again to release) - -* reg_23 - - tap make timeout? - -* reg_24 - - tap release timeout? - -* reg_25 - - smart edge cursor speed (0x02 = slow, 0x03 = medium, 0x04 = fast) - -* reg_26 - - smart edge activation area width? - - -4.2 Native relative mode 4 byte packet format - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -byte 0: - bit 7 6 5 4 3 2 1 0 - c c p2 p1 1 M R L - - L, R, M = 1 when Left, Right, Middle mouse button pressed - some models have M as byte 3 odd parity bit - when parity checking is enabled (reg_11, P = 1): - p1..p2 = byte 1 and 2 odd parity bit - c = 1 when corner tap detected - -byte 1: - bit 7 6 5 4 3 2 1 0 - dx7 dx6 dx5 dx4 dx3 dx2 dx1 dx0 - - dx7..dx0 = x movement; positive = right, negative = left - byte 1 = 0xf0 when corner tap detected - -byte 2: - bit 7 6 5 4 3 2 1 0 - dy7 dy6 dy5 dy4 dy3 dy2 dy1 dy0 - - dy7..dy0 = y movement; positive = up, negative = down - -byte 3: - parity checking enabled (reg_11, P = 1): - - bit 7 6 5 4 3 2 1 0 - w h n1 n0 ds3 ds2 ds1 ds0 - - normally: - ds3..ds0 = scroll wheel amount and direction - positive = down or left - negative = up or right - when corner tap detected: - ds0 = 1 when top right corner tapped - ds1 = 1 when bottom right corner tapped - ds2 = 1 when bottom left corner tapped - ds3 = 1 when top left corner tapped - n1..n0 = number of fingers on touchpad - only models with firmware 2.x report this, models with - firmware 1.x seem to map one, two and three finger taps - directly to L, M and R mouse buttons - h = 1 when horizontal scroll action - w = 1 when wide finger touch? - - otherwise (reg_11, P = 0): - - bit 7 6 5 4 3 2 1 0 - ds7 ds6 ds5 ds4 ds3 ds2 ds1 ds0 - - ds7..ds0 = vertical scroll amount and direction - negative = up - positive = down - - -4.3 Native absolute mode 4 byte packet format - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -EF013 and EF019 have a special behaviour (due to a bug in the firmware?), and -when 1 finger is touching, the first 2 position reports must be discarded. -This counting is reset whenever a different number of fingers is reported. - -byte 0: - firmware version 1.x: - - bit 7 6 5 4 3 2 1 0 - D U p1 p2 1 p3 R L - - L, R = 1 when Left, Right mouse button pressed - p1..p3 = byte 1..3 odd parity bit - D, U = 1 when rocker switch pressed Up, Down - - firmware version 2.x: - - bit 7 6 5 4 3 2 1 0 - n1 n0 p2 p1 1 p3 R L - - L, R = 1 when Left, Right mouse button pressed - p1..p3 = byte 1..3 odd parity bit - n1..n0 = number of fingers on touchpad - -byte 1: - firmware version 1.x: - - bit 7 6 5 4 3 2 1 0 - f 0 th tw x9 x8 y9 y8 - - tw = 1 when two finger touch - th = 1 when three finger touch - f = 1 when finger touch - - firmware version 2.x: - - bit 7 6 5 4 3 2 1 0 - . . . . x9 x8 y9 y8 - -byte 2: - bit 7 6 5 4 3 2 1 0 - x7 x6 x5 x4 x3 x2 x1 x0 - - x9..x0 = absolute x value (horizontal) - -byte 3: - bit 7 6 5 4 3 2 1 0 - y7 y6 y5 y4 y3 y2 y1 y0 - - y9..y0 = absolute y value (vertical) - - -///////////////////////////////////////////////////////////////////////////// - - -5. Hardware version 2 - ================== - - -5.1 Registers - ~~~~~~~~~ - -By echoing a hexadecimal value to a register it contents can be altered. - -For example: - - echo -n 0x56 > reg_10 - -* reg_10 - - bit 7 6 5 4 3 2 1 0 - 0 1 0 1 0 1 D 0 - - D: 1 = enable drag and drop - -* reg_11 - - bit 7 6 5 4 3 2 1 0 - 1 0 0 0 S 0 1 0 - - S: 1 = enable vertical scroll - -* reg_21 - - unknown (0x00) - -* reg_22 - - drag and drop release time out (short: 0x70 ... long 0x7e; - 0x7f = never i.e. tap again to release) - - -5.2 Native absolute mode 6 byte packet format - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -5.2.1 Parity checking and packet re-synchronization -There is no parity checking, however some consistency checks can be performed. - -For instance for EF113: - SA1= packet[0]; - A1 = packet[1]; - B1 = packet[2]; - SB1= packet[3]; - C1 = packet[4]; - D1 = packet[5]; - if( (((SA1 & 0x3C) != 0x3C) && ((SA1 & 0xC0) != 0x80)) || // check Byte 1 - (((SA1 & 0x0C) != 0x0C) && ((SA1 & 0xC0) == 0x80)) || // check Byte 1 (one finger pressed) - (((SA1 & 0xC0) != 0x80) && (( A1 & 0xF0) != 0x00)) || // check Byte 2 - (((SB1 & 0x3E) != 0x38) && ((SA1 & 0xC0) != 0x80)) || // check Byte 4 - (((SB1 & 0x0E) != 0x08) && ((SA1 & 0xC0) == 0x80)) || // check Byte 4 (one finger pressed) - (((SA1 & 0xC0) != 0x80) && (( C1 & 0xF0) != 0x00)) ) // check Byte 5 - // error detected - -For all the other ones, there are just a few constant bits: - if( ((packet[0] & 0x0C) != 0x04) || - ((packet[3] & 0x0f) != 0x02) ) - // error detected - - -In case an error is detected, all the packets are shifted by one (and packet[0] is discarded). - -5.2.2 One/Three finger touch - ~~~~~~~~~~~~~~~~ - -byte 0: - - bit 7 6 5 4 3 2 1 0 - n1 n0 w3 w2 . . R L - - L, R = 1 when Left, Right mouse button pressed - n1..n0 = number of fingers on touchpad - -byte 1: - - bit 7 6 5 4 3 2 1 0 - p7 p6 p5 p4 x11 x10 x9 x8 - -byte 2: - - bit 7 6 5 4 3 2 1 0 - x7 x6 x5 x4 x3 x2 x1 x0 - - x11..x0 = absolute x value (horizontal) - -byte 3: - - bit 7 6 5 4 3 2 1 0 - n4 vf w1 w0 . . . b2 - - n4 = set if more than 3 fingers (only in 3 fingers mode) - vf = a kind of flag ? (only on EF123, 0 when finger is over one - of the buttons, 1 otherwise) - w3..w0 = width of the finger touch (not EF113) - b2 (on EF113 only, 0 otherwise), b2.R.L indicates one button pressed: - 0 = none - 1 = Left - 2 = Right - 3 = Middle (Left and Right) - 4 = Forward - 5 = Back - 6 = Another one - 7 = Another one - -byte 4: - - bit 7 6 5 4 3 2 1 0 - p3 p1 p2 p0 y11 y10 y9 y8 - - p7..p0 = pressure (not EF113) - -byte 5: - - bit 7 6 5 4 3 2 1 0 - y7 y6 y5 y4 y3 y2 y1 y0 - - y11..y0 = absolute y value (vertical) - - -5.2.3 Two finger touch - ~~~~~~~~~~~~~~~~ - -Note that the two pairs of coordinates are not exactly the coordinates of the -two fingers, but only the pair of the lower-left and upper-right coordinates. -So the actual fingers might be situated on the other diagonal of the square -defined by these two points. - -byte 0: - - bit 7 6 5 4 3 2 1 0 - n1 n0 ay8 ax8 . . R L - - L, R = 1 when Left, Right mouse button pressed - n1..n0 = number of fingers on touchpad - -byte 1: - - bit 7 6 5 4 3 2 1 0 - ax7 ax6 ax5 ax4 ax3 ax2 ax1 ax0 - - ax8..ax0 = lower-left finger absolute x value - -byte 2: - - bit 7 6 5 4 3 2 1 0 - ay7 ay6 ay5 ay4 ay3 ay2 ay1 ay0 - - ay8..ay0 = lower-left finger absolute y value - -byte 3: - - bit 7 6 5 4 3 2 1 0 - . . by8 bx8 . . . . - -byte 4: - - bit 7 6 5 4 3 2 1 0 - bx7 bx6 bx5 bx4 bx3 bx2 bx1 bx0 - - bx8..bx0 = upper-right finger absolute x value - -byte 5: - - bit 7 6 5 4 3 2 1 0 - by7 by8 by5 by4 by3 by2 by1 by0 - - by8..by0 = upper-right finger absolute y value - -///////////////////////////////////////////////////////////////////////////// - -6. Hardware version 3 - ================== - -6.1 Registers - ~~~~~~~~~ -* reg_10 - - bit 7 6 5 4 3 2 1 0 - 0 0 0 0 0 0 0 A - - A: 1 = enable absolute tracking - -6.2 Native absolute mode 6 byte packet format - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -1 and 3 finger touch shares the same 6-byte packet format, except that -3 finger touch only reports the position of the center of all three fingers. - -Firmware would send 12 bytes of data for 2 finger touch. - -Note on debounce: -In case the box has unstable power supply or other electricity issues, or -when number of finger changes, F/W would send "debounce packet" to inform -driver that the hardware is in debounce status. -The debouce packet has the following signature: - byte 0: 0xc4 - byte 1: 0xff - byte 2: 0xff - byte 3: 0x02 - byte 4: 0xff - byte 5: 0xff -When we encounter this kind of packet, we just ignore it. - -6.2.1 One/Three finger touch - ~~~~~~~~~~~~~~~~~~~~~~ - -byte 0: - - bit 7 6 5 4 3 2 1 0 - n1 n0 w3 w2 0 1 R L - - L, R = 1 when Left, Right mouse button pressed - n1..n0 = number of fingers on touchpad - -byte 1: - - bit 7 6 5 4 3 2 1 0 - p7 p6 p5 p4 x11 x10 x9 x8 - -byte 2: - - bit 7 6 5 4 3 2 1 0 - x7 x6 x5 x4 x3 x2 x1 x0 - - x11..x0 = absolute x value (horizontal) - -byte 3: - - bit 7 6 5 4 3 2 1 0 - 0 0 w1 w0 0 0 1 0 - - w3..w0 = width of the finger touch - -byte 4: - - bit 7 6 5 4 3 2 1 0 - p3 p1 p2 p0 y11 y10 y9 y8 - - p7..p0 = pressure - -byte 5: - - bit 7 6 5 4 3 2 1 0 - y7 y6 y5 y4 y3 y2 y1 y0 - - y11..y0 = absolute y value (vertical) - -6.2.2 Two finger touch - ~~~~~~~~~~~~~~~~ - -The packet format is exactly the same for two finger touch, except the hardware -sends two 6 byte packets. The first packet contains data for the first finger, -the second packet has data for the second finger. So for two finger touch a -total of 12 bytes are sent. - -///////////////////////////////////////////////////////////////////////////// - -7. Hardware version 4 - ================== - -7.1 Registers - ~~~~~~~~~ -* reg_07 - - bit 7 6 5 4 3 2 1 0 - 0 0 0 0 0 0 0 A - - A: 1 = enable absolute tracking - -7.2 Native absolute mode 6 byte packet format - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -v4 hardware is a true multitouch touchpad, capable of tracking up to 5 fingers. -Unfortunately, due to PS/2's limited bandwidth, its packet format is rather -complex. - -Whenever the numbers or identities of the fingers changes, the hardware sends a -status packet to indicate how many and which fingers is on touchpad, followed by -head packets or motion packets. A head packet contains data of finger id, finger -position (absolute x, y values), width, and pressure. A motion packet contains -two fingers' position delta. - -For example, when status packet tells there are 2 fingers on touchpad, then we -can expect two following head packets. If the finger status doesn't change, -the following packets would be motion packets, only sending delta of finger -position, until we receive a status packet. - -One exception is one finger touch. when a status packet tells us there is only -one finger, the hardware would just send head packets afterwards. - -7.2.1 Status packet - ~~~~~~~~~~~~~ - -byte 0: - - bit 7 6 5 4 3 2 1 0 - . . . . 0 1 R L - - L, R = 1 when Left, Right mouse button pressed - -byte 1: - - bit 7 6 5 4 3 2 1 0 - . . . ft4 ft3 ft2 ft1 ft0 - - ft4 ft3 ft2 ft1 ft0 ftn = 1 when finger n is on touchpad - -byte 2: not used - -byte 3: - - bit 7 6 5 4 3 2 1 0 - . . . 1 0 0 0 0 - - constant bits - -byte 4: - - bit 7 6 5 4 3 2 1 0 - p . . . . . . . - - p = 1 for palm - -byte 5: not used - -7.2.2 Head packet - ~~~~~~~~~~~ - -byte 0: - - bit 7 6 5 4 3 2 1 0 - w3 w2 w1 w0 0 1 R L - - L, R = 1 when Left, Right mouse button pressed - w3..w0 = finger width (spans how many trace lines) - -byte 1: - - bit 7 6 5 4 3 2 1 0 - p7 p6 p5 p4 x11 x10 x9 x8 - -byte 2: - - bit 7 6 5 4 3 2 1 0 - x7 x6 x5 x4 x3 x2 x1 x0 - - x11..x0 = absolute x value (horizontal) - -byte 3: - - bit 7 6 5 4 3 2 1 0 - id2 id1 id0 1 0 0 0 1 - - id2..id0 = finger id - -byte 4: - - bit 7 6 5 4 3 2 1 0 - p3 p1 p2 p0 y11 y10 y9 y8 - - p7..p0 = pressure - -byte 5: - - bit 7 6 5 4 3 2 1 0 - y7 y6 y5 y4 y3 y2 y1 y0 - - y11..y0 = absolute y value (vertical) - -7.2.3 Motion packet - ~~~~~~~~~~~~~ - -byte 0: - - bit 7 6 5 4 3 2 1 0 - id2 id1 id0 w 0 1 R L - - L, R = 1 when Left, Right mouse button pressed - id2..id0 = finger id - w = 1 when delta overflows (> 127 or < -128), in this case - firmware sends us (delta x / 5) and (delta y / 5) - -byte 1: - - bit 7 6 5 4 3 2 1 0 - x7 x6 x5 x4 x3 x2 x1 x0 - - x7..x0 = delta x (two's complement) - -byte 2: - - bit 7 6 5 4 3 2 1 0 - y7 y6 y5 y4 y3 y2 y1 y0 - - y7..y0 = delta y (two's complement) - -byte 3: - - bit 7 6 5 4 3 2 1 0 - id2 id1 id0 1 0 0 1 0 - - id2..id0 = finger id - -byte 4: - - bit 7 6 5 4 3 2 1 0 - x7 x6 x5 x4 x3 x2 x1 x0 - - x7..x0 = delta x (two's complement) - -byte 5: - - bit 7 6 5 4 3 2 1 0 - y7 y6 y5 y4 y3 y2 y1 y0 - - y7..y0 = delta y (two's complement) - - byte 0 ~ 2 for one finger - byte 3 ~ 5 for another diff --git a/Documentation/input/event-codes.txt b/Documentation/input/event-codes.txt deleted file mode 100644 index 53305bd0818..00000000000 --- a/Documentation/input/event-codes.txt +++ /dev/null @@ -1,318 +0,0 @@ -The input protocol uses a map of types and codes to express input device values -to userspace. This document describes the types and codes and how and when they -may be used. - -A single hardware event generates multiple input events. Each input event -contains the new value of a single data item. A special event type, EV_SYN, is -used to separate input events into packets of input data changes occurring at -the same moment in time. In the following, the term "event" refers to a single -input event encompassing a type, code, and value. - -The input protocol is a stateful protocol. Events are emitted only when values -of event codes have changed. However, the state is maintained within the Linux -input subsystem; drivers do not need to maintain the state and may attempt to -emit unchanged values without harm. Userspace may obtain the current state of -event code values using the EVIOCG* ioctls defined in linux/input.h. The event -reports supported by a device are also provided by sysfs in -class/input/event*/device/capabilities/, and the properties of a device are -provided in class/input/event*/device/properties. - -Event types: -=========== -Event types are groupings of codes under a logical input construct. Each -type has a set of applicable codes to be used in generating events. See the -Codes section for details on valid codes for each type. - -* EV_SYN: - - Used as markers to separate events. Events may be separated in time or in - space, such as with the multitouch protocol. - -* EV_KEY: - - Used to describe state changes of keyboards, buttons, or other key-like - devices. - -* EV_REL: - - Used to describe relative axis value changes, e.g. moving the mouse 5 units - to the left. - -* EV_ABS: - - Used to describe absolute axis value changes, e.g. describing the - coordinates of a touch on a touchscreen. - -* EV_MSC: - - Used to describe miscellaneous input data that do not fit into other types. - -* EV_SW: - - Used to describe binary state input switches. - -* EV_LED: - - Used to turn LEDs on devices on and off. - -* EV_SND: - - Used to output sound to devices. - -* EV_REP: - - Used for autorepeating devices. - -* EV_FF: - - Used to send force feedback commands to an input device. - -* EV_PWR: - - A special type for power button and switch input. - -* EV_FF_STATUS: - - Used to receive force feedback device status. - -Event codes: -=========== -Event codes define the precise type of event. - -EV_SYN: ----------- -EV_SYN event values are undefined. Their usage is defined only by when they are -sent in the evdev event stream. - -* SYN_REPORT: - - Used to synchronize and separate events into packets of input data changes - occurring at the same moment in time. For example, motion of a mouse may set - the REL_X and REL_Y values for one motion, then emit a SYN_REPORT. The next - motion will emit more REL_X and REL_Y values and send another SYN_REPORT. - -* SYN_CONFIG: - - TBD - -* SYN_MT_REPORT: - - Used to synchronize and separate touch events. See the - multi-touch-protocol.txt document for more information. - -* SYN_DROPPED: - - Used to indicate buffer overrun in the evdev client's event queue. - Client should ignore all events up to and including next SYN_REPORT - event and query the device (using EVIOCG* ioctls) to obtain its - current state. - -EV_KEY: ----------- -EV_KEY events take the form KEY_<name> or BTN_<name>. For example, KEY_A is used -to represent the 'A' key on a keyboard. When a key is depressed, an event with -the key's code is emitted with value 1. When the key is released, an event is -emitted with value 0. Some hardware send events when a key is repeated. These -events have a value of 2. In general, KEY_<name> is used for keyboard keys, and -BTN_<name> is used for other types of momentary switch events. - -A few EV_KEY codes have special meanings: - -* BTN_TOOL_<name>: - - These codes are used in conjunction with input trackpads, tablets, and - touchscreens. These devices may be used with fingers, pens, or other tools. - When an event occurs and a tool is used, the corresponding BTN_TOOL_<name> - code should be set to a value of 1. When the tool is no longer interacting - with the input device, the BTN_TOOL_<name> code should be reset to 0. All - trackpads, tablets, and touchscreens should use at least one BTN_TOOL_<name> - code when events are generated. - -* BTN_TOUCH: - BTN_TOUCH is used for touch contact. While an input tool is determined to be - within meaningful physical contact, the value of this property must be set - to 1. Meaningful physical contact may mean any contact, or it may mean - contact conditioned by an implementation defined property. For example, a - touchpad may set the value to 1 only when the touch pressure rises above a - certain value. BTN_TOUCH may be combined with BTN_TOOL_<name> codes. For - example, a pen tablet may set BTN_TOOL_PEN to 1 and BTN_TOUCH to 0 while the - pen is hovering over but not touching the tablet surface. - -Note: For appropriate function of the legacy mousedev emulation driver, -BTN_TOUCH must be the first evdev code emitted in a synchronization frame. - -Note: Historically a touch device with BTN_TOOL_FINGER and BTN_TOUCH was -interpreted as a touchpad by userspace, while a similar device without -BTN_TOOL_FINGER was interpreted as a touchscreen. For backwards compatibility -with current userspace it is recommended to follow this distinction. In the -future, this distinction will be deprecated and the device properties ioctl -EVIOCGPROP, defined in linux/input.h, will be used to convey the device type. - -* BTN_TOOL_FINGER, BTN_TOOL_DOUBLETAP, BTN_TOOL_TRIPLETAP, BTN_TOOL_QUADTAP: - - These codes denote one, two, three, and four finger interaction on a - trackpad or touchscreen. For example, if the user uses two fingers and moves - them on the touchpad in an effort to scroll content on screen, - BTN_TOOL_DOUBLETAP should be set to value 1 for the duration of the motion. - Note that all BTN_TOOL_<name> codes and the BTN_TOUCH code are orthogonal in - purpose. A trackpad event generated by finger touches should generate events - for one code from each group. At most only one of these BTN_TOOL_<name> - codes should have a value of 1 during any synchronization frame. - -Note: Historically some drivers emitted multiple of the finger count codes with -a value of 1 in the same synchronization frame. This usage is deprecated. - -Note: In multitouch drivers, the input_mt_report_finger_count() function should -be used to emit these codes. Please see multi-touch-protocol.txt for details. - -EV_REL: ----------- -EV_REL events describe relative changes in a property. For example, a mouse may -move to the left by a certain number of units, but its absolute position in -space is unknown. If the absolute position is known, EV_ABS codes should be used -instead of EV_REL codes. - -A few EV_REL codes have special meanings: - -* REL_WHEEL, REL_HWHEEL: - - These codes are used for vertical and horizontal scroll wheels, - respectively. - -EV_ABS: ----------- -EV_ABS events describe absolute changes in a property. For example, a touchpad -may emit coordinates for a touch location. - -A few EV_ABS codes have special meanings: - -* ABS_DISTANCE: - - Used to describe the distance of a tool from an interaction surface. This - event should only be emitted while the tool is hovering, meaning in close - proximity of the device and while the value of the BTN_TOUCH code is 0. If - the input device may be used freely in three dimensions, consider ABS_Z - instead. - -* ABS_MT_<name>: - - Used to describe multitouch input events. Please see - multi-touch-protocol.txt for details. - -EV_SW: ----------- -EV_SW events describe stateful binary switches. For example, the SW_LID code is -used to denote when a laptop lid is closed. - -Upon binding to a device or resuming from suspend, a driver must report -the current switch state. This ensures that the device, kernel, and userspace -state is in sync. - -Upon resume, if the switch state is the same as before suspend, then the input -subsystem will filter out the duplicate switch state reports. The driver does -not need to keep the state of the switch at any time. - -EV_MSC: ----------- -EV_MSC events are used for input and output events that do not fall under other -categories. - -EV_LED: ----------- -EV_LED events are used for input and output to set and query the state of -various LEDs on devices. - -EV_REP: ----------- -EV_REP events are used for specifying autorepeating events. - -EV_SND: ----------- -EV_SND events are used for sending sound commands to simple sound output -devices. - -EV_FF: ----------- -EV_FF events are used to initialize a force feedback capable device and to cause -such device to feedback. - -EV_PWR: ----------- -EV_PWR events are a special type of event used specifically for power -mangement. Its usage is not well defined. To be addressed later. - -Device properties: -================= -Normally, userspace sets up an input device based on the data it emits, -i.e., the event types. In the case of two devices emitting the same event -types, additional information can be provided in the form of device -properties. - -INPUT_PROP_DIRECT + INPUT_PROP_POINTER: --------------------------------------- -The INPUT_PROP_DIRECT property indicates that device coordinates should be -directly mapped to screen coordinates (not taking into account trivial -transformations, such as scaling, flipping and rotating). Non-direct input -devices require non-trivial transformation, such as absolute to relative -transformation for touchpads. Typical direct input devices: touchscreens, -drawing tablets; non-direct devices: touchpads, mice. - -The INPUT_PROP_POINTER property indicates that the device is not transposed -on the screen and thus requires use of an on-screen pointer to trace user's -movements. Typical pointer devices: touchpads, tablets, mice; non-pointer -device: touchscreen. - -If neither INPUT_PROP_DIRECT or INPUT_PROP_POINTER are set, the property is -considered undefined and the device type should be deduced in the -traditional way, using emitted event types. - -INPUT_PROP_BUTTONPAD: --------------------- -For touchpads where the button is placed beneath the surface, such that -pressing down on the pad causes a button click, this property should be -set. Common in clickpad notebooks and macbooks from 2009 and onwards. - -Originally, the buttonpad property was coded into the bcm5974 driver -version field under the name integrated button. For backwards -compatibility, both methods need to be checked in userspace. - -INPUT_PROP_SEMI_MT: ------------------- -Some touchpads, most common between 2008 and 2011, can detect the presence -of multiple contacts without resolving the individual positions; only the -number of contacts and a rectangular shape is known. For such -touchpads, the semi-mt property should be set. - -Depending on the device, the rectangle may enclose all touches, like a -bounding box, or just some of them, for instance the two most recent -touches. The diversity makes the rectangle of limited use, but some -gestures can normally be extracted from it. - -If INPUT_PROP_SEMI_MT is not set, the device is assumed to be a true MT -device. - -Guidelines: -========== -The guidelines below ensure proper single-touch and multi-finger functionality. -For multi-touch functionality, see the multi-touch-protocol.txt document for -more information. - -Mice: ----------- -REL_{X,Y} must be reported when the mouse moves. BTN_LEFT must be used to report -the primary button press. BTN_{MIDDLE,RIGHT,4,5,etc.} should be used to report -further buttons of the device. REL_WHEEL and REL_HWHEEL should be used to report -scroll wheel events where available. - -Touchscreens: ----------- -ABS_{X,Y} must be reported with the location of the touch. BTN_TOUCH must be -used to report when a touch is active on the screen. -BTN_{MOUSE,LEFT,MIDDLE,RIGHT} must not be reported as the result of touch -contact. BTN_TOOL_<name> events should be reported where possible. - -For new hardware, INPUT_PROP_DIRECT should be set. - -Trackpads: ----------- -Legacy trackpads that only provide relative position information must report -events like mice described above. - -Trackpads that provide absolute touch position must report ABS_{X,Y} for the -location of the touch. BTN_TOUCH should be used to report when a touch is active -on the trackpad. Where multi-finger support is available, BTN_TOOL_<name> should -be used to report the number of touches active on the trackpad. - -For new hardware, INPUT_PROP_POINTER should be set. - -Tablets: ----------- -BTN_TOOL_<name> events must be reported when a stylus or other tool is active on -the tablet. ABS_{X,Y} must be reported with the location of the tool. BTN_TOUCH -should be used to report when the tool is in contact with the tablet. -BTN_{STYLUS,STYLUS2} should be used to report buttons on the tool itself. Any -button may be used for buttons on the tablet except BTN_{MOUSE,LEFT}. -BTN_{0,1,2,etc} are good generic codes for unlabeled buttons. Do not use -meaningful buttons, like BTN_FORWARD, unless the button is labeled for that -purpose on the device. - -For new hardware, both INPUT_PROP_DIRECT and INPUT_PROP_POINTER should be set. diff --git a/Documentation/input/ff.txt b/Documentation/input/ff.txt deleted file mode 100644 index b3867bf49f8..00000000000 --- a/Documentation/input/ff.txt +++ /dev/null @@ -1,221 +0,0 @@ -Force feedback for Linux. -By Johann Deneux <johann.deneux@gmail.com> on 2001/04/22. -Updated by Anssi Hannula <anssi.hannula@gmail.com> on 2006/04/09. -You may redistribute this file. Please remember to include shape.fig and -interactive.fig as well. ----------------------------------------------------------------------------- - -1. 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. -This document only describes the force feedback part of the Linux input -interface. Please read joystick.txt and input.txt before reading further this -document. - -2. Instructions to the user -~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To enable force feedback, you have to: - -1. have your kernel configured with evdev and a driver that supports your - device. -2. make sure evdev module is loaded and /dev/input/event* device files are - created. - -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 break down if -something goes wrong. - -If you have a serial iforce device, you need to start inputattach. See -joystick.txt for details. - -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 developer -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -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 <linux/input.h> -#include <sys/ioctl.h> - -#define BITS_TO_LONGS(x) \ - (((x) + 8 * sizeof (unsigned long) - 1) / (8 * sizeof (unsigned long))) -unsigned long features[BITS_TO_LONGS(FF_CNT)]; -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_CONSTANT can render constant force effects -- FF_PERIODIC can render periodic effects with the following waveforms: - - FF_SQUARE square waveform - - FF_TRIANGLE triangle waveform - - FF_SINE sine waveform - - FF_SAW_UP sawtooth up waveform - - FF_SAW_DOWN sawtooth down waveform - - FF_CUSTOM custom waveform -- 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 -- FF_INERTIA can simulate inertia -- FF_GAIN gain is adjustable -- FF_AUTOCENTER autocenter is adjustable - -Note: In most cases you should use FF_PERIODIC instead of FF_RUMBLE. All - devices that support FF_RUMBLE support FF_PERIODIC (square, triangle, - sine) and the other way around. - -Note: The exact syntax FF_CUSTOM is undefined for the time being as no driver - supports it yet. - - -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 <linux/input.h> -#include <sys/ioctl.h> - -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. - -Effects are file descriptor specific. - -See <linux/input.h> for a description of the ff_effect struct. 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. Note that this also -stops 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 <linux/input.h> -#include <unistd.h> - - 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. - -/* 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. - -Therefore it is recommended to dynamically change direction while the effect -is playing only when it is ok to restart the effect with a replay count of 1. - -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 - -NOTE: Status feedback is only supported by iforce driver. If you have - a really good reason to use this, please contact - linux-joystick@atrey.karlin.mff.cuni.cz or anssi.hannula@gmail.com - so that support for it can be added to the rest of the drivers. - diff --git a/Documentation/input/gameport-programming.txt b/Documentation/input/gameport-programming.txt deleted file mode 100644 index 03a74fc3b49..00000000000 --- a/Documentation/input/gameport-programming.txt +++ /dev/null @@ -1,187 +0,0 @@ -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 to program the hardware to, starting from the more exotic -addresses is preferred, because the likelihood 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/gpio-tilt.txt b/Documentation/input/gpio-tilt.txt deleted file mode 100644 index 06d60c3ff5e..00000000000 --- a/Documentation/input/gpio-tilt.txt +++ /dev/null @@ -1,103 +0,0 @@ -Driver for tilt-switches connected via GPIOs -============================================ - -Generic driver to read data from tilt switches connected via gpios. -Orientation can be provided by one or more than one tilt switches, -i.e. each tilt switch providing one axis, and the number of axes -is also not limited. - - -Data structures: ----------------- - -The array of struct gpio in the gpios field is used to list the gpios -that represent the current tilt state. - -The array of struct gpio_tilt_axis describes the axes that are reported -to the input system. The values set therein are used for the -input_set_abs_params calls needed to init the axes. - -The array of struct gpio_tilt_state maps gpio states to the corresponding -values to report. The gpio state is represented as a bitfield where the -bit-index corresponds to the index of the gpio in the struct gpio array. -In the same manner the values stored in the axes array correspond to -the elements of the gpio_tilt_axis-array. - - -Example: --------- - -Example configuration for a single TS1003 tilt switch that rotates around -one axis in 4 steps and emitts the current tilt via two GPIOs. - -static int sg060_tilt_enable(struct device *dev) { - /* code to enable the sensors */ -}; - -static void sg060_tilt_disable(struct device *dev) { - /* code to disable the sensors */ -}; - -static struct gpio sg060_tilt_gpios[] = { - { SG060_TILT_GPIO_SENSOR1, GPIOF_IN, "tilt_sensor1" }, - { SG060_TILT_GPIO_SENSOR2, GPIOF_IN, "tilt_sensor2" }, -}; - -static struct gpio_tilt_state sg060_tilt_states[] = { - { - .gpios = (0 << 1) | (0 << 0), - .axes = (int[]) { - 0, - }, - }, { - .gpios = (0 << 1) | (1 << 0), - .axes = (int[]) { - 1, /* 90 degrees */ - }, - }, { - .gpios = (1 << 1) | (1 << 0), - .axes = (int[]) { - 2, /* 180 degrees */ - }, - }, { - .gpios = (1 << 1) | (0 << 0), - .axes = (int[]) { - 3, /* 270 degrees */ - }, - }, -}; - -static struct gpio_tilt_axis sg060_tilt_axes[] = { - { - .axis = ABS_RY, - .min = 0, - .max = 3, - .fuzz = 0, - .flat = 0, - }, -}; - -static struct gpio_tilt_platform_data sg060_tilt_pdata= { - .gpios = sg060_tilt_gpios, - .nr_gpios = ARRAY_SIZE(sg060_tilt_gpios), - - .axes = sg060_tilt_axes, - .nr_axes = ARRAY_SIZE(sg060_tilt_axes), - - .states = sg060_tilt_states, - .nr_states = ARRAY_SIZE(sg060_tilt_states), - - .debounce_interval = 100, - - .poll_interval = 1000, - .enable = sg060_tilt_enable, - .disable = sg060_tilt_disable, -}; - -static struct platform_device sg060_device_tilt = { - .name = "gpio-tilt-polled", - .id = -1, - .dev = { - .platform_data = &sg060_tilt_pdata, - }, -}; diff --git a/Documentation/input/iforce-protocol.txt b/Documentation/input/iforce-protocol.txt deleted file mode 100644 index 2d5fbfd6023..00000000000 --- a/Documentation/input/iforce-protocol.txt +++ /dev/null @@ -1,258 +0,0 @@ -** 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: johann.deneux@gmail.com - -** WARNING ** -I shall not be held responsible for any damage 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 -responses 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 additional 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 <idx> <val> [<val>] -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 <val> -LEN= 1 -00 State - Bit 3 Pause force feedback - Bit 2 Enable force feedback - Bit 0 Stop all effects - -**** Set overall gain **** -OP= 43 <val> -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 software seems, hum, well... buggy. In fact, data appear with a -few seconds latency. Personally, 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 <johann.deneux@gmail.com> -Home page at http://web.archive.org/web/*/http://www.esil.univ-mrs.fr - -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 deleted file mode 100644 index 7f8b9d97bc4..00000000000 --- a/Documentation/input/input-programming.txt +++ /dev/null @@ -1,302 +0,0 @@ -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 <linux/input.h> -#include <linux/module.h> -#include <linux/init.h> - -#include <asm/irq.h> -#include <asm/io.h> - -static struct input_dev *button_dev; - -static irqreturn_t button_interrupt(int irq, void *dummy) -{ - input_report_key(button_dev, BTN_0, inb(BUTTON_PORT) & 1); - input_sync(button_dev); - return IRQ_HANDLED; -} - -static int __init button_init(void) -{ - int error; - - 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 = input_allocate_device(); - if (!button_dev) { - printk(KERN_ERR "button.c: Not enough memory\n"); - error = -ENOMEM; - goto err_free_irq; - } - - button_dev->evbit[0] = BIT_MASK(EV_KEY); - button_dev->keybit[BIT_WORD(BTN_0)] = BIT_MASK(BTN_0); - - error = input_register_device(button_dev); - if (error) { - printk(KERN_ERR "button.c: Failed to register device\n"); - goto err_free_dev; - } - - return 0; - - err_free_dev: - input_free_device(button_dev); - err_free_irq: - free_irq(BUTTON_IRQ, button_interrupt); - return error; -} - -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 <linux/input.h> 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 allocates a new input device structure with input_allocate_device() -and sets up 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. input_register_device() may sleep and therefore 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: - -static int button_open(struct input_dev *dev) -{ - 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; - } - - return 0; -} - -static void button_close(struct input_dev *dev) -{ - free_irq(IRQ_AMIGA_VERTB, button_interrupt); -} - -static int __init button_init(void) -{ - ... - button_dev->open = button_open; - button_dev->close = button_close; - ... -} - -Note that input core keeps track of number of users for the device and -makes sure that dev->open() is called only when the first user connects -to the device and that dev->close() is called when the very last user -disconnects. Calls to both callbacks are serialized. - -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; - -Or, you can just say: - - input_set_abs_params(button_dev, ABS_X, 0, 255, 4, 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 BITS_TO_LONGS(), BIT_WORD(), BIT_MASK() -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -These three macros from bitops.h help some bitfield computations: - - BITS_TO_LONGS(x) - returns the length of a bitfield array in longs for - x bits - BIT_WORD(x) - returns the index in the array in longs for bit x - BIT_MASK(x) - returns the index in a long for bit x - -1.5 The id* and name fields -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -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.6 The keycode, keycodemax, keycodesize fields -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -These three fields should be used by input devices that have dense keymaps. -The keycode is an array used to map from scancodes to input system keycodes. -The keycode max should contain the size of the array and keycodesize the -size of each entry in it (in bytes). - -Userspace can query and alter current scancode to keycode mappings using -EVIOCGKEYCODE and EVIOCSKEYCODE ioctls on corresponding evdev interface. -When a device has all 3 aforementioned fields filled in, the driver may -rely on kernel's default implementation of setting and querying keycode -mappings. - -1.7 dev->getkeycode() and dev->setkeycode() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -getkeycode() and setkeycode() callbacks allow drivers to override default -keycode/keycodesize/keycodemax mapping mechanism provided by input core -and implement sparse keycode maps. - -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 deleted file mode 100644 index 666c06c5ab0..00000000000 --- a/Documentation/input/input.txt +++ /dev/null @@ -1,290 +0,0 @@ - Linux Input drivers v1.0 - (c) 1999-2001 Vojtech Pavlik <vojtech@ucw.cz> - Sponsored by SuSE ----------------------------------------------------------------------------- - -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 <vojtech@ucw.cz>, 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. - The commands to 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/hid/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 distribute 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 -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 <vojtech@ucw.cz> 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 moment, EV_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. - diff --git a/Documentation/input/interactive.fig b/Documentation/input/interactive.fig deleted file mode 100644 index 1e7de387723..00000000000 --- a/Documentation/input/interactive.fig +++ /dev/null @@ -1,42 +0,0 @@ -#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 deleted file mode 100644 index c507330740c..00000000000 --- a/Documentation/input/joystick-api.txt +++ /dev/null @@ -1,314 +0,0 @@ - Joystick API Documentation -*-Text-*- - - Ragnar Hojland Espinosa - <ragnar@macula.net> - - 7 Aug 1998 - -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 deleted file mode 100644 index 56870c70a79..00000000000 --- a/Documentation/input/joystick-parport.txt +++ /dev/null @@ -1,542 +0,0 @@ - Linux Joystick parport drivers v2.0 - (c) 1998-2000 Vojtech Pavlik <vojtech@ucw.cz> - (c) 1998 Andree Borrmann <a.borrmann@tu-bs.de> - Sponsored by SuSE ----------------------------------------------------------------------------- - -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 and/or SNES mice 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, SNES gamepads and SNES mice. - - 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) ----|>|-------+ - | - <and so on> : - | -(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 and mice - - +----> 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 between. - - 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 <schwenke@burg-halle.de> - - 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 - 9 | SNES mouse - - The exact type of the PSX controller type is autoprobed when used, so -hot swapping should work (but is not recommended). - - 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 performance. If your pads don't -respond try raising it until 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 deleted file mode 100644 index 304262bb661..00000000000 --- a/Documentation/input/joystick.txt +++ /dev/null @@ -1,586 +0,0 @@ - Linux Joystick driver v2.0.0 - (c) 1996-2000 Vojtech Pavlik <vojtech@ucw.cz> - Sponsored by SuSE ----------------------------------------------------------------------------- - -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 <vojtech@ucw.cz>, 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://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, -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=<type1>,<type2>,<type3>,.... - - 'type' is type of the joystick from the table below, defining joysticks -present on gameports in the system, starting with gameport0, second 'type' -entry defining joystick on gameport1 and so on. - - Type | Meaning - ----------------------------------- - none | No analog joystick on that port - auto | Autodetect joystick - 2btn | 2-button n-axis joystick - y-joy | Two 2-button 2-axis joysticks on an Y-cable - y-pad | Two 2-button 2-axis gamepads on an Y-cable - fcs | Thrustmaster FCS compatible joystick - chf | Joystick with a CH Flightstick compatible hat - fullchf | CH Flightstick compatible with two hats and 6 buttons - gamepad | 4/6-button n-axis gamepad - gamepad8 | 8-button 2-axis gamepad - - In case your joystick doesn't fit in any of the above categories, you can -specify the type as a number by combining the bits in the table below. This -is not recommended unless you really know what are you doing. It's not -dangerous, but not simple either. - - Bit | Meaning - -------------------------- - 0 | Axis X1 - 1 | Axis Y1 - 2 | Axis X2 - 3 | Axis Y2 - 4 | Button A - 5 | Button B - 6 | Button C - 7 | Button D - 8 | CHF Buttons X and Y - 9 | CHF Hat 1 - 10 | CHF Hat 2 - 11 | FCS Hat - 12 | Pad Button X - 13 | Pad Button Y - 14 | Pad Button U - 15 | Pad Button V - 16 | Saitek F1-F4 Buttons - 17 | Saitek Digital Mode - 19 | GamePad - 20 | Joy2 Axis X1 - 21 | Joy2 Axis Y1 - 22 | Joy2 Axis X2 - 23 | Joy2 Axis Y2 - 24 | Joy2 Button A - 25 | Joy2 Button B - 26 | Joy2 Button C - 27 | Joy2 Button D - 31 | Joy2 GamePad - -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 Millennium 3D Interceptor -* ThrustMaster 3D Rage Pad -* ThrustMaster Fusion Digital Game Pad - - Devices not directly supported, but hopefully working are: - -* ThrustMaster FragMaster -* ThrustMaster Attack Throttle - - If you have one of these, contact me. - - TMDC devices are autodetected, and thus no parameters to the module -are needed. Up to two TMDC devices can be connected to one gameport, using -an Y-cable. - -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 -its 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>,<b> - - a and b define the joysticks connected to the JOY0DAT and JOY1DAT ports of -the Amiga. - - Value | Joystick type - --------------------- - 0 | None - 1 | 1-button digital joystick - - No more joystick types are supported now, but that should change in the -future if I get an Amiga in the reach of my fingers. - -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/multi-touch-protocol.txt b/Documentation/input/multi-touch-protocol.txt deleted file mode 100644 index 543101c5bf2..00000000000 --- a/Documentation/input/multi-touch-protocol.txt +++ /dev/null @@ -1,347 +0,0 @@ -Multi-touch (MT) Protocol -------------------------- - Copyright (C) 2009-2010 Henrik Rydberg <rydberg@euromail.se> - - -Introduction ------------- - -In order to utilize the full power of the new multi-touch and multi-user -devices, a way to report detailed data from multiple contacts, i.e., -objects in direct contact with the device surface, is needed. This -document describes the multi-touch (MT) protocol which allows kernel -drivers to report details for an arbitrary number of contacts. - -The protocol is divided into two types, depending on the capabilities of the -hardware. For devices handling anonymous contacts (type A), the protocol -describes how to send the raw data for all contacts to the receiver. For -devices capable of tracking identifiable contacts (type B), the protocol -describes how to send updates for individual contacts via event slots. - - -Protocol Usage --------------- - -Contact details are sent sequentially as separate packets of ABS_MT -events. Only the ABS_MT events are recognized as part of a contact -packet. Since these events are ignored by current single-touch (ST) -applications, the MT protocol can be implemented on top of the ST protocol -in an existing driver. - -Drivers for type A devices separate contact packets by calling -input_mt_sync() at the end of each packet. This generates a SYN_MT_REPORT -event, which instructs the receiver to accept the data for the current -contact and prepare to receive another. - -Drivers for type B devices separate contact packets by calling -input_mt_slot(), with a slot as argument, at the beginning of each packet. -This generates an ABS_MT_SLOT event, which instructs the receiver to -prepare for updates of the given slot. - -All drivers mark the end of a multi-touch transfer by calling the usual -input_sync() function. This instructs the receiver to act upon events -accumulated since last EV_SYN/SYN_REPORT and prepare to receive a new set -of events/packets. - -The main difference between the stateless type A protocol and the stateful -type B slot protocol lies in the usage of identifiable contacts to reduce -the amount of data sent to userspace. The slot protocol requires the use of -the ABS_MT_TRACKING_ID, either provided by the hardware or computed from -the raw data [5]. - -For type A devices, the kernel driver should generate an arbitrary -enumeration of the full set of anonymous contacts currently on the -surface. The order in which the packets appear in the event stream is not -important. Event filtering and finger tracking is left to user space [3]. - -For type B devices, the kernel driver should associate a slot with each -identified contact, and use that slot to propagate changes for the contact. -Creation, replacement and destruction of contacts is achieved by modifying -the ABS_MT_TRACKING_ID of the associated slot. A non-negative tracking id -is interpreted as a contact, and the value -1 denotes an unused slot. A -tracking id not previously present is considered new, and a tracking id no -longer present is considered removed. Since only changes are propagated, -the full state of each initiated contact has to reside in the receiving -end. Upon receiving an MT event, one simply updates the appropriate -attribute of the current slot. - -Some devices identify and/or track more contacts than they can report to the -driver. A driver for such a device should associate one type B slot with each -contact that is reported by the hardware. Whenever the identity of the -contact associated with a slot changes, the driver should invalidate that -slot by changing its ABS_MT_TRACKING_ID. If the hardware signals that it is -tracking more contacts than it is currently reporting, the driver should use -a BTN_TOOL_*TAP event to inform userspace of the total number of contacts -being tracked by the hardware at that moment. The driver should do this by -explicitly sending the corresponding BTN_TOOL_*TAP event and setting -use_count to false when calling input_mt_report_pointer_emulation(). -The driver should only advertise as many slots as the hardware can report. -Userspace can detect that a driver can report more total contacts than slots -by noting that the largest supported BTN_TOOL_*TAP event is larger than the -total number of type B slots reported in the absinfo for the ABS_MT_SLOT axis. - -Protocol Example A ------------------- - -Here is what a minimal event sequence for a two-contact touch would look -like for a type A device: - - ABS_MT_POSITION_X x[0] - ABS_MT_POSITION_Y y[0] - SYN_MT_REPORT - ABS_MT_POSITION_X x[1] - ABS_MT_POSITION_Y y[1] - SYN_MT_REPORT - SYN_REPORT - -The sequence after moving one of the contacts looks exactly the same; the -raw data for all present contacts are sent between every synchronization -with SYN_REPORT. - -Here is the sequence after lifting the first contact: - - ABS_MT_POSITION_X x[1] - ABS_MT_POSITION_Y y[1] - SYN_MT_REPORT - SYN_REPORT - -And here is the sequence after lifting the second contact: - - SYN_MT_REPORT - SYN_REPORT - -If the driver reports one of BTN_TOUCH or ABS_PRESSURE in addition to the -ABS_MT events, the last SYN_MT_REPORT event may be omitted. Otherwise, the -last SYN_REPORT will be dropped by the input core, resulting in no -zero-contact event reaching userland. - - -Protocol Example B ------------------- - -Here is what a minimal event sequence for a two-contact touch would look -like for a type B device: - - ABS_MT_SLOT 0 - ABS_MT_TRACKING_ID 45 - ABS_MT_POSITION_X x[0] - ABS_MT_POSITION_Y y[0] - ABS_MT_SLOT 1 - ABS_MT_TRACKING_ID 46 - ABS_MT_POSITION_X x[1] - ABS_MT_POSITION_Y y[1] - SYN_REPORT - -Here is the sequence after moving contact 45 in the x direction: - - ABS_MT_SLOT 0 - ABS_MT_POSITION_X x[0] - SYN_REPORT - -Here is the sequence after lifting the contact in slot 0: - - ABS_MT_TRACKING_ID -1 - SYN_REPORT - -The slot being modified is already 0, so the ABS_MT_SLOT is omitted. The -message removes the association of slot 0 with contact 45, thereby -destroying contact 45 and freeing slot 0 to be reused for another contact. - -Finally, here is the sequence after lifting the second contact: - - ABS_MT_SLOT 1 - ABS_MT_TRACKING_ID -1 - SYN_REPORT - - -Event Usage ------------ - -A set of ABS_MT events with the desired properties is defined. The events -are divided into categories, to allow for partial implementation. The -minimum set consists of ABS_MT_POSITION_X and ABS_MT_POSITION_Y, which -allows for multiple contacts to be tracked. If the device supports it, the -ABS_MT_TOUCH_MAJOR and ABS_MT_WIDTH_MAJOR may be used to provide the size -of the contact area and approaching contact, respectively. - -The TOUCH and WIDTH parameters have a geometrical interpretation; imagine -looking through a window at someone gently holding a finger against the -glass. You will see two regions, one inner region consisting of the part -of the finger actually touching the glass, and one outer region formed by -the perimeter of the finger. The diameter of the inner region is the -ABS_MT_TOUCH_MAJOR, the diameter of the outer region is -ABS_MT_WIDTH_MAJOR. Now imagine the person pressing the finger harder -against the glass. The inner region will increase, and in general, the -ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR, which is always smaller than -unity, is related to the contact pressure. For pressure-based devices, -ABS_MT_PRESSURE may be used to provide the pressure on the contact area -instead. Devices capable of contact hovering can use ABS_MT_DISTANCE to -indicate the distance between the contact and the surface. - -In addition to the MAJOR parameters, the oval shape of the contact can be -described by adding the MINOR parameters, such that MAJOR and MINOR are the -major and minor axis of an ellipse. Finally, the orientation of the oval -shape can be describe with the ORIENTATION parameter. - -For type A devices, further specification of the touch shape is possible -via ABS_MT_BLOB_ID. - -The ABS_MT_TOOL_TYPE may be used to specify whether the touching tool is a -finger or a pen or something else. Finally, the ABS_MT_TRACKING_ID event -may be used to track identified contacts over time [5]. - -In the type B protocol, ABS_MT_TOOL_TYPE and ABS_MT_TRACKING_ID are -implicitly handled by input core; drivers should instead call -input_mt_report_slot_state(). - - -Event Semantics ---------------- - -ABS_MT_TOUCH_MAJOR - -The length of the major axis of the contact. The length should be given in -surface units. If the surface has an X times Y resolution, the largest -possible value of ABS_MT_TOUCH_MAJOR is sqrt(X^2 + Y^2), the diagonal [4]. - -ABS_MT_TOUCH_MINOR - -The length, in surface units, of the minor axis of the contact. If the -contact is circular, this event can be omitted [4]. - -ABS_MT_WIDTH_MAJOR - -The length, in surface units, of the major axis of the approaching -tool. This should be understood as the size of the tool itself. The -orientation of the contact and the approaching tool are assumed to be the -same [4]. - -ABS_MT_WIDTH_MINOR - -The length, in surface units, of the minor axis of the approaching -tool. Omit if circular [4]. - -The above four values can be used to derive additional information about -the contact. The ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR approximates -the notion of pressure. The fingers of the hand and the palm all have -different characteristic widths [1]. - -ABS_MT_PRESSURE - -The pressure, in arbitrary units, on the contact area. May be used instead -of TOUCH and WIDTH for pressure-based devices or any device with a spatial -signal intensity distribution. - -ABS_MT_DISTANCE - -The distance, in surface units, between the contact and the surface. Zero -distance means the contact is touching the surface. A positive number means -the contact is hovering above the surface. - -ABS_MT_ORIENTATION - -The orientation of the ellipse. The value should describe a signed quarter -of a revolution clockwise around the touch center. The signed value range -is arbitrary, but zero should be returned for a finger aligned along the Y -axis of the surface, a negative value when finger is turned to the left, and -a positive value when finger turned to the right. When completely aligned with -the X axis, the range max should be returned. Orientation can be omitted -if the touching object is circular, or if the information is not available -in the kernel driver. Partial orientation support is possible if the device -can distinguish between the two axis, but not (uniquely) any values in -between. In such cases, the range of ABS_MT_ORIENTATION should be [0, 1] -[4]. - -ABS_MT_POSITION_X - -The surface X coordinate of the center of the touching ellipse. - -ABS_MT_POSITION_Y - -The surface Y coordinate of the center of the touching ellipse. - -ABS_MT_TOOL_TYPE - -The type of approaching tool. A lot of kernel drivers cannot distinguish -between different tool types, such as a finger or a pen. In such cases, the -event should be omitted. The protocol currently supports MT_TOOL_FINGER and -MT_TOOL_PEN [2]. For type B devices, this event is handled by input core; -drivers should instead use input_mt_report_slot_state(). - -ABS_MT_BLOB_ID - -The BLOB_ID groups several packets together into one arbitrarily shaped -contact. The sequence of points forms a polygon which defines the shape of -the contact. This is a low-level anonymous grouping for type A devices, and -should not be confused with the high-level trackingID [5]. Most type A -devices do not have blob capability, so drivers can safely omit this event. - -ABS_MT_TRACKING_ID - -The TRACKING_ID identifies an initiated contact throughout its life cycle -[5]. The value range of the TRACKING_ID should be large enough to ensure -unique identification of a contact maintained over an extended period of -time. For type B devices, this event is handled by input core; drivers -should instead use input_mt_report_slot_state(). - - -Event Computation ------------------ - -The flora of different hardware unavoidably leads to some devices fitting -better to the MT protocol than others. To simplify and unify the mapping, -this section gives recipes for how to compute certain events. - -For devices reporting contacts as rectangular shapes, signed orientation -cannot be obtained. Assuming X and Y are the lengths of the sides of the -touching rectangle, here is a simple formula that retains the most -information possible: - - ABS_MT_TOUCH_MAJOR := max(X, Y) - ABS_MT_TOUCH_MINOR := min(X, Y) - ABS_MT_ORIENTATION := bool(X > Y) - -The range of ABS_MT_ORIENTATION should be set to [0, 1], to indicate that -the device can distinguish between a finger along the Y axis (0) and a -finger along the X axis (1). - - -Finger Tracking ---------------- - -The process of finger tracking, i.e., to assign a unique trackingID to each -initiated contact on the surface, is a Euclidian Bipartite Matching -problem. At each event synchronization, the set of actual contacts is -matched to the set of contacts from the previous synchronization. A full -implementation can be found in [3]. - - -Gestures --------- - -In the specific application of creating gesture events, the TOUCH and WIDTH -parameters can be used to, e.g., approximate finger pressure or distinguish -between index finger and thumb. With the addition of the MINOR parameters, -one can also distinguish between a sweeping finger and a pointing finger, -and with ORIENTATION, one can detect twisting of fingers. - - -Notes ------ - -In order to stay compatible with existing applications, the data reported -in a finger packet must not be recognized as single-touch events. - -For type A devices, all finger data bypasses input filtering, since -subsequent events of the same type refer to different fingers. - -For example usage of the type A protocol, see the bcm5974 driver. For -example usage of the type B protocol, see the hid-egalax driver. - -[1] With the extension ABS_MT_APPROACH_X and ABS_MT_APPROACH_Y, the -difference between the contact position and the approaching tool position -could be used to derive tilt. -[2] The list can of course be extended. -[3] The mtdev project: http://bitmath.org/code/mtdev/. -[4] See the section on event computation. -[5] See the section on finger tracking. diff --git a/Documentation/input/notifier.txt b/Documentation/input/notifier.txt deleted file mode 100644 index 95172ca6f3d..00000000000 --- a/Documentation/input/notifier.txt +++ /dev/null @@ -1,52 +0,0 @@ -Keyboard notifier - -One can use register_keyboard_notifier to get called back on keyboard -events (see kbd_keycode() function for details). The passed structure is -keyboard_notifier_param: - -- 'vc' always provide the VC for which the keyboard event applies; -- 'down' is 1 for a key press event, 0 for a key release; -- 'shift' is the current modifier state, mask bit indexes are KG_*; -- 'value' depends on the type of event. - -- KBD_KEYCODE events are always sent before other events, value is the keycode. -- KBD_UNBOUND_KEYCODE events are sent if the keycode is not bound to a keysym. - value is the keycode. -- KBD_UNICODE events are sent if the keycode -> keysym translation produced a - unicode character. value is the unicode value. -- KBD_KEYSYM events are sent if the keycode -> keysym translation produced a - non-unicode character. value is the keysym. -- KBD_POST_KEYSYM events are sent after the treatment of non-unicode keysyms. - That permits one to inspect the resulting LEDs for instance. - -For each kind of event but the last, the callback may return NOTIFY_STOP in -order to "eat" the event: the notify loop is stopped and the keyboard event is -dropped. - -In a rough C snippet, we have: - -kbd_keycode(keycode) { - ... - params.value = keycode; - if (notifier_call_chain(KBD_KEYCODE,¶ms) == NOTIFY_STOP) - || !bound) { - notifier_call_chain(KBD_UNBOUND_KEYCODE,¶ms); - return; - } - - if (unicode) { - param.value = unicode; - if (notifier_call_chain(KBD_UNICODE,¶ms) == NOTIFY_STOP) - return; - emit unicode; - return; - } - - params.value = keysym; - if (notifier_call_chain(KBD_KEYSYM,¶ms) == NOTIFY_STOP) - return; - apply keysym; - notifier_call_chain(KBD_POST_KEYSYM,¶ms); -} - -NOTE: This notifier is usually called from interrupt context. diff --git a/Documentation/input/ntrig.txt b/Documentation/input/ntrig.txt deleted file mode 100644 index be1fd981f73..00000000000 --- a/Documentation/input/ntrig.txt +++ /dev/null @@ -1,126 +0,0 @@ -N-Trig touchscreen Driver -------------------------- - Copyright (c) 2008-2010 Rafi Rubin <rafi@seas.upenn.edu> - Copyright (c) 2009-2010 Stephane Chatty - -This driver provides support for N-Trig pen and multi-touch sensors. Single -and multi-touch events are translated to the appropriate protocols for -the hid and input systems. Pen events are sufficiently hid compliant and -are left to the hid core. The driver also provides additional filtering -and utility functions accessible with sysfs and module parameters. - -This driver has been reported to work properly with multiple N-Trig devices -attached. - - -Parameters ----------- - -Note: values set at load time are global and will apply to all applicable -devices. Adjusting parameters with sysfs will override the load time values, -but only for that one device. - -The following parameters are used to configure filters to reduce noise: - -activate_slack number of fingers to ignore before processing events - -activation_height size threshold to activate immediately -activation_width - -min_height size threshold bellow which fingers are ignored -min_width both to decide activation and during activity - -deactivate_slack the number of "no contact" frames to ignore before - propagating the end of activity events - -When the last finger is removed from the device, it sends a number of empty -frames. By holding off on deactivation for a few frames we can tolerate false -erroneous disconnects, where the sensor may mistakenly not detect a finger that -is still present. Thus deactivate_slack addresses problems where a users might -see breaks in lines during drawing, or drop an object during a long drag. - - -Additional sysfs items ----------------------- - -These nodes just provide easy access to the ranges reported by the device. -sensor_logical_height the range for positions reported during activity -sensor_logical_width - -sensor_physical_height internal ranges not used for normal events but -sensor_physical_width useful for tuning - -All N-Trig devices with product id of 1 report events in the ranges of -X: 0-9600 -Y: 0-7200 -However not all of these devices have the same physical dimensions. Most -seem to be 12" sensors (Dell Latitude XT and XT2 and the HP TX2), and -at least one model (Dell Studio 17) has a 17" sensor. The ratio of physical -to logical sizes is used to adjust the size based filter parameters. - - -Filtering ---------- - -With the release of the early multi-touch firmwares it became increasingly -obvious that these sensors were prone to erroneous events. Users reported -seeing both inappropriately dropped contact and ghosts, contacts reported -where no finger was actually touching the screen. - -Deactivation slack helps prevent dropped contact for single touch use, but does -not address the problem of dropping one of more contacts while other contacts -are still active. Drops in the multi-touch context require additional -processing and should be handled in tandem with tacking. - -As observed ghost contacts are similar to actual use of the sensor, but they -seem to have different profiles. Ghost activity typically shows up as small -short lived touches. As such, I assume that the longer the continuous stream -of events the more likely those events are from a real contact, and that the -larger the size of each contact the more likely it is real. Balancing the -goals of preventing ghosts and accepting real events quickly (to minimize -user observable latency), the filter accumulates confidence for incoming -events until it hits thresholds and begins propagating. In the interest in -minimizing stored state as well as the cost of operations to make a decision, -I've kept that decision simple. - -Time is measured in terms of the number of fingers reported, not frames since -the probability of multiple simultaneous ghosts is expected to drop off -dramatically with increasing numbers. Rather than accumulate weight as a -function of size, I just use it as a binary threshold. A sufficiently large -contact immediately overrides the waiting period and leads to activation. - -Setting the activation size thresholds to large values will result in deciding -primarily on activation slack. If you see longer lived ghosts, turning up the -activation slack while reducing the size thresholds may suffice to eliminate -the ghosts while keeping the screen quite responsive to firm taps. - -Contacts continue to be filtered with min_height and min_width even after -the initial activation filter is satisfied. The intent is to provide -a mechanism for filtering out ghosts in the form of an extra finger while -you actually are using the screen. In practice this sort of ghost has -been far less problematic or relatively rare and I've left the defaults -set to 0 for both parameters, effectively turning off that filter. - -I don't know what the optimal values are for these filters. If the defaults -don't work for you, please play with the parameters. If you do find other -values more comfortable, I would appreciate feedback. - -The calibration of these devices does drift over time. If ghosts or contact -dropping worsen and interfere with the normal usage of your device, try -recalibrating it. - - -Calibration ------------ - -The N-Trig windows tools provide calibration and testing routines. Also an -unofficial unsupported set of user space tools including a calibrator is -available at: -http://code.launchpad.net/~rafi-seas/+junk/ntrig_calib - - -Tracking --------- - -As of yet, all tested N-Trig firmwares do not track fingers. When multiple -contacts are active they seem to be sorted primarily by Y position. diff --git a/Documentation/input/rotary-encoder.txt b/Documentation/input/rotary-encoder.txt deleted file mode 100644 index 92e68bce13a..00000000000 --- a/Documentation/input/rotary-encoder.txt +++ /dev/null @@ -1,121 +0,0 @@ -rotary-encoder - a generic driver for GPIO connected devices -Daniel Mack <daniel@caiaq.de>, Feb 2009 - -0. Function ------------ - -Rotary encoders are devices which are connected to the CPU or other -peripherals with two wires. The outputs are phase-shifted by 90 degrees -and by triggering on falling and rising edges, the turn direction can -be determined. - -Some encoders have both outputs low in stable states, whereas others also have -a stable state with both outputs high (half-period mode). - -The phase diagram of these two outputs look like this: - - _____ _____ _____ - | | | | | | - Channel A ____| |_____| |_____| |____ - - : : : : : : : : : : : : - __ _____ _____ _____ - | | | | | | | - Channel B |_____| |_____| |_____| |__ - - : : : : : : : : : : : : - Event a b c d a b c d a b c d - - |<-------->| - one step - - |<-->| - one step (half-period mode) - -For more information, please see - http://en.wikipedia.org/wiki/Rotary_encoder - - -1. Events / state machine -------------------------- - -In half-period mode, state a) and c) above are used to determine the -rotational direction based on the last stable state. Events are reported in -states b) and d) given that the new stable state is different from the last -(i.e. the rotation was not reversed half-way). - -Otherwise, the following apply: - -a) Rising edge on channel A, channel B in low state - This state is used to recognize a clockwise turn - -b) Rising edge on channel B, channel A in high state - When entering this state, the encoder is put into 'armed' state, - meaning that there it has seen half the way of a one-step transition. - -c) Falling edge on channel A, channel B in high state - This state is used to recognize a counter-clockwise turn - -d) Falling edge on channel B, channel A in low state - Parking position. If the encoder enters this state, a full transition - should have happened, unless it flipped back on half the way. The - 'armed' state tells us about that. - -2. Platform requirements ------------------------- - -As there is no hardware dependent call in this driver, the platform it is -used with must support gpiolib. Another requirement is that IRQs must be -able to fire on both edges. - - -3. Board integration --------------------- - -To use this driver in your system, register a platform_device with the -name 'rotary-encoder' and associate the IRQs and some specific platform -data with it. - -struct rotary_encoder_platform_data is declared in -include/linux/rotary-encoder.h and needs to be filled with the number of -steps the encoder has and can carry information about externally inverted -signals (because of an inverting buffer or other reasons). The encoder -can be set up to deliver input information as either an absolute or relative -axes. For relative axes the input event returns +/-1 for each step. For -absolute axes the position of the encoder can either roll over between zero -and the number of steps or will clamp at the maximum and zero depending on -the configuration. - -Because GPIO to IRQ mapping is platform specific, this information must -be given in separately to the driver. See the example below. - ----------<snip>--------- - -/* board support file example */ - -#include <linux/input.h> -#include <linux/rotary_encoder.h> - -#define GPIO_ROTARY_A 1 -#define GPIO_ROTARY_B 2 - -static struct rotary_encoder_platform_data my_rotary_encoder_info = { - .steps = 24, - .axis = ABS_X, - .relative_axis = false, - .rollover = false, - .gpio_a = GPIO_ROTARY_A, - .gpio_b = GPIO_ROTARY_B, - .inverted_a = 0, - .inverted_b = 0, - .half_period = false, -}; - -static struct platform_device rotary_encoder_device = { - .name = "rotary-encoder", - .id = 0, - .dev = { - .platform_data = &my_rotary_encoder_info, - } -}; - diff --git a/Documentation/input/sentelic.txt b/Documentation/input/sentelic.txt deleted file mode 100644 index 89251e2a3eb..00000000000 --- a/Documentation/input/sentelic.txt +++ /dev/null @@ -1,873 +0,0 @@ -Copyright (C) 2002-2011 Sentelic Corporation. -Last update: Dec-07-2011 - -============================================================================== -* Finger Sensing Pad Intellimouse Mode(scrolling wheel, 4th and 5th buttons) -============================================================================== -A) MSID 4: Scrolling wheel mode plus Forward page(4th button) and Backward - page (5th button) -@1. Set sample rate to 200; -@2. Set sample rate to 200; -@3. Set sample rate to 80; -@4. Issuing the "Get device ID" command (0xF2) and waits for the response; -@5. FSP will respond 0x04. - -Packet 1 - Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 -BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| - 1 |Y|X|y|x|1|M|R|L| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 | | |B|F|W|W|W|W| - |---------------| |---------------| |---------------| |---------------| - -Byte 1: Bit7 => Y overflow - Bit6 => X overflow - Bit5 => Y sign bit - Bit4 => X sign bit - Bit3 => 1 - Bit2 => Middle Button, 1 is pressed, 0 is not pressed. - Bit1 => Right Button, 1 is pressed, 0 is not pressed. - Bit0 => Left Button, 1 is pressed, 0 is not pressed. -Byte 2: X Movement(9-bit 2's complement integers) -Byte 3: Y Movement(9-bit 2's complement integers) -Byte 4: Bit3~Bit0 => the scrolling wheel's movement since the last data report. - valid values, -8 ~ +7 - Bit4 => 1 = 4th mouse button is pressed, Forward one page. - 0 = 4th mouse button is not pressed. - Bit5 => 1 = 5th mouse button is pressed, Backward one page. - 0 = 5th mouse button is not pressed. - -B) MSID 6: Horizontal and Vertical scrolling. -@ Set bit 1 in register 0x40 to 1 - -# FSP replaces scrolling wheel's movement as 4 bits to show horizontal and - vertical scrolling. - -Packet 1 - Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 -BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| - 1 |Y|X|y|x|1|M|R|L| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 | | |B|F|r|l|u|d| - |---------------| |---------------| |---------------| |---------------| - -Byte 1: Bit7 => Y overflow - Bit6 => X overflow - Bit5 => Y sign bit - Bit4 => X sign bit - Bit3 => 1 - Bit2 => Middle Button, 1 is pressed, 0 is not pressed. - Bit1 => Right Button, 1 is pressed, 0 is not pressed. - Bit0 => Left Button, 1 is pressed, 0 is not pressed. -Byte 2: X Movement(9-bit 2's complement integers) -Byte 3: Y Movement(9-bit 2's complement integers) -Byte 4: Bit0 => the Vertical scrolling movement downward. - Bit1 => the Vertical scrolling movement upward. - Bit2 => the Horizontal scrolling movement leftward. - Bit3 => the Horizontal scrolling movement rightward. - Bit4 => 1 = 4th mouse button is pressed, Forward one page. - 0 = 4th mouse button is not pressed. - Bit5 => 1 = 5th mouse button is pressed, Backward one page. - 0 = 5th mouse button is not pressed. - -C) MSID 7: -# FSP uses 2 packets (8 Bytes) to represent Absolute Position. - so we have PACKET NUMBER to identify packets. - If PACKET NUMBER is 0, the packet is Packet 1. - If PACKET NUMBER is 1, the packet is Packet 2. - Please count this number in program. - -# MSID6 special packet will be enable at the same time when enable MSID 7. - -============================================================================== -* Absolute position for STL3886-G0. -============================================================================== -@ Set bit 2 or 3 in register 0x40 to 1 -@ Set bit 6 in register 0x40 to 1 - -Packet 1 (ABSOLUTE POSITION) - Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 -BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| - 1 |0|1|V|1|1|M|R|L| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 |r|l|d|u|X|X|Y|Y| - |---------------| |---------------| |---------------| |---------------| - -Byte 1: Bit7~Bit6 => 00, Normal data packet - => 01, Absolute coordination packet - => 10, Notify packet - Bit5 => valid bit - Bit4 => 1 - Bit3 => 1 - Bit2 => Middle Button, 1 is pressed, 0 is not pressed. - Bit1 => Right Button, 1 is pressed, 0 is not pressed. - Bit0 => Left Button, 1 is pressed, 0 is not pressed. -Byte 2: X coordinate (xpos[9:2]) -Byte 3: Y coordinate (ypos[9:2]) -Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0]) - Bit3~Bit2 => X coordinate (ypos[1:0]) - Bit4 => scroll up - Bit5 => scroll down - Bit6 => scroll left - Bit7 => scroll right - -Notify Packet for G0 - Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 -BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| - 1 |1|0|0|1|1|M|R|L| 2 |C|C|C|C|C|C|C|C| 3 |M|M|M|M|M|M|M|M| 4 |0|0|0|0|0|0|0|0| - |---------------| |---------------| |---------------| |---------------| - -Byte 1: Bit7~Bit6 => 00, Normal data packet - => 01, Absolute coordination packet - => 10, Notify packet - Bit5 => 0 - Bit4 => 1 - Bit3 => 1 - Bit2 => Middle Button, 1 is pressed, 0 is not pressed. - Bit1 => Right Button, 1 is pressed, 0 is not pressed. - Bit0 => Left Button, 1 is pressed, 0 is not pressed. -Byte 2: Message Type => 0x5A (Enable/Disable status packet) - Mode Type => 0xA5 (Normal/Icon mode status) -Byte 3: Message Type => 0x00 (Disabled) - => 0x01 (Enabled) - Mode Type => 0x00 (Normal) - => 0x01 (Icon) -Byte 4: Bit7~Bit0 => Don't Care - -============================================================================== -* Absolute position for STL3888-Ax. -============================================================================== -Packet 1 (ABSOLUTE POSITION) - Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 -BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| - 1 |0|1|V|A|1|L|0|1| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 |x|x|y|y|X|X|Y|Y| - |---------------| |---------------| |---------------| |---------------| - -Byte 1: Bit7~Bit6 => 00, Normal data packet - => 01, Absolute coordination packet - => 10, Notify packet - => 11, Normal data packet with on-pad click - Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up. - When both fingers are up, the last two reports have zero valid - bit. - Bit4 => arc - Bit3 => 1 - Bit2 => Left Button, 1 is pressed, 0 is released. - Bit1 => 0 - Bit0 => 1 -Byte 2: X coordinate (xpos[9:2]) -Byte 3: Y coordinate (ypos[9:2]) -Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0]) - Bit3~Bit2 => X coordinate (ypos[1:0]) - Bit5~Bit4 => y1_g - Bit7~Bit6 => x1_g - -Packet 2 (ABSOLUTE POSITION) - Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 -BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| - 1 |0|1|V|A|1|R|1|0| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 |x|x|y|y|X|X|Y|Y| - |---------------| |---------------| |---------------| |---------------| - -Byte 1: Bit7~Bit6 => 00, Normal data packet - => 01, Absolute coordinates packet - => 10, Notify packet - => 11, Normal data packet with on-pad click - Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up. - When both fingers are up, the last two reports have zero valid - bit. - Bit4 => arc - Bit3 => 1 - Bit2 => Right Button, 1 is pressed, 0 is released. - Bit1 => 1 - Bit0 => 0 -Byte 2: X coordinate (xpos[9:2]) -Byte 3: Y coordinate (ypos[9:2]) -Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0]) - Bit3~Bit2 => X coordinate (ypos[1:0]) - Bit5~Bit4 => y2_g - Bit7~Bit6 => x2_g - -Notify Packet for STL3888-Ax - Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 -BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| - 1 |1|0|1|P|1|M|R|L| 2 |C|C|C|C|C|C|C|C| 3 |0|0|F|F|0|0|0|i| 4 |r|l|d|u|0|0|0|0| - |---------------| |---------------| |---------------| |---------------| - -Byte 1: Bit7~Bit6 => 00, Normal data packet - => 01, Absolute coordinates packet - => 10, Notify packet - => 11, Normal data packet with on-pad click - Bit5 => 1 - Bit4 => when in absolute coordinates mode (valid when EN_PKT_GO is 1): - 0: left button is generated by the on-pad command - 1: left button is generated by the external button - Bit3 => 1 - Bit2 => Middle Button, 1 is pressed, 0 is not pressed. - Bit1 => Right Button, 1 is pressed, 0 is not pressed. - Bit0 => Left Button, 1 is pressed, 0 is not pressed. -Byte 2: Message Type => 0xB7 (Multi Finger, Multi Coordinate mode) -Byte 3: Bit7~Bit6 => Don't care - Bit5~Bit4 => Number of fingers - Bit3~Bit1 => Reserved - Bit0 => 1: enter gesture mode; 0: leaving gesture mode -Byte 4: Bit7 => scroll right button - Bit6 => scroll left button - Bit5 => scroll down button - Bit4 => scroll up button - * Note that if gesture and additional button (Bit4~Bit7) - happen at the same time, the button information will not - be sent. - Bit3~Bit0 => Reserved - -Sample sequence of Multi-finger, Multi-coordinate mode: - - notify packet (valid bit == 1), abs pkt 1, abs pkt 2, abs pkt 1, - abs pkt 2, ..., notify packet (valid bit == 0) - -============================================================================== -* Absolute position for STL3888-B0. -============================================================================== -Packet 1(ABSOLUTE POSITION) - Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 -BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| - 1 |0|1|V|F|1|0|R|L| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 |r|l|u|d|X|X|Y|Y| - |---------------| |---------------| |---------------| |---------------| - -Byte 1: Bit7~Bit6 => 00, Normal data packet - => 01, Absolute coordinates packet - => 10, Notify packet - => 11, Normal data packet with on-pad click - Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up. - When both fingers are up, the last two reports have zero valid - bit. - Bit4 => finger up/down information. 1: finger down, 0: finger up. - Bit3 => 1 - Bit2 => finger index, 0 is the first finger, 1 is the second finger. - Bit1 => Right Button, 1 is pressed, 0 is not pressed. - Bit0 => Left Button, 1 is pressed, 0 is not pressed. -Byte 2: X coordinate (xpos[9:2]) -Byte 3: Y coordinate (ypos[9:2]) -Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0]) - Bit3~Bit2 => X coordinate (ypos[1:0]) - Bit4 => scroll down button - Bit5 => scroll up button - Bit6 => scroll left button - Bit7 => scroll right button - -Packet 2 (ABSOLUTE POSITION) - Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 -BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| - 1 |0|1|V|F|1|1|R|L| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 |r|l|u|d|X|X|Y|Y| - |---------------| |---------------| |---------------| |---------------| - -Byte 1: Bit7~Bit6 => 00, Normal data packet - => 01, Absolute coordination packet - => 10, Notify packet - => 11, Normal data packet with on-pad click - Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up. - When both fingers are up, the last two reports have zero valid - bit. - Bit4 => finger up/down information. 1: finger down, 0: finger up. - Bit3 => 1 - Bit2 => finger index, 0 is the first finger, 1 is the second finger. - Bit1 => Right Button, 1 is pressed, 0 is not pressed. - Bit0 => Left Button, 1 is pressed, 0 is not pressed. -Byte 2: X coordinate (xpos[9:2]) -Byte 3: Y coordinate (ypos[9:2]) -Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0]) - Bit3~Bit2 => X coordinate (ypos[1:0]) - Bit4 => scroll down button - Bit5 => scroll up button - Bit6 => scroll left button - Bit7 => scroll right button - -Notify Packet for STL3888-B0 - Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 -BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| - 1 |1|0|1|P|1|M|R|L| 2 |C|C|C|C|C|C|C|C| 3 |0|0|F|F|0|0|0|i| 4 |r|l|u|d|0|0|0|0| - |---------------| |---------------| |---------------| |---------------| - -Byte 1: Bit7~Bit6 => 00, Normal data packet - => 01, Absolute coordination packet - => 10, Notify packet - => 11, Normal data packet with on-pad click - Bit5 => 1 - Bit4 => when in absolute coordinates mode (valid when EN_PKT_GO is 1): - 0: left button is generated by the on-pad command - 1: left button is generated by the external button - Bit3 => 1 - Bit2 => Middle Button, 1 is pressed, 0 is not pressed. - Bit1 => Right Button, 1 is pressed, 0 is not pressed. - Bit0 => Left Button, 1 is pressed, 0 is not pressed. -Byte 2: Message Type => 0xB7 (Multi Finger, Multi Coordinate mode) -Byte 3: Bit7~Bit6 => Don't care - Bit5~Bit4 => Number of fingers - Bit3~Bit1 => Reserved - Bit0 => 1: enter gesture mode; 0: leaving gesture mode -Byte 4: Bit7 => scroll right button - Bit6 => scroll left button - Bit5 => scroll up button - Bit4 => scroll down button - * Note that if gesture and additional button(Bit4~Bit7) - happen at the same time, the button information will not - be sent. - Bit3~Bit0 => Reserved - -Sample sequence of Multi-finger, Multi-coordinate mode: - - notify packet (valid bit == 1), abs pkt 1, abs pkt 2, abs pkt 1, - abs pkt 2, ..., notify packet (valid bit == 0) - -============================================================================== -* Absolute position for STL3888-Cx and STL3888-Dx. -============================================================================== -Single Finger, Absolute Coordinate Mode (SFAC) - Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 -BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| - 1 |0|1|0|P|1|M|R|L| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 |r|l|B|F|X|X|Y|Y| - |---------------| |---------------| |---------------| |---------------| - -Byte 1: Bit7~Bit6 => 00, Normal data packet - => 01, Absolute coordinates packet - => 10, Notify packet - Bit5 => Coordinate mode(always 0 in SFAC mode): - 0: single-finger absolute coordinates (SFAC) mode - 1: multi-finger, multiple coordinates (MFMC) mode - Bit4 => 0: The LEFT button is generated by on-pad command (OPC) - 1: The LEFT button is generated by external button - Default is 1 even if the LEFT button is not pressed. - Bit3 => Always 1, as specified by PS/2 protocol. - Bit2 => Middle Button, 1 is pressed, 0 is not pressed. - Bit1 => Right Button, 1 is pressed, 0 is not pressed. - Bit0 => Left Button, 1 is pressed, 0 is not pressed. -Byte 2: X coordinate (xpos[9:2]) -Byte 3: Y coordinate (ypos[9:2]) -Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0]) - Bit3~Bit2 => X coordinate (ypos[1:0]) - Bit4 => 4th mouse button(forward one page) - Bit5 => 5th mouse button(backward one page) - Bit6 => scroll left button - Bit7 => scroll right button - -Multi Finger, Multiple Coordinates Mode (MFMC): - Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 -BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| - 1 |0|1|1|P|1|F|R|L| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 |r|l|B|F|X|X|Y|Y| - |---------------| |---------------| |---------------| |---------------| - -Byte 1: Bit7~Bit6 => 00, Normal data packet - => 01, Absolute coordination packet - => 10, Notify packet - Bit5 => Coordinate mode (always 1 in MFMC mode): - 0: single-finger absolute coordinates (SFAC) mode - 1: multi-finger, multiple coordinates (MFMC) mode - Bit4 => 0: The LEFT button is generated by on-pad command (OPC) - 1: The LEFT button is generated by external button - Default is 1 even if the LEFT button is not pressed. - Bit3 => Always 1, as specified by PS/2 protocol. - Bit2 => Finger index, 0 is the first finger, 1 is the second finger. - If bit 1 and 0 are all 1 and bit 4 is 0, the middle external - button is pressed. - Bit1 => Right Button, 1 is pressed, 0 is not pressed. - Bit0 => Left Button, 1 is pressed, 0 is not pressed. -Byte 2: X coordinate (xpos[9:2]) -Byte 3: Y coordinate (ypos[9:2]) -Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0]) - Bit3~Bit2 => X coordinate (ypos[1:0]) - Bit4 => 4th mouse button(forward one page) - Bit5 => 5th mouse button(backward one page) - Bit6 => scroll left button - Bit7 => scroll right button - - When one of the two fingers is up, the device will output four consecutive -MFMC#0 report packets with zero X and Y to represent 1st finger is up or -four consecutive MFMC#1 report packets with zero X and Y to represent that -the 2nd finger is up. On the other hand, if both fingers are up, the device -will output four consecutive single-finger, absolute coordinate(SFAC) packets -with zero X and Y. - -Notify Packet for STL3888-Cx/Dx - Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 -BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| - 1 |1|0|0|P|1|M|R|L| 2 |C|C|C|C|C|C|C|C| 3 |0|0|F|F|0|0|0|i| 4 |r|l|u|d|0|0|0|0| - |---------------| |---------------| |---------------| |---------------| - -Byte 1: Bit7~Bit6 => 00, Normal data packet - => 01, Absolute coordinates packet - => 10, Notify packet - Bit5 => Always 0 - Bit4 => 0: The LEFT button is generated by on-pad command(OPC) - 1: The LEFT button is generated by external button - Default is 1 even if the LEFT button is not pressed. - Bit3 => 1 - Bit2 => Middle Button, 1 is pressed, 0 is not pressed. - Bit1 => Right Button, 1 is pressed, 0 is not pressed. - Bit0 => Left Button, 1 is pressed, 0 is not pressed. -Byte 2: Message type: - 0xba => gesture information - 0xc0 => one finger hold-rotating gesture -Byte 3: The first parameter for the received message: - 0xba => gesture ID (refer to the 'Gesture ID' section) - 0xc0 => region ID -Byte 4: The second parameter for the received message: - 0xba => N/A - 0xc0 => finger up/down information - -Sample sequence of Multi-finger, Multi-coordinates mode: - - notify packet (valid bit == 1), MFMC packet 1 (byte 1, bit 2 == 0), - MFMC packet 2 (byte 1, bit 2 == 1), MFMC packet 1, MFMC packet 2, - ..., notify packet (valid bit == 0) - - That is, when the device is in MFMC mode, the host will receive - interleaved absolute coordinate packets for each finger. - -============================================================================== -* FSP Enable/Disable packet -============================================================================== - Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 -BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| - 1 |Y|X|0|0|1|M|R|L| 2 |0|1|0|1|1|0|1|E| 3 | | | | | | | | | 4 | | | | | | | | | - |---------------| |---------------| |---------------| |---------------| - -FSP will send out enable/disable packet when FSP receive PS/2 enable/disable -command. Host will receive the packet which Middle, Right, Left button will -be set. The packet only use byte 0 and byte 1 as a pattern of original packet. -Ignore the other bytes of the packet. - -Byte 1: Bit7 => 0, Y overflow - Bit6 => 0, X overflow - Bit5 => 0, Y sign bit - Bit4 => 0, X sign bit - Bit3 => 1 - Bit2 => 1, Middle Button - Bit1 => 1, Right Button - Bit0 => 1, Left Button -Byte 2: Bit7~1 => (0101101b) - Bit0 => 1 = Enable - 0 = Disable -Byte 3: Don't care -Byte 4: Don't care (MOUSE ID 3, 4) -Byte 5~8: Don't care (Absolute packet) - -============================================================================== -* PS/2 Command Set -============================================================================== - -FSP supports basic PS/2 commanding set and modes, refer to following URL for -details about PS/2 commands: - -http://www.computer-engineering.org/ps2mouse/ - -============================================================================== -* Programming Sequence for Determining Packet Parsing Flow -============================================================================== -1. Identify FSP by reading device ID(0x00) and version(0x01) register - -2a. For FSP version < STL3888 Cx, determine number of buttons by reading - the 'test mode status' (0x20) register: - - buttons = reg[0x20] & 0x30 - - if buttons == 0x30 or buttons == 0x20: - # two/four buttons - Refer to 'Finger Sensing Pad PS/2 Mouse Intellimouse' - section A for packet parsing detail(ignore byte 4, bit ~ 7) - elif buttons == 0x10: - # 6 buttons - Refer to 'Finger Sensing Pad PS/2 Mouse Intellimouse' - section B for packet parsing detail - elif buttons == 0x00: - # 6 buttons - Refer to 'Finger Sensing Pad PS/2 Mouse Intellimouse' - section A for packet parsing detail - -2b. For FSP version >= STL3888 Cx: - Refer to 'Finger Sensing Pad PS/2 Mouse Intellimouse' - section A for packet parsing detail (ignore byte 4, bit ~ 7) - -============================================================================== -* Programming Sequence for Register Reading/Writing -============================================================================== - -Register inversion requirement: - - Following values needed to be inverted(the '~' operator in C) before being -sent to FSP: - - 0xe8, 0xe9, 0xee, 0xf2, 0xf3 and 0xff. - -Register swapping requirement: - - Following values needed to have their higher 4 bits and lower 4 bits being -swapped before being sent to FSP: - - 10, 20, 40, 60, 80, 100 and 200. - -Register reading sequence: - - 1. send 0xf3 PS/2 command to FSP; - - 2. send 0x66 PS/2 command to FSP; - - 3. send 0x88 PS/2 command to FSP; - - 4. send 0xf3 PS/2 command to FSP; - - 5. if the register address being to read is not required to be - inverted(refer to the 'Register inversion requirement' section), - goto step 6 - - 5a. send 0x68 PS/2 command to FSP; - - 5b. send the inverted register address to FSP and goto step 8; - - 6. if the register address being to read is not required to be - swapped(refer to the 'Register swapping requirement' section), - goto step 7 - - 6a. send 0xcc PS/2 command to FSP; - - 6b. send the swapped register address to FSP and goto step 8; - - 7. send 0x66 PS/2 command to FSP; - - 7a. send the original register address to FSP and goto step 8; - - 8. send 0xe9(status request) PS/2 command to FSP; - - 9. the 4th byte of the response read from FSP should be the - requested register value(?? indicates don't care byte): - - host: 0xe9 - 3888: 0xfa (??) (??) (val) - - * Note that since the Cx release, the hardware will return 1's - complement of the register value at the 3rd byte of status request - result: - - host: 0xe9 - 3888: 0xfa (??) (~val) (val) - -Register writing sequence: - - 1. send 0xf3 PS/2 command to FSP; - - 2. if the register address being to write is not required to be - inverted(refer to the 'Register inversion requirement' section), - goto step 3 - - 2a. send 0x74 PS/2 command to FSP; - - 2b. send the inverted register address to FSP and goto step 5; - - 3. if the register address being to write is not required to be - swapped(refer to the 'Register swapping requirement' section), - goto step 4 - - 3a. send 0x77 PS/2 command to FSP; - - 3b. send the swapped register address to FSP and goto step 5; - - 4. send 0x55 PS/2 command to FSP; - - 4a. send the register address to FSP and goto step 5; - - 5. send 0xf3 PS/2 command to FSP; - - 6. if the register value being to write is not required to be - inverted(refer to the 'Register inversion requirement' section), - goto step 7 - - 6a. send 0x47 PS/2 command to FSP; - - 6b. send the inverted register value to FSP and goto step 9; - - 7. if the register value being to write is not required to be - swapped(refer to the 'Register swapping requirement' section), - goto step 8 - - 7a. send 0x44 PS/2 command to FSP; - - 7b. send the swapped register value to FSP and goto step 9; - - 8. send 0x33 PS/2 command to FSP; - - 8a. send the register value to FSP; - - 9. the register writing sequence is completed. - - * Note that since the Cx release, the hardware will return 1's - complement of the register value at the 3rd byte of status request - result. Host can optionally send another 0xe9 (status request) PS/2 - command to FSP at the end of register writing to verify that the - register writing operation is successful (?? indicates don't care - byte): - - host: 0xe9 - 3888: 0xfa (??) (~val) (val) - -============================================================================== -* Programming Sequence for Page Register Reading/Writing -============================================================================== - - In order to overcome the limitation of maximum number of registers -supported, the hardware separates register into different groups called -'pages.' Each page is able to include up to 255 registers. - - The default page after power up is 0x82; therefore, if one has to get -access to register 0x8301, one has to use following sequence to switch -to page 0x83, then start reading/writing from/to offset 0x01 by using -the register read/write sequence described in previous section. - -Page register reading sequence: - - 1. send 0xf3 PS/2 command to FSP; - - 2. send 0x66 PS/2 command to FSP; - - 3. send 0x88 PS/2 command to FSP; - - 4. send 0xf3 PS/2 command to FSP; - - 5. send 0x83 PS/2 command to FSP; - - 6. send 0x88 PS/2 command to FSP; - - 7. send 0xe9(status request) PS/2 command to FSP; - - 8. the response read from FSP should be the requested page value. - -Page register writing sequence: - - 1. send 0xf3 PS/2 command to FSP; - - 2. send 0x38 PS/2 command to FSP; - - 3. send 0x88 PS/2 command to FSP; - - 4. send 0xf3 PS/2 command to FSP; - - 5. if the page address being written is not required to be - inverted(refer to the 'Register inversion requirement' section), - goto step 6 - - 5a. send 0x47 PS/2 command to FSP; - - 5b. send the inverted page address to FSP and goto step 9; - - 6. if the page address being written is not required to be - swapped(refer to the 'Register swapping requirement' section), - goto step 7 - - 6a. send 0x44 PS/2 command to FSP; - - 6b. send the swapped page address to FSP and goto step 9; - - 7. send 0x33 PS/2 command to FSP; - - 8. send the page address to FSP; - - 9. the page register writing sequence is completed. - -============================================================================== -* Gesture ID -============================================================================== - - Unlike other devices which sends multiple fingers' coordinates to host, -FSP processes multiple fingers' coordinates internally and convert them -into a 8 bits integer, namely 'Gesture ID.' Following is a list of -supported gesture IDs: - - ID Description - 0x86 2 finger straight up - 0x82 2 finger straight down - 0x80 2 finger straight right - 0x84 2 finger straight left - 0x8f 2 finger zoom in - 0x8b 2 finger zoom out - 0xc0 2 finger curve, counter clockwise - 0xc4 2 finger curve, clockwise - 0x2e 3 finger straight up - 0x2a 3 finger straight down - 0x28 3 finger straight right - 0x2c 3 finger straight left - 0x38 palm - -============================================================================== -* Register Listing -============================================================================== - - Registers are represented in 16 bits values. The higher 8 bits represent -the page address and the lower 8 bits represent the relative offset within -that particular page. Refer to the 'Programming Sequence for Page Register -Reading/Writing' section for instructions on how to change current page -address. - -offset width default r/w name -0x8200 bit7~bit0 0x01 RO device ID - -0x8201 bit7~bit0 RW version ID - 0xc1: STL3888 Ax - 0xd0 ~ 0xd2: STL3888 Bx - 0xe0 ~ 0xe1: STL3888 Cx - 0xe2 ~ 0xe3: STL3888 Dx - -0x8202 bit7~bit0 0x01 RO vendor ID - -0x8203 bit7~bit0 0x01 RO product ID - -0x8204 bit3~bit0 0x01 RW revision ID - -0x820b test mode status 1 - bit3 1 RO 0: rotate 180 degree - 1: no rotation - *only supported by H/W prior to Cx - -0x820f register file page control - bit2 0 RW 1: rotate 180 degree - 0: no rotation - *supported since Cx - - bit0 0 RW 1 to enable page 1 register files - *only supported by H/W prior to Cx - -0x8210 RW system control 1 - bit0 1 RW Reserved, must be 1 - bit1 0 RW Reserved, must be 0 - bit4 0 RW Reserved, must be 0 - bit5 1 RW register clock gating enable - 0: read only, 1: read/write enable - (Note that following registers does not require clock gating being - enabled prior to write: 05 06 07 08 09 0c 0f 10 11 12 16 17 18 23 2e - 40 41 42 43. In addition to that, this bit must be 1 when gesture - mode is enabled) - -0x8220 test mode status - bit5~bit4 RO number of buttons - 11 => 2, lbtn/rbtn - 10 => 4, lbtn/rbtn/scru/scrd - 01 => 6, lbtn/rbtn/scru/scrd/scrl/scrr - 00 => 6, lbtn/rbtn/scru/scrd/fbtn/bbtn - *only supported by H/W prior to Cx - -0x8231 RW on-pad command detection - bit7 0 RW on-pad command left button down tag - enable - 0: disable, 1: enable - *only supported by H/W prior to Cx - -0x8234 RW on-pad command control 5 - bit4~bit0 0x05 RW XLO in 0s/4/1, so 03h = 0010.1b = 2.5 - (Note that position unit is in 0.5 scanline) - *only supported by H/W prior to Cx - - bit7 0 RW on-pad tap zone enable - 0: disable, 1: enable - *only supported by H/W prior to Cx - -0x8235 RW on-pad command control 6 - bit4~bit0 0x1d RW XHI in 0s/4/1, so 19h = 1100.1b = 12.5 - (Note that position unit is in 0.5 scanline) - *only supported by H/W prior to Cx - -0x8236 RW on-pad command control 7 - bit4~bit0 0x04 RW YLO in 0s/4/1, so 03h = 0010.1b = 2.5 - (Note that position unit is in 0.5 scanline) - *only supported by H/W prior to Cx - -0x8237 RW on-pad command control 8 - bit4~bit0 0x13 RW YHI in 0s/4/1, so 11h = 1000.1b = 8.5 - (Note that position unit is in 0.5 scanline) - *only supported by H/W prior to Cx - -0x8240 RW system control 5 - bit1 0 RW FSP Intellimouse mode enable - 0: disable, 1: enable - *only supported by H/W prior to Cx - - bit2 0 RW movement + abs. coordinate mode enable - 0: disable, 1: enable - (Note that this function has the functionality of bit 1 even when - bit 1 is not set. However, the format is different from that of bit 1. - In addition, when bit 1 and bit 2 are set at the same time, bit 2 will - override bit 1.) - *only supported by H/W prior to Cx - - bit3 0 RW abs. coordinate only mode enable - 0: disable, 1: enable - (Note that this function has the functionality of bit 1 even when - bit 1 is not set. However, the format is different from that of bit 1. - In addition, when bit 1, bit 2 and bit 3 are set at the same time, - bit 3 will override bit 1 and 2.) - *only supported by H/W prior to Cx - - bit5 0 RW auto switch enable - 0: disable, 1: enable - *only supported by H/W prior to Cx - - bit6 0 RW G0 abs. + notify packet format enable - 0: disable, 1: enable - (Note that the absolute/relative coordinate output still depends on - bit 2 and 3. That is, if any of those bit is 1, host will receive - absolute coordinates; otherwise, host only receives packets with - relative coordinate.) - *only supported by H/W prior to Cx - - bit7 0 RW EN_PS2_F2: PS/2 gesture mode 2nd - finger packet enable - 0: disable, 1: enable - *only supported by H/W prior to Cx - -0x8243 RW on-pad control - bit0 0 RW on-pad control enable - 0: disable, 1: enable - (Note that if this bit is cleared, bit 3/5 will be ineffective) - *only supported by H/W prior to Cx - - bit3 0 RW on-pad fix vertical scrolling enable - 0: disable, 1: enable - *only supported by H/W prior to Cx - - bit5 0 RW on-pad fix horizontal scrolling enable - 0: disable, 1: enable - *only supported by H/W prior to Cx - -0x8290 RW software control register 1 - bit0 0 RW absolute coordination mode - 0: disable, 1: enable - *supported since Cx - - bit1 0 RW gesture ID output - 0: disable, 1: enable - *supported since Cx - - bit2 0 RW two fingers' coordinates output - 0: disable, 1: enable - *supported since Cx - - bit3 0 RW finger up one packet output - 0: disable, 1: enable - *supported since Cx - - bit4 0 RW absolute coordination continuous mode - 0: disable, 1: enable - *supported since Cx - - bit6~bit5 00 RW gesture group selection - 00: basic - 01: suite - 10: suite pro - 11: advanced - *supported since Cx - - bit7 0 RW Bx packet output compatible mode - 0: disable, 1: enable *supported since Cx - *supported since Cx - - -0x833d RW on-pad command control 1 - bit7 1 RW on-pad command detection enable - 0: disable, 1: enable - *supported since Cx - -0x833e RW on-pad command detection - bit7 0 RW on-pad command left button down tag - enable. Works only in H/W based PS/2 - data packet mode. - 0: disable, 1: enable - *supported since Cx diff --git a/Documentation/input/shape.fig b/Documentation/input/shape.fig deleted file mode 100644 index c22bff83d06..00000000000 --- a/Documentation/input/shape.fig +++ /dev/null @@ -1,65 +0,0 @@ -#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/walkera0701.txt b/Documentation/input/walkera0701.txt deleted file mode 100644 index 561385d3848..00000000000 --- a/Documentation/input/walkera0701.txt +++ /dev/null @@ -1,109 +0,0 @@ - -Walkera WK-0701 transmitter is supplied with a ready to fly Walkera -helicopters such as HM36, HM37, HM60. The walkera0701 module enables to use -this transmitter as joystick - -Devel homepage and download: -http://zub.fei.tuke.sk/walkera-wk0701/ - -or use cogito: -cg-clone http://zub.fei.tuke.sk/GIT/walkera0701-joystick - - -Connecting to PC: - -At back side of transmitter S-video connector can be found. Modulation -pulses from processor to HF part can be found at pin 2 of this connector, -pin 3 is GND. Between pin 3 and CPU 5k6 resistor can be found. To get -modulation pulses to PC, signal pulses must be amplified. - -Cable: (walkera TX to parport) - -Walkera WK-0701 TX S-VIDEO connector: - (back side of TX) - __ __ S-video: canon25 - / |_| \ pin 2 (signal) NPN parport - / O 4 3 O \ pin 3 (GND) LED ________________ 10 ACK - ( O 2 1 O ) | C - \ ___ / 2 ________________________|\|_____|/ - | [___] | |/| B |\ - ------- 3 __________________________________|________________ 25 GND - E - - -I use green LED and BC109 NPN transistor. - -Software: - -Build kernel with walkera0701 module. Module walkera0701 need exclusive -access to parport, modules like lp must be unloaded before loading -walkera0701 module, check dmesg for error messages. Connect TX to PC by -cable and run jstest /dev/input/js0 to see values from TX. If no value can -be changed by TX "joystick", check output from /proc/interrupts. Value for -(usually irq7) parport must increase if TX is on. - - - -Technical details: - -Driver use interrupt from parport ACK input bit to measure pulse length -using hrtimers. - -Frame format: -Based on walkera WK-0701 PCM Format description by Shaul Eizikovich. -(downloaded from http://www.smartpropoplus.com/Docs/Walkera_Wk-0701_PCM.pdf) - -Signal pulses: - (ANALOG) - SYNC BIN OCT - +---------+ +------+ - | | | | ---+ +------+ +--- - -Frame: - SYNC , BIN1, OCT1, BIN2, OCT2 ... BIN24, OCT24, BIN25, next frame SYNC .. - -pulse length: - Binary values: Analog octal values: - - 288 uS Binary 0 318 uS 000 - 438 uS Binary 1 398 uS 001 - 478 uS 010 - 558 uS 011 - 638 uS 100 - 1306 uS SYNC 718 uS 101 - 798 uS 110 - 878 uS 111 - -24 bin+oct values + 1 bin value = 24*4+1 bits = 97 bits - -(Warning, pulses on ACK are inverted by transistor, irq is raised up on sync -to bin change or octal value to bin change). - -Binary data representations: - -One binary and octal value can be grouped to nibble. 24 nibbles + one binary -values can be sampled between sync pulses. - -Values for first four channels (analog joystick values) can be found in -first 10 nibbles. Analog value is represented by one sign bit and 9 bit -absolute binary value. (10 bits per channel). Next nibble is checksum for -first ten nibbles. - -Next nibbles 12 .. 21 represents four channels (not all channels can be -directly controlled from TX). Binary representations ar the same as in first -four channels. In nibbles 22 and 23 is a special magic number. Nibble 24 is -checksum for nibbles 12..23. - -After last octal value for nibble 24 and next sync pulse one additional -binary value can be sampled. This bit and magic number is not used in -software driver. Some details about this magic numbers can be found in -Walkera_Wk-0701_PCM.pdf. - -Checksum calculation: - -Summary of octal values in nibbles must be same as octal value in checksum -nibble (only first 3 bits are used). Binary value for checksum nibble is -calculated by sum of binary values in checked nibbles + sum of octal values -in checked nibbles divided by 8. Only bit 0 of this sum is used. - diff --git a/Documentation/input/xpad.txt b/Documentation/input/xpad.txt deleted file mode 100644 index 7cc9a436e6a..00000000000 --- a/Documentation/input/xpad.txt +++ /dev/null @@ -1,183 +0,0 @@ -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. Notes --------- - -Driver updated for kernel 2.6.17.11. (Based on a patch for 2.6.11.4.) - -The number of buttons/axes reported varies based on 3 things: -- if you are using a known controller -- if you are using a known dance pad -- if using an unknown device (one not listed below), what you set in the - module configuration for "Map D-PAD to buttons rather than axes for unknown - pads" (module option dpad_to_buttons) - -If you set dpad_to_buttons to 0 and you are using an unknown device (one -not listed below), the driver will map the directional pad to axes (X/Y), -if you said N it will map the d-pad to buttons, which is needed for dance -style games to function correctly. The default is Y. - -dpad_to_buttons has no effect for known pads. - -0.1 Normal Controllers ----------------------- -With a normal controller, the directional pad is mapped to its own X/Y axes. -The jstest-program from joystick-1.2.15 (jstest-version 2.1.0) will report 8 -axes and 10 buttons. - -All 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. - - -0.2 Xbox Dance Pads -------------------- -When using a known dance pad, jstest will report 6 axes and 14 buttons. - -For dance style pads (like the redoctane pad) several changes -have been made. The old driver would map the d-pad to axes, resulting -in the driver being unable to report when the user was pressing both -left+right or up+down, making DDR style games unplayable. - -Known dance pads automatically map the d-pad to buttons and will work -correctly out of the box. - -If your dance pad is recognized by the driver but is using axes instead -of buttons, see section 0.3 - Unknown Controllers - -I've tested this with Stepmania, and it works quite well. - - -0.3 Unknown Controllers ----------------------- -If you have an unknown xbox controller, it should work just fine with -the default settings. - -HOWEVER if you have an unknown dance pad not listed below, it will not -work UNLESS you set "dpad_to_buttons" to 1 in the module configuration. - -PLEASE, if you have an unknown controller, email Dom <binary1230@yahoo.com> with -a dump from /proc/bus/usb and a description of the pad (manufacturer, country, -whether it is a dance pad or normal controller) so that we can add your pad -to the list of supported devices, ensuring that it will work out of the -box in the future. - - -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. You -can buy these online fairly cheap, or build your own. - -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.6), the following devices are included: - original Microsoft XBOX controller (US), vendor=0x045e, product=0x0202 - smaller Microsoft XBOX controller (US), vendor=0x045e, product=0x0289 - original Microsoft XBOX controller (Japan), vendor=0x045e, product=0x0285 - InterAct PowerPad Pro (Germany), vendor=0x05fd, product=0x107a - RedOctane Xbox Dance Pad (US), vendor=0x0c12, product=0x8809 - -The driver should work with xbox pads not listed above as well, however -you will need to do something extra for dance pads to work. - -If you have a controller not listed above, see 0.3 - Unknown Controllers - -If you compiled and installed the driver, test the functionality: -> modprobe xpad -> modprobe joydev -> jstest /dev/js0 - -If you're using a normal controller, there should be a single line showing -18 inputs (8 axes, 10 buttons), and its values should change if you move -the sticks and push the buttons. If you're using a dance pad, it should -show 20 inputs (6 axes, 14 buttons). - -It works? Voila, you're 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.markosweb.com/www/xboxhackz.com/ - -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 - -5. /proc/bus/usb/devices - dump from Redoctane Xbox Dance Pad (US): - -T: Bus=01 Lev=02 Prnt=09 Port=00 Cnt=01 Dev#= 10 Spd=12 MxCh= 0 -D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 -P: Vendor=0c12 ProdID=8809 Rev= 0.01 -S: Product=XBOX DDR -C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA -I: If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=xpad -E: Ad=82(I) Atr=03(Int.) MxPS= 32 Ivl=4ms -E: Ad=02(O) Atr=03(Int.) MxPS= 32 Ivl=4ms - --- -Marko Friedemann <mfr@bmx-chemnitz.de> -2002-07-16 - - original doc - -Dominic Cerquetti <binary1230@yahoo.com> -2005-03-19 - - added stuff for dance pads, new d-pad->axes mappings diff --git a/Documentation/input/yealink.txt b/Documentation/input/yealink.txt deleted file mode 100644 index 5360e434486..00000000000 --- a/Documentation/input/yealink.txt +++ /dev/null @@ -1,216 +0,0 @@ -Driver documentation for yealink usb-p1k phones - -0. Status -~~~~~~~~~ -The p1k is a relatively cheap usb 1.1 phone with: - - keyboard full support, yealink.ko / input event API - - LCD full support, yealink.ko / sysfs API - - LED full support, yealink.ko / sysfs API - - dialtone full support, yealink.ko / sysfs API - - ringtone full support, yealink.ko / sysfs API - - audio playback full support, snd_usb_audio.ko / alsa API - - audio record full support, snd_usb_audio.ko / alsa API - -For vendor documentation see http://www.yealink.com - - -1. Compilation (stand alone version) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Currently only kernel 2.6.x.y versions are supported. -In order to build the yealink.ko module do - - make - -If you encounter problems please check if in the MAKE_OPTS variable in -the Makefile is pointing to the location where your kernel sources -are located, default /usr/src/linux. - - -1.1 Troubleshooting -~~~~~~~~~~~~~~~~~~~ -Q: Module yealink compiled and installed without any problem but phone - is not initialized and does not react to any actions. -A: If you see something like: - hiddev0: USB HID v1.00 Device [Yealink Network Technology Ltd. VOIP USB Phone - in dmesg, it means that the hid driver has grabbed the device first. Try to - load module yealink before any other usb hid driver. Please see the - instructions provided by your distribution on module configuration. - -Q: Phone is working now (displays version and accepts keypad input) but I can't - find the sysfs files. -A: The sysfs files are located on the particular usb endpoint. On most - distributions you can do: "find /sys/ -name get_icons" for a hint. - - -2. keyboard features -~~~~~~~~~~~~~~~~~~~~ -The current mapping in the kernel is provided by the map_p1k_to_key -function: - - Physical USB-P1K button layout input events - - - up up - IN OUT left, right - down down - - pickup C hangup enter, backspace, escape - 1 2 3 1, 2, 3 - 4 5 6 4, 5, 6, - 7 8 9 7, 8, 9, - * 0 # *, 0, #, - - The "up" and "down" keys, are symbolised by arrows on the button. - The "pickup" and "hangup" keys are symbolised by a green and red phone - on the button. - - -3. LCD features -~~~~~~~~~~~~~~~ -The LCD is divided and organised as a 3 line display: - - |[] [][] [][] [][] in |[][] - |[] M [][] D [][] : [][] out |[][] - store - - NEW REP SU MO TU WE TH FR SA - - [] [] [] [] [] [] [] [] [] [] [] [] - [] [] [] [] [] [] [] [] [] [] [] [] - - -Line 1 Format (see below) : 18.e8.M8.88...188 - Icon names : M D : IN OUT STORE -Line 2 Format : ......... - Icon name : NEW REP SU MO TU WE TH FR SA -Line 3 Format : 888888888888 - - -Format description: - From a userspace perspective the world is separated into "digits" and "icons". - A digit can have a character set, an icon can only be ON or OFF. - - Format specifier - '8' : Generic 7 segment digit with individual addressable segments - - Reduced capability 7 segm digit, when segments are hard wired together. - '1' : 2 segments digit only able to produce a 1. - 'e' : Most significant day of the month digit, - able to produce at least 1 2 3. - 'M' : Most significant minute digit, - able to produce at least 0 1 2 3 4 5. - - Icons or pictograms: - '.' : For example like AM, PM, SU, a 'dot' .. or other single segment - elements. - - -4. Driver usage -~~~~~~~~~~~~~~~ -For userland the following interfaces are available using the sysfs interface: - /sys/.../ - line1 Read/Write, lcd line1 - line2 Read/Write, lcd line2 - line3 Read/Write, lcd line3 - - get_icons Read, returns a set of available icons. - hide_icon Write, hide the element by writing the icon name. - show_icon Write, display the element by writing the icon name. - - map_seg7 Read/Write, the 7 segments char set, common for all - yealink phones. (see map_to_7segment.h) - - ringtone Write, upload binary representation of a ringtone, - see yealink.c. status EXPERIMENTAL due to potential - races between async. and sync usb calls. - - -4.1 lineX -~~~~~~~~~ -Reading /sys/../lineX will return the format string with its current value: - - Example: - cat ./line3 - 888888888888 - Linux Rocks! - -Writing to /sys/../lineX will set the corresponding LCD line. - - Excess characters are ignored. - - If less characters are written than allowed, the remaining digits are - unchanged. - - The tab '\t'and '\n' char does not overwrite the original content. - - Writing a space to an icon will always hide its content. - - Example: - date +"%m.%e.%k:%M" | sed 's/^0/ /' > ./line1 - - Will update the LCD with the current date & time. - - -4.2 get_icons -~~~~~~~~~~~~~ -Reading will return all available icon names and its current settings: - - cat ./get_icons - on M - on D - on : - IN - OUT - STORE - NEW - REP - SU - MO - TU - WE - TH - FR - SA - LED - DIALTONE - RINGTONE - - -4.3 show/hide icons -~~~~~~~~~~~~~~~~~~~ -Writing to these files will update the state of the icon. -Only one icon at a time can be updated. - -If an icon is also on a ./lineX the corresponding value is -updated with the first letter of the icon. - - Example - light up the store icon: - echo -n "STORE" > ./show_icon - - cat ./line1 - 18.e8.M8.88...188 - S - - Example - sound the ringtone for 10 seconds: - echo -n RINGTONE > /sys/..../show_icon - sleep 10 - echo -n RINGTONE > /sys/..../hide_icon - - -5. Sound features -~~~~~~~~~~~~~~~~~ -Sound is supported by the ALSA driver: snd_usb_audio - -One 16-bit channel with sample and playback rates of 8000 Hz is the practical -limit of the device. - - Example - recording test: - arecord -v -d 10 -r 8000 -f S16_LE -t wav foobar.wav - - Example - playback test: - aplay foobar.wav - - -6. Credits & Acknowledgments -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - Olivier Vandorpe, for starting the usbb2k-api project doing much of - the reverse engineering. - - Martin Diehl, for pointing out how to handle USB memory allocation. - - Dmitry Torokhov, for the numerous code reviews and suggestions. - |