input.txt 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291
  1. Linux Input drivers v1.0
  2. (c) 1999-2001 Vojtech Pavlik <vojtech@ucw.cz>
  3. Sponsored by SuSE
  4. $Id: input.txt,v 1.1.1.1 2007/06/12 07:27:12 eyryu Exp $
  5. ----------------------------------------------------------------------------
  6. 0. Disclaimer
  7. ~~~~~~~~~~~~~
  8. This program is free software; you can redistribute it and/or modify it
  9. under the terms of the GNU General Public License as published by the Free
  10. Software Foundation; either version 2 of the License, or (at your option)
  11. any later version.
  12. This program is distributed in the hope that it will be useful, but
  13. WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  14. or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
  15. more details.
  16. You should have received a copy of the GNU General Public License along
  17. with this program; if not, write to the Free Software Foundation, Inc., 59
  18. Temple Place, Suite 330, Boston, MA 02111-1307 USA
  19. Should you need to contact me, the author, you can do so either by e-mail
  20. - mail your message to <vojtech@ucw.cz>, or by paper mail: Vojtech Pavlik,
  21. Simunkova 1594, Prague 8, 182 00 Czech Republic
  22. For your convenience, the GNU General Public License version 2 is included
  23. in the package: See the file COPYING.
  24. 1. Introduction
  25. ~~~~~~~~~~~~~~~
  26. This is a collection of drivers that is designed to support all input
  27. devices under Linux. While it is currently used only on for USB input
  28. devices, future use (say 2.5/2.6) is expected to expand to replace
  29. most of the existing input system, which is why it lives in
  30. drivers/input/ instead of drivers/usb/.
  31. The centre of the input drivers is the input module, which must be
  32. loaded before any other of the input modules - it serves as a way of
  33. communication between two groups of modules:
  34. 1.1 Device drivers
  35. ~~~~~~~~~~~~~~~~~~
  36. These modules talk to the hardware (for example via USB), and provide
  37. events (keystrokes, mouse movements) to the input module.
  38. 1.2 Event handlers
  39. ~~~~~~~~~~~~~~~~~~
  40. These modules get events from input and pass them where needed via
  41. various interfaces - keystrokes to the kernel, mouse movements via a
  42. simulated PS/2 interface to GPM and X and so on.
  43. 2. Simple Usage
  44. ~~~~~~~~~~~~~~~
  45. For the most usual configuration, with one USB mouse and one USB keyboard,
  46. you'll have to load the following modules (or have them built in to the
  47. kernel):
  48. input
  49. mousedev
  50. keybdev
  51. usbcore
  52. uhci_hcd or ohci_hcd or ehci_hcd
  53. usbhid
  54. After this, the USB keyboard will work straight away, and the USB mouse
  55. will be available as a character device on major 13, minor 63:
  56. crw-r--r-- 1 root root 13, 63 Mar 28 22:45 mice
  57. This device has to be created.
  58. The commands to create it by hand are:
  59. cd /dev
  60. mkdir input
  61. mknod input/mice c 13 63
  62. After that you have to point GPM (the textmode mouse cut&paste tool) and
  63. XFree to this device to use it - GPM should be called like:
  64. gpm -t ps2 -m /dev/input/mice
  65. And in X:
  66. Section "Pointer"
  67. Protocol "ImPS/2"
  68. Device "/dev/input/mice"
  69. ZAxisMapping 4 5
  70. EndSection
  71. When you do all of the above, you can use your USB mouse and keyboard.
  72. 3. Detailed Description
  73. ~~~~~~~~~~~~~~~~~~~~~~~
  74. 3.1 Device drivers
  75. ~~~~~~~~~~~~~~~~~~
  76. Device drivers are the modules that generate events. The events are
  77. however not useful without being handled, so you also will need to use some
  78. of the modules from section 3.2.
  79. 3.1.1 usbhid
  80. ~~~~~~~~~~~~
  81. usbhid is the largest and most complex driver of the whole suite. It
  82. handles all HID devices, and because there is a very wide variety of them,
  83. and because the USB HID specification isn't simple, it needs to be this big.
  84. Currently, it handles USB mice, joysticks, gamepads, steering wheels
  85. keyboards, trackballs and digitizers.
  86. However, USB uses HID also for monitor controls, speaker controls, UPSs,
  87. LCDs and many other purposes.
  88. The monitor and speaker controls should be easy to add to the hid/input
  89. interface, but for the UPSs and LCDs it doesn't make much sense. For this,
  90. the hiddev interface was designed. See Documentation/usb/hiddev.txt
  91. for more information about it.
  92. The usage of the usbhid module is very simple, it takes no parameters,
  93. detects everything automatically and when a HID device is inserted, it
  94. detects it appropriately.
  95. However, because the devices vary wildly, you might happen to have a
  96. device that doesn't work well. In that case #define DEBUG at the beginning
  97. of hid-core.c and send me the syslog traces.
  98. 3.1.2 usbmouse
  99. ~~~~~~~~~~~~~~
  100. For embedded systems, for mice with broken HID descriptors and just any
  101. other use when the big usbhid wouldn't be a good choice, there is the
  102. usbmouse driver. It handles USB mice only. It uses a simpler HIDBP
  103. protocol. This also means the mice must support this simpler protocol. Not
  104. all do. If you don't have any strong reason to use this module, use usbhid
  105. instead.
  106. 3.1.3 usbkbd
  107. ~~~~~~~~~~~~
  108. Much like usbmouse, this module talks to keyboards with a simplified
  109. HIDBP protocol. It's smaller, but doesn't support any extra special keys.
  110. Use usbhid instead if there isn't any special reason to use this.
  111. 3.1.4 wacom
  112. ~~~~~~~~~~~
  113. This is a driver for Wacom Graphire and Intuos tablets. Not for Wacom
  114. PenPartner, that one is handled by the HID driver. Although the Intuos and
  115. Graphire tablets claim that they are HID tablets as well, they are not and
  116. thus need this specific driver.
  117. 3.1.5 iforce
  118. ~~~~~~~~~~~~
  119. A driver for I-Force joysticks and wheels, both over USB and RS232.
  120. It includes ForceFeedback support now, even though Immersion
  121. Corp. considers the protocol a trade secret and won't disclose a word
  122. about it.
  123. 3.2 Event handlers
  124. ~~~~~~~~~~~~~~~~~~
  125. Event handlers distribute the events from the devices to userland and
  126. kernel, as needed.
  127. 3.2.1 keybdev
  128. ~~~~~~~~~~~~~
  129. keybdev is currently a rather ugly hack that translates the input
  130. events into architecture-specific keyboard raw mode (Xlated AT Set2 on
  131. x86), and passes them into the handle_scancode function of the
  132. keyboard.c module. This works well enough on all architectures that
  133. keybdev can generate rawmode on, other architectures can be added to
  134. it.
  135. The right way would be to pass the events to keyboard.c directly,
  136. best if keyboard.c would itself be an event handler. This is done in
  137. the input patch, available on the webpage mentioned below.
  138. 3.2.2 mousedev
  139. ~~~~~~~~~~~~~~
  140. mousedev is also a hack to make programs that use mouse input
  141. work. It takes events from either mice or digitizers/tablets and makes
  142. a PS/2-style (a la /dev/psaux) mouse device available to the
  143. userland. Ideally, the programs could use a more reasonable interface,
  144. for example evdev
  145. Mousedev devices in /dev/input (as shown above) are:
  146. crw-r--r-- 1 root root 13, 32 Mar 28 22:45 mouse0
  147. crw-r--r-- 1 root root 13, 33 Mar 29 00:41 mouse1
  148. crw-r--r-- 1 root root 13, 34 Mar 29 00:41 mouse2
  149. crw-r--r-- 1 root root 13, 35 Apr 1 10:50 mouse3
  150. ...
  151. ...
  152. crw-r--r-- 1 root root 13, 62 Apr 1 10:50 mouse30
  153. crw-r--r-- 1 root root 13, 63 Apr 1 10:50 mice
  154. Each 'mouse' device is assigned to a single mouse or digitizer, except
  155. the last one - 'mice'. This single character device is shared by all
  156. mice and digitizers, and even if none are connected, the device is
  157. present. This is useful for hotplugging USB mice, so that programs
  158. can open the device even when no mice are present.
  159. CONFIG_INPUT_MOUSEDEV_SCREEN_[XY] in the kernel configuration are
  160. the size of your screen (in pixels) in XFree86. This is needed if you
  161. want to use your digitizer in X, because its movement is sent to X
  162. via a virtual PS/2 mouse and thus needs to be scaled
  163. accordingly. These values won't be used if you use a mouse only.
  164. Mousedev will generate either PS/2, ImPS/2 (Microsoft IntelliMouse) or
  165. ExplorerPS/2 (IntelliMouse Explorer) protocols, depending on what the
  166. program reading the data wishes. You can set GPM and X to any of
  167. these. You'll need ImPS/2 if you want to make use of a wheel on a USB
  168. mouse and ExplorerPS/2 if you want to use extra (up to 5) buttons.
  169. 3.2.3 joydev
  170. ~~~~~~~~~~~~
  171. Joydev implements v0.x and v1.x Linux joystick api, much like
  172. drivers/char/joystick/joystick.c used to in earlier versions. See
  173. joystick-api.txt in the Documentation subdirectory for details. As
  174. soon as any joystick is connected, it can be accessed in /dev/input
  175. on:
  176. crw-r--r-- 1 root root 13, 0 Apr 1 10:50 js0
  177. crw-r--r-- 1 root root 13, 1 Apr 1 10:50 js1
  178. crw-r--r-- 1 root root 13, 2 Apr 1 10:50 js2
  179. crw-r--r-- 1 root root 13, 3 Apr 1 10:50 js3
  180. ...
  181. And so on up to js31.
  182. 3.2.4 evdev
  183. ~~~~~~~~~~~
  184. evdev is the generic input event interface. It passes the events
  185. generated in the kernel straight to the program, with timestamps. The
  186. API is still evolving, but should be useable now. It's described in
  187. section 5.
  188. This should be the way for GPM and X to get keyboard and mouse
  189. events. It allows for multihead in X without any specific multihead
  190. kernel support. The event codes are the same on all architectures and
  191. are hardware independent.
  192. The devices are in /dev/input:
  193. crw-r--r-- 1 root root 13, 64 Apr 1 10:49 event0
  194. crw-r--r-- 1 root root 13, 65 Apr 1 10:50 event1
  195. crw-r--r-- 1 root root 13, 66 Apr 1 10:50 event2
  196. crw-r--r-- 1 root root 13, 67 Apr 1 10:50 event3
  197. ...
  198. And so on up to event31.
  199. 4. Verifying if it works
  200. ~~~~~~~~~~~~~~~~~~~~~~~~
  201. Typing a couple keys on the keyboard should be enough to check that
  202. a USB keyboard works and is correctly connected to the kernel keyboard
  203. driver.
  204. Doing a cat /dev/input/mouse0 (c, 13, 32) will verify that a mouse
  205. is also emulated, characters should appear if you move it.
  206. You can test the joystick emulation with the 'jstest' utility,
  207. available in the joystick package (see Documentation/input/joystick.txt).
  208. You can test the event devices with the 'evtest' utility available
  209. in the LinuxConsole project CVS archive (see the URL below).
  210. 5. Event interface
  211. ~~~~~~~~~~~~~~~~~~
  212. Should you want to add event device support into any application (X, gpm,
  213. svgalib ...) I <vojtech@ucw.cz> will be happy to provide you any help I
  214. can. Here goes a description of the current state of things, which is going
  215. to be extended, but not changed incompatibly as time goes:
  216. You can use blocking and nonblocking reads, also select() on the
  217. /dev/input/eventX devices, and you'll always get a whole number of input
  218. events on a read. Their layout is:
  219. struct input_event {
  220. struct timeval time;
  221. unsigned short type;
  222. unsigned short code;
  223. unsigned int value;
  224. };
  225. 'time' is the timestamp, it returns the time at which the event happened.
  226. Type is for example EV_REL for relative moment, REL_KEY for a keypress or
  227. release. More types are defined in include/linux/input.h.
  228. 'code' is event code, for example REL_X or KEY_BACKSPACE, again a complete
  229. list is in include/linux/input.h.
  230. 'value' is the value the event carries. Either a relative change for
  231. EV_REL, absolute new value for EV_ABS (joysticks ...), or 0 for EV_KEY for
  232. release, 1 for keypress and 2 for autorepeat.