2 <title>Supporting Input Devices</title>
5 A working console and keyboard during the initial boot image execution
6 is needed to enter a password for encrypted file systems; it also
7 helps while debugging. This section discusses the kernel input
8 layer and how it can be supported during image generation.
12 The console is a designated terminal, where kernel output goes, and that
13 is the initial I/O device for <filename>/sbin/init</filename>. Like all
14 terminal devices, it provides a number of functions: you can read
15 and write to it, plus it has a number of <code>ioctl()</code>
16 functions to manage line buffering, interrupt characters and
17 baudrate or parity where applicable.
21 Terminals come in different types: it can be a VT100 or terminal
22 emulator connected via an RS232 cable, or it can be a combination
23 of a CRT and a keyboard. The keyboard can be connected via
24 USB or it can talk a byte oriented protocol via a legacy UART
29 The CRT is managed in two layers. The top layer, "virtual
30 terminal", manages a two dimensional array describing which letter
31 should go in which position of the screen. In fact, there are a
32 number of different arrays, and which one is actually visible on
33 the screen is selected by a keyboard combination.
34 Below the virtual terminals is a layer that actually places the
35 letters on the screen. This can be done a letter at a time,
36 using a VGA interface, or the letters can be painted pixel by
37 pixel, using a frame buffer.
41 Below the terminal concept we find the input layer. This provides a
42 unified interface to the various user input devices: mouse, keyboard,
43 PC speaker, joystick, tablet. These input devices not only
44 generate data, they can also receive input from the computer. As
45 an example, the keyboard needs computer input to operate the NUM
46 LOCK indicator. Hardware devices such as keyboards register
47 themselves with the input layer, describing their capabilities
48 (I can send relative position, have two buttons and no LEDs),
49 and the input layer assigns a handler to the hardware device.
50 The handler presents the device to upper layers, either as a char
51 special file or as the input part of a terminal device.
52 This is not a one-to-one mapping: every mouse gets its own
53 handler, but keyboard and PC speaker share a handler, so it looks
54 to userland like you have a keyboard that can do "beep".
58 In addition to handlers for specific type of upper layers (mouse,
59 joystick, touch screen) there is a generic handler that provides a
60 character device file such as <filename>/dev/input/event0</filename>
61 for every input device detected; input events are presented through
62 these devices in a unified format. The input layer generates
63 hotplug events for these generic event handlers; hotplug uses
64 <filename>modules.inputmap</filename> to load a module containing a
65 suitable upper layer event handler. The keyboard handler is a special
66 case that does not occur in this map, so for image generation there
67 is little to be learned from hotplug input support.
71 To guarantee a working console, <application>yaird</application>
72 should examine <filename>/dev/console</filename>, determine
73 whether it's RS232 or hardware directly connected to the computer,
74 and then load modules for either serial port, or for virtual
75 terminals, the input layer and any hardware underlying it.
76 Unfortunately, <filename>/dev/console</filename> does not give
77 a hint what is below the terminal interface, and unfortunately,
78 lots of input devices are legacy hardware that is hard to probe
79 and only sketchily described by sysfs in kernel 2.6.10.
83 This means that a guarantee for a working console cannot be made,
84 which is why distribution kernels come with components such as the
85 keyboard and serial port driver compiled into the kernel. We can
86 do something else though: provide modules for keyboard devices
87 provided the kernel provides correct information. That covers the
88 case of USB keyboards, and that's something that's not compiled
89 into distribution kernels, so that the administrator has to add
90 modules explictly in order to get the keyboard working in
91 the initial boot image.
95 Lets examine the sources of information we have to find which input
96 hardware we have to support.
101 In <filename>/sys/class/input</filename>, all input devices
102 are enumerated. Mostly, these only contain a
103 <filename>dev</filename> file containing major/minor number,
104 but USB devices also have a <filename>device</filename>
105 symlink into <filename>/sys/devices</filename> identifying
106 the underlying hardware.
112 In <filename>/boot/menu/grub.lst</filename>, kernel options
113 can be defined that determine whether to use a serial line as
114 console and whether to use a frame buffer. The consequence
115 is that it is fundamentally impossible to determine by looking
116 at the hardware alone what's needed to get an image that will
117 boot without problems. This probably means we'll have to consider
118 supplying some modules in the image that will only get loaded
119 depending on kernel options.
125 The file <filename>/proc/bus/input/devices</filename> gives
126 a formatted overview of all known input devices; entries look
129 I: Bus=0003 Vendor=413c Product=2003 Version=0100
130 N: Name="DELL DELL USB Keyboard"
131 P: Phys=usb-0000:00:1d.7-4.1/input1
132 H: Handlers=kbd event2
134 B: KEY=7f f0000 0 3878 d801d101 1e0000 0 0 0
136 Here the "I" line shows identification information passed to
137 the input layer by the hardware driver that is used to look
138 up the appropiate handler. "N" is a printable name provided
139 by the hardware driver. "P" is a hint at location in a bus
140 of the device; note how this line is completely unrelated to
141 the location of the hardware in
142 <filename>/sys/devices</filename>.
143 The H (Handlers) line is obvious; The B lines specify
144 capabilities of the device, plus extra information for each
145 capability. Known capabilities include:
146 <informaltable frame='topbot'>
147 <tgroup cols='2' align='left'>
150 <entry>Capability</entry>
151 <entry>Description</entry>
157 <entry>Input event is completed</entry>
161 <entry>Key press/release event</entry>
165 <entry>Relative measure, as in mouse movement</entry>
169 <entry>Absolute position, as in graphics
174 <entry>Miscelanious</entry>
182 <entry>Set hardware repeat</entry>
186 <entry>Don't know</entry>
190 <entry>Power event: on/off switch pressed.</entry>
193 <entry>FF_STATUS</entry>
194 <entry>Don't know.</entry>
205 Finally, let's consider some kernel configuration defines, the
206 corresponding modules and their function. This could be used as a
207 start to check whether all components required to make an
208 operational console are available on the generated image:
209 <informaltable frame='topbot'>
210 <tgroup cols='3' align='left'>
213 <entry>Define</entry>
214 <entry>Module</entry>
215 <entry>Description</entry>
222 <entry>(bool)</entry>
224 Support multiple virtual terminals, irrespective of what
225 hardware is used to display letters from the virtual
231 <entry>VT_CONSOLE</entry>
232 <entry>(bool)</entry>
234 Make the VT a candidate for console output. The alternative
235 is a serial line to a VT100 or terminal emulator
240 <entry>VGA_CONSOLE</entry>
241 <entry>(bool)</entry>
243 Display a terminal on CRT using the VGA interface.
248 <entry>FRAMEBUFFER_CONSOLE</entry>
251 Display a terminal on a framebuffer, painting letters a
252 pixel at a time. This has to know about fonts.
257 <entry>FB_VESA</entry>
258 <entry>vesafb</entry>
260 Implement a framebuffer based on VESA (a common standard
261 for PC graphic cards), a place where an X server or
262 the framebuffer console can write pixels to be displayed
264 There are many different framebuffer modules that
265 optimise for different graphics cards.
266 Note that while vesafb and other drivers such as intelfb
267 can be built as a module, they only function correctly
268 when built into the kernel. Most framebuffer modules
269 depend on three other modules to function correctly:
270 cfbfillrect, cfbcopyarea, cfbimgblt.
278 Interpret input from a standard AT or PS/2 keyboard.
279 Other keyboards use other byte codes, see for example
280 the Acorn keyboard (rpckbd).
288 Module that manages a stream of bytes from and to an IO port.
289 It includes a kernel thread (kseriod) that handles the queue
290 needed to talk to slow ports. It is normally used for
291 dedicated IO ports talking to PS/2 mouse and keyboard,
292 but can also be interfaced to serial ports (COM1, COM2).
293 The atkbd driver uses a serio driver to communicate with
299 <entry>SERIO_I8042</entry>
302 Implement a serio stream on top of the i8042 chip, the chip
303 that connects the standard AT keyboard and PS/2 mouse to
305 This is legacy hardware: it's not connected via PCI but
306 directly to the 'platform bus'.
307 When a chip such as i8042 that implements
308 serio is detected, it registers itself with the input
309 layer. The input layer then lets drivers that use serio
310 (such as atkbd and psmouse) probe whether a known device
311 is connected via the chip; if such a device is found,
312 it is registered as a new input device.
317 <entry>SERIAL_8250</entry>
318 <entry>serial</entry>
320 Support for serial ports (COM1, COM2) on PC hardware.
321 Lots of other configuration options exist to support
322 multiple cards and fiddle with interrupts.
323 If compiled in rather than modular, a further option,
324 SERIAL_8250_CONSOLE, allows using the serial port as a
330 <entry>USB_HID</entry>
331 <entry>usbhid</entry>
333 Driver for USB keyboards and mice.
334 Another define, USB_HIDINPUT, needs to be true for
335 these devices to actually work.
340 <entry>USB_KBD</entry>
341 <entry>usbkbd</entry>
343 Severely limited form of USB keyboard; uses the "boot
344 protocol". This conflicts with the complete driver.
355 The following figure gives an example of how the various modules
359 <figure id="console-module-flow">
361 Module relation for common console setup
365 <imagedata fileref="figures/console.png" format="PNG"/>
371 In practical terms, a first step toward a more robust boot image
372 is to support new keyboard types, such as USB keyboards.
373 The following algorithm should do that.
379 Interpret <filename>/proc/bus/input/devices</filename>.
385 Look for devices that have handler kbd <emphasis>and</emphasis>
386 that have buttons. Mice and the PC speaker don't match that
387 criterium, keyboards do.
393 You could interpret the name field of such devices if you're
394 interested in supporting legacy keyboards.
400 The devices that have handler 'kbd' also have a handler 'event\d',
401 where input is presented in a generalised event format;
402 look up this device in /sys/class/input/event\d/.
408 If it's got a device symlink, load the hardware drivers for that
409 hardware device (most likely it's usbhid plus a usb core driver).
415 Don't bother with a mknod, the input is handled via
416 <filename>/dev/console</filename>.
422 Otherwise it's presumable a legacy device; you could check for
424 <filename>/sys/devices/platform/i8042/serio\d/</filename>,
425 or you could just assume the appropriate driver to be compiled in.
431 Implement support for
432 <filename>/etc/hotplug/blacklist</filename>,
433 since some USB keyboards publish two interfaces (full HID
434 and the limited boot protocol), the input layer makes both
435 visible in <filename>/proc/bus/input/devices</filename> and
436 the corresponding modules are mutually conflicting.
437 The blacklist is used to filter out one of these modules.
projects / bacula / rescue / blob