diff options
Diffstat (limited to 'Documentation/input')
| -rw-r--r-- | Documentation/input/event-codes.rst | 10 | ||||
| -rw-r--r-- | Documentation/input/ff.rst | 6 | ||||
| -rw-r--r-- | Documentation/input/gameport-programming.rst | 35 | ||||
| -rw-r--r-- | Documentation/input/input-programming.rst | 20 | ||||
| -rw-r--r-- | Documentation/input/input.rst | 8 | ||||
| -rw-r--r-- | Documentation/input/joydev/joystick-api.rst | 14 | ||||
| -rw-r--r-- | Documentation/input/joydev/joystick.rst | 26 | ||||
| -rw-r--r-- | Documentation/input/multi-touch-protocol.rst | 8 | ||||
| -rw-r--r-- | Documentation/input/notifier.rst | 3 | ||||
| -rw-r--r-- | Documentation/input/uinput.rst | 2 |
10 files changed, 72 insertions, 60 deletions
diff --git a/Documentation/input/event-codes.rst b/Documentation/input/event-codes.rst index 3118fc1c1e26..b24ae7d292cc 100644 --- a/Documentation/input/event-codes.rst +++ b/Documentation/input/event-codes.rst @@ -246,9 +246,9 @@ A few EV_ABS codes have special meanings: A device should set the resolution of the axis to indicate whether the pressure is in measurable units. If the resolution is zero, the - pressure data is in arbitrary units. If the resolution is nonzero, the + pressure data is in arbitrary units. If the resolution is non-zero, the pressure data is in units/gram. For example, a value of 10 with a - resolution of 1 represents 10 gram, a value of 10 with a resolution on + resolution of 1 represents 10 gram, a value of 10 with a resolution of 1000 represents 10 microgram. EV_SW @@ -344,7 +344,7 @@ 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. +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 @@ -356,7 +356,7 @@ 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. +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 @@ -394,7 +394,7 @@ Guidelines ========== The guidelines below ensure proper single-touch and multi-finger functionality. -For multi-touch functionality, see the multi-touch-protocol.txt document for +For multi-touch functionality, see the multi-touch-protocol.rst document for more information. Mice diff --git a/Documentation/input/ff.rst b/Documentation/input/ff.rst index 0c02e87ee86d..5a1da42c33b3 100644 --- a/Documentation/input/ff.rst +++ b/Documentation/input/ff.rst @@ -16,8 +16,8 @@ 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. +interface. Please read joydev/joystick.rst and input.rst before reading further +this document. Instructions to the user ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -36,7 +36,7 @@ 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. +joydev/joystick.rst for details. Does it work ? -------------- diff --git a/Documentation/input/gameport-programming.rst b/Documentation/input/gameport-programming.rst index c96911df1c54..7d7063ad0f9f 100644 --- a/Documentation/input/gameport-programming.rst +++ b/Documentation/input/gameport-programming.rst @@ -21,7 +21,7 @@ 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 +E.g. 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 @@ -78,7 +78,7 @@ the gameport. To register a cooked gameport:: for (i = 0; i < 4; i++) axes[i] = my_mmio[i]; - buttons[i] = my_mmio[4]; + buttons[0] = my_mmio[4]; } int my_open(struct gameport *gameport, int mode) @@ -117,25 +117,28 @@ Simple:: The gameport structure ~~~~~~~~~~~~~~~~~~~~~~ -.. note:: - - This section is outdated. There are several fields here that don't - match what's there at include/linux/gameport.h. - :: struct gameport { - void *private; + void *port_data; A private pointer for free use in the gameport driver. (Not the joystick driver!) :: - int number; + char name[32]; + +Driver's name as set by driver calling gameport_set_name(). Informational +purpose only. + +:: + + char phys[32]; -Number assigned to the gameport when registered. Informational purpose only. +gameport's physical name/description as set by driver calling gameport_set_phys(). +Informational purpose only. :: @@ -210,8 +213,16 @@ gameport. :: - struct gameport_dev *dev; - struct gameport *next; + struct timer_list poll_timer; + unsigned int poll_interval; /* in msecs */ + spinlock_t timer_lock; + unsigned int poll_cnt; + void (*poll_handler)(struct gameport *); + struct gameport *parent, *child; + struct gameport_driver *drv; + struct mutex drv_mutex; /* protects serio->drv so attributes can pin driver */ + struct device dev; + struct list_head node; For internal use by the gameport layer. diff --git a/Documentation/input/input-programming.rst b/Documentation/input/input-programming.rst index 5938145b0e35..2638dce69764 100644 --- a/Documentation/input/input-programming.rst +++ b/Documentation/input/input-programming.rst @@ -120,7 +120,7 @@ Then there is the:: 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 +for example for mouse movement, where you don't want the X and Y values to be interpreted separately, because that'd result in a different movement. dev->open() and dev->close() @@ -128,7 +128,7 @@ 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 +all the time, or if the device uses a valuable resource (e.g. 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:: @@ -161,7 +161,7 @@ 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 +The open() callback should return a 0 in case of success or any non-zero value in case of failure. The close() callback (which is void) must always succeed. Inhibiting input devices @@ -182,8 +182,8 @@ providing events to the input core. Calling the device's close() method on inhibit (if there are users) allows the driver to save power. Either by directly powering down the device or by -releasing the runtime-pm reference it got in open() when the driver is using -runtime-pm. +releasing the runtime-PM reference it got in open() when the driver is using +runtime-PM. Inhibiting and uninhibiting are orthogonal to opening and closing the device by input handlers. Userspace might want to inhibit a device in anticipation before @@ -219,8 +219,8 @@ It's reported to the input system via:: input_report_key(struct input_dev *dev, int code, int value) See uapi/linux/input-event-codes.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 +KEY_MAX). Value is interpreted as a truth value, i.e. any non-zero 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 @@ -231,12 +231,12 @@ 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 +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. +function. Events are generated only for non-zero values. However EV_ABS requires a little special care. Before calling input_register_device, you have to fill additional fields in the input_dev @@ -280,7 +280,7 @@ 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 +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. diff --git a/Documentation/input/input.rst b/Documentation/input/input.rst index 0eb61e67a7b7..2c67fa904adc 100644 --- a/Documentation/input/input.rst +++ b/Documentation/input/input.rst @@ -9,7 +9,7 @@ Introduction Architecture ============ -Input subsystem a collection of drivers that is designed to support +Input subsystem is a collection of drivers that is designed to support all input devices under Linux. Most of the drivers reside in drivers/input, although quite a few live in drivers/hid and drivers/platform. @@ -50,7 +50,7 @@ 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 usually created automatically by the system. The commands +This device is usually created automatically by the system. The commands to create it by hand are:: cd /dev @@ -180,7 +180,7 @@ 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 +Currently, it handles USB mice, joysticks, gamepads, steering wheels, keyboards, trackballs and digitizers. However, USB uses HID also for monitor controls, speaker controls, UPSs, @@ -268,7 +268,7 @@ events on a read. Their layout is:: }; ``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 +Type is for example EV_REL for relative movement, EV_KEY for a keypress or release. More types are defined in include/uapi/linux/input-event-codes.h. ``code`` is event code, for example REL_X or KEY_BACKSPACE, again a complete diff --git a/Documentation/input/joydev/joystick-api.rst b/Documentation/input/joydev/joystick-api.rst index 95803e2e8cd0..af5934c10c1c 100644 --- a/Documentation/input/joydev/joystick-api.rst +++ b/Documentation/input/joydev/joystick-api.rst @@ -71,7 +71,7 @@ The possible values of ``type`` are:: #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 +events on open. That is, if it's issuing an INIT BUTTON event, the current type value will be:: int type = JS_EVENT_BUTTON | JS_EVENT_INIT; /* 0x81 */ @@ -100,8 +100,8 @@ is, you have both an axis 0 and a button 0). Generally, =============== ======= 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. +directions, some only in 4. The driver, however, always reports a hat as two +independent axes, even if the hardware doesn't allow independent movement. js_event.value @@ -188,10 +188,10 @@ 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 +The other reason is that you want to know all that happened, and not delay the processing till later. -Why can get the queue full? Because you don't empty the queue as +Why can the queue get 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. @@ -277,7 +277,7 @@ 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]; +information for all axes. That is, struct js_corr corr[MAX_AXIS]; struct js_corr is defined as:: @@ -328,7 +328,7 @@ To test the state of the buttons, 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 +except 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. diff --git a/Documentation/input/joydev/joystick.rst b/Documentation/input/joydev/joystick.rst index 9746fd76cc58..f615906a0821 100644 --- a/Documentation/input/joydev/joystick.rst +++ b/Documentation/input/joydev/joystick.rst @@ -133,15 +133,15 @@ And add a line to your rc script executing that file:: This way, after the next reboot your joystick will remain calibrated. You can also add the ``jscal -p`` line to your shutdown script. -HW specific driver information -============================== +Hardware-specific driver information +==================================== In this section each of the separate hardware specific drivers is described. Analog joysticks ---------------- -The analog.c uses the standard analog inputs of the gameport, and thus +The analog.c driver 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. @@ -266,7 +266,7 @@ to: * 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 +combination of) devices on a single gameport, using a Y-cable or chained together. Logitech WingMan Joystick, Logitech WingMan Attack, Logitech WingMan @@ -288,7 +288,7 @@ supports: * 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 +of up to two of these pads either chained together or using a Y-cable on a single gameport. GrIP MultiPort isn't supported yet. Gravis Stinger is a serial device and is @@ -311,7 +311,7 @@ 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. +the USB documentation for how to setup a USB mouse. ThrustMaster DirectConnect (BSP) -------------------------------- @@ -332,7 +332,7 @@ 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. +a Y-cable. Creative Labs Blaster --------------------- @@ -342,7 +342,7 @@ the: * Creative Blaster GamePad Cobra -Up to two of these can be used on a single gameport, using an Y-cable. +Up to two of these can be used on a single gameport, using a Y-cable. Genius Digital joysticks ------------------------ @@ -381,7 +381,7 @@ card, 16 in case you have two in your system. Trident 4DWave / Aureal Vortex ------------------------------ -Soundcards with a Trident 4DWave DX/NX or Aureal Vortex/Vortex2 chipsets +Soundcards with a Trident 4DWave DX/NX or Aureal Vortex/Vortex2 chipset 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.. @@ -454,7 +454,7 @@ 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 +kernel, you also need to attach a serial port to it. To do that, run the inputattach program:: inputattach --spaceorb /dev/tts/x & @@ -466,7 +466,7 @@ or:: 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 +There is one caveat with the SpaceOrb. The button #6, the one 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 @@ -500,7 +500,7 @@ joy-magellan module. It currently supports only the: * Magellan 3D * Space Mouse -models, the additional buttons on the 'Plus' versions are not supported yet. +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:: @@ -575,7 +575,7 @@ FAQ :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 + 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. diff --git a/Documentation/input/multi-touch-protocol.rst b/Documentation/input/multi-touch-protocol.rst index 21c1e6a22888..1085cbee4ee7 100644 --- a/Documentation/input/multi-touch-protocol.rst +++ b/Documentation/input/multi-touch-protocol.rst @@ -261,7 +261,7 @@ ABS_MT_PRESSURE signal intensity distribution. If the resolution is zero, the pressure data is in arbitrary units. - If the resolution is nonzero, the pressure data is in units/gram. See + If the resolution is non-zero, the pressure data is in units/gram. See :ref:`input-event-codes` for details. ABS_MT_DISTANCE @@ -279,14 +279,14 @@ ABS_MT_ORIENTATION max should be returned; when aligned with the X axis in the negative direction, the range -max should be returned. - Touch ellipsis are symmetrical by default. For devices capable of true 360 + Touch ellipses are symmetrical by default. For devices capable of true 360 degree orientation, the reported orientation must exceed the range max to indicate more than a quarter of a revolution. For an upside-down finger, range max * 2 should be returned. Orientation can be omitted if the touch area 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 + support is possible if the device can distinguish between the two axes, but not (uniquely) any values in between. In such cases, the range of ABS_MT_ORIENTATION should be [0, 1] [#f4]_. @@ -356,7 +356,7 @@ 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). -For win8 devices with both T and C coordinates, the position mapping is:: +For Win8 devices with both T and C coordinates, the position mapping is:: ABS_MT_POSITION_X := T_X ABS_MT_POSITION_Y := T_Y diff --git a/Documentation/input/notifier.rst b/Documentation/input/notifier.rst index 161350cb865e..824379399e61 100644 --- a/Documentation/input/notifier.rst +++ b/Documentation/input/notifier.rst @@ -4,11 +4,12 @@ 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: +keyboard_notifier_param (see <linux/keyboard.h>): - '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_*; +- 'ledstate' is the current LED state; - 'value' depends on the type of event. - KBD_KEYCODE events are always sent before other events, value is the keycode. diff --git a/Documentation/input/uinput.rst b/Documentation/input/uinput.rst index 10c62e62a0a6..30fe80e325a5 100644 --- a/Documentation/input/uinput.rst +++ b/Documentation/input/uinput.rst @@ -179,7 +179,7 @@ uinput old interface -------------------- Before uinput version 5, there wasn't a dedicated ioctl to set up a virtual -device. Programs supportinf older versions of uinput interface need to fill +device. Programs supporting older versions of uinput interface need to fill a uinput_user_dev structure and write it to the uinput file descriptor to configure the new uinput device. New code should not use the old interface but interact with uinput via ioctl calls, or use libevdev. |