/[gentoo]/xml/htdocs/doc/en/udev-guide.xml
Gentoo

Contents of /xml/htdocs/doc/en/udev-guide.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.44 - (show annotations) (download) (as text)
Tue Oct 30 20:31:27 2007 UTC (10 years, 3 months ago) by nightmorph
Branch: MAIN
Changes since 1.43: +61 -3 lines
File MIME type: application/xml
added udev module order section, as suggested by zzam via email

1 <?xml version='1.0' encoding="UTF-8"?>
2 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/udev-guide.xml,v 1.43 2007/10/18 18:31:06 nightmorph Exp $ -->
4
5 <guide link="/doc/en/udev-guide.xml">
6 <title>Gentoo udev Guide</title>
7
8 <author title="Author">
9 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
10 </author>
11 <author title="Contributor">
12 <mail link="greg_g@gentoo.org">Gregorio Guidi</mail>
13 </author>
14 <author title="Editor">
15 <mail link="nightmorph"/>
16 </author>
17
18 <abstract>
19 This document explains what udev is and how you can use udev to fit your needs.
20 </abstract>
21
22 <!-- The content of this document is licensed under the CC-BY-SA license -->
23 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
24 <license/>
25
26 <version>0.33</version>
27 <date>2007-10-30</date>
28
29 <chapter>
30 <title>What is udev?</title>
31 <section>
32 <title>The /dev Directory</title>
33 <body>
34
35 <p>
36 When Linux-users talk about the hardware on their system in the vicinity of
37 people who believe Linux is some sort of virus or brand of coffee, the use of
38 "slash dev slash foo" will return a strange look for sure. But for the fortunate
39 user (and that includes you) using <path>/dev/hda1</path> is just a fast way of
40 explaining that we are talking about the primary master IDE, first partition. Or
41 aren't we?
42 </p>
43
44 <p>
45 We all know what a device file is. Some even know why device files have special
46 numbers when we take a closer look at them when we issue <c>ls -l</c> in
47 <path>/dev</path>. But what we always take for granted is that the primary
48 master IDE disk is referred to as <path>/dev/hda</path>. You might not see it
49 this way, but this is a flaw by design.
50 </p>
51
52 <p>
53 Think about hotpluggable devices like USB, IEEE1394, hot-swappable PCI, ... What
54 is the first device? And for how long? What will the other devices be named when
55 the first one disappears? How will that affect ongoing transactions? Wouldn't it
56 be fun that a printing job is suddenly moved from your supernew laserprinter to
57 your almost-dead matrix printer because your mom decided to pull the plug of the
58 laserprinter which happened to be the first printer?
59 </p>
60
61 <p>
62 Enter <e>udev</e>. The goals of the udev project are both interesting and
63 needed:
64 </p>
65
66 <ul>
67 <li>Runs in userspace</li>
68 <li>Dynamically creates/removes device files</li>
69 <li>Provides consistent naming</li>
70 <li>Provides a user-space API</li>
71 </ul>
72
73 <p>
74 To provide these features, udev is developed in three separate projects:
75 <e>namedev</e>, <e>libsysfs</e> and, of course, <e>udev</e>.
76 </p>
77
78 </body>
79 </section>
80 <section>
81 <title>namedev</title>
82 <body>
83
84 <p>
85 Namedev allows you to define the device naming separately from the udev program.
86 This allows for flexible naming policies and naming schemes developed by
87 separate entities. This device naming subsystem provides a standard interface
88 that udev can use.
89 </p>
90
91 <p>
92 Currently only a single naming scheme is provided by namedev; the one provided
93 by LANANA, used by the majority of Linux systems currently and therefore very
94 suitable for the majority of Linux users.
95 </p>
96
97 <p>
98 Namedev uses a 5-step procedure to find out the name of a given device. If the
99 device name is found in one of the given steps, that name is used. The steps
100 are:
101 </p>
102
103 <ul>
104 <li>label or serial number</li>
105 <li>bus device number</li>
106 <li>bus topology</li>
107 <li>statically given name</li>
108 <li>kernel provided name</li>
109 </ul>
110
111 <p>
112 The <e>label or serial number</e> step checks if the device has a unique
113 identifier. For instance USB devices have a unique USB serial number; SCSI
114 devices have a unique UUID. If namedev finds a match between this unique number
115 and a given configuration file, the name provided in the configuration file is
116 used.
117 </p>
118
119 <p>
120 The <e>bus device number</e> step checks the device bus number. For
121 non-hot-swappable environments this procedure is sufficient to
122 identify a hardware device. For instance PCI bus numbers rarely change in the
123 lifetime of a system. Again, if namedev finds a match between this position and
124 a given configuration file, the name provided in that configuration file is
125 used.
126 </p>
127
128 <p>
129 Likewise the <e>bus topology</e> is a rather static way of defining devices as
130 long as the user doesn't switch devices. When the position of the device matches
131 a given setting provided by the user, the accompanying name is used.
132 </p>
133
134 <p>
135 The fourth step, <e>statically given name</e>, is a simple string replacement.
136 When the kernel name (the default name) matches a given replacement string, the
137 substitute name will be used.
138 </p>
139
140 <p>
141 The final step (<e>kernel provided name</e>) is a catch-all: this one takes
142 the default name provided by the kernel. In the majority of cases this is
143 sufficient as it matches the device naming used on current Linux systems.
144 </p>
145
146 </body>
147 </section>
148 <section>
149 <title>libsysfs</title>
150 <body>
151
152 <p>
153 udev interacts with the kernel through the sysfs pseudo filesystem. The libsysfs
154 project provides a common API to access the information given by the sysfs
155 filesystem in a generic way. This allows for querying all kinds of hardware
156 without having to make assumptions on the kind of hardware.
157 </p>
158
159 </body>
160 </section>
161 <section>
162 <title>udev</title>
163 <body>
164
165 <p>
166 Every time the kernel gets an event in the device structure, it asks udev to
167 take a look. udev follows the rules in the <path>/etc/udev/rules.d/</path>
168 directory. udev then uses the information given by the kernel to perform the
169 necessary actions on the <path>/dev</path> structure (creating or deleting
170 device files).
171 </p>
172
173 </body>
174 </section>
175 </chapter>
176
177 <chapter>
178 <title>Using udev on Gentoo</title>
179 <section>
180 <title>Requirements</title>
181 <body>
182
183 <p>
184 udev is meant to be used in combination with a 2.6 kernel (like
185 <c>gentoo-sources</c> with the default 2007.0 profile). If you're using such a
186 kernel then you just have to make sure that you have a recent
187 <c>sys-apps/baselayout</c> version. That's all you need.
188 </p>
189
190 <pre caption="Installing udev">
191 # <i>emerge udev</i>
192 </pre>
193
194 <p>
195 Kernelwise, be sure to activate the following options:
196 </p>
197
198 <pre caption="Required kernel options">
199 General setup ---&gt;
200 [*] Support for hot-pluggable devices
201
202 File systems ---&gt;
203 Pseudo filesystems ---&gt;
204 [*] /proc file system support
205 [*] Virtual memory file system support (former shm fs)
206 </pre>
207
208 <p>
209 If you use <c>genkernel</c>, don't forget to run it with the <c>--udev</c>
210 option to enable all the required kernel configuration directives. The default
211 configuration given by this <c>genkernel</c> invocation is sufficient.
212 </p>
213
214 </body>
215 </section>
216 <section>
217 <title>Configuration</title>
218 <body>
219
220 <p>
221 If you want to use the udev-tweaks Gentoo added to make your life
222 comfortable, then read no more. Gentoo will use udev but keep a static
223 <path>/dev</path> so that you will never have any missing device nodes.
224 The Gentoo init scripts won't run the devfsd daemon and will deactivate devfs
225 when you boot up.
226 </p>
227
228 <p>
229 But if you are a die-hard and want to run a udev-only, no-tweaked system as is
230 intended by the udev development (including the difficulties of missing device
231 nodes because udev doesn't support them yet), by all means, read on :)
232 </p>
233
234 <p>
235 We'll deactivate the rules that save the device file nodes: edit the
236 <c>RC_DEVICE_TARBALL</c> variable in <path>/etc/conf.d/rc</path> and set it to
237 <c>no</c>:
238 </p>
239
240 <pre caption="/etc/conf.d/rc">
241 RC_DEVICE_TARBALL="no"
242 </pre>
243
244 <p>
245 If you have included devfs support in your kernel, you can deactivate it in
246 the bootloader configuration: add <c>gentoo=nodevfs</c> as a kernel parameter.
247 If you want to use devfs and deactivate udev, add <c>gentoo=noudev</c> as kernel
248 parameter.
249 </p>
250
251 </body>
252 </section>
253 </chapter>
254
255 <chapter>
256 <title>Known Issues</title>
257 <section>
258 <title>Missing device node files at boot</title>
259 <body>
260
261 <p>
262 If you can't boot successfully because you get an error about
263 <path>/dev/null</path> not found, or because the initial console is missing, the
264 problem is that you lack some device files that must be available <e>before</e>
265 <path>/dev</path> is mounted and handled by udev. This is common on Gentoo
266 machines installed from old media.
267 </p>
268
269 <p>
270 If you run <c>sys-apps/baselayout-1.8.12</c> or later, this problem is
271 alleviated since the boot process should still manage to complete. However, to
272 get rid of those annoying warnings, you should create the missing device nodes
273 as described below.
274 </p>
275
276 <p>
277 To see which devices nodes are present before the <path>/dev</path> filesystem
278 is mounted, run the following commands:
279 </p>
280
281 <pre caption="Listing device nodes available at boot">
282 # <i>mkdir test</i>
283 # <i>mount --bind / test</i>
284 # <i>cd test/dev</i>
285 # <i>ls</i>
286 </pre>
287
288 <p>
289 The devices needed for a successful boot are <path>/dev/null</path> and
290 <path>/dev/console</path>. If they didn't show up in the previous test, you have
291 to create them manually. Issue the following commands in the
292 <path>test/dev/</path> directory:
293 </p>
294
295 <pre caption="Creating necessary device node files">
296 # <i>mknod -m 660 console c 5 1</i>
297 # <i>mknod -m 660 null c 1 3</i>
298 </pre>
299
300 <p>
301 When you're finished, don't forget to unmount the <path>test/</path> directory:
302 </p>
303
304 <pre caption="Unmounting the test/ directory">
305 # <i>cd ../..</i>
306 # <i>umount test</i>
307 # <i>rmdir test</i>
308 </pre>
309
310 </body>
311 </section>
312 <section>
313 <title>udev and nvidia</title>
314 <body>
315
316 <p>
317 If you use the proprietary driver from nVidia and the X server fails to start on
318 a udev-only system, then make sure you have:
319 </p>
320
321 <ul>
322 <li>
323 the <c>nvidia</c> module listed in
324 <path>/etc/modules.autoload.d/kernel-2.6</path>
325 </li>
326 <li>
327 a version of baselayout equal to or greater than
328 <c>sys-apps/baselayout-1.8.12</c>
329 </li>
330 </ul>
331
332 </body>
333 </section>
334 <section>
335 <title>No Consistent Naming between DevFS and udev</title>
336 <body>
337
338 <p>
339 Even though our intention is to have a consistent naming scheme between both
340 dynamical device management solutions, sometimes naming differences do occur.
341 </p>
342
343 <p>
344 One reported clash is with a HP Smart Array 5i RAID controller (more precisely
345 the <c>cciss</c> kernel module). With udev, the devices are named
346 <path>/dev/cciss/cXdYpZ</path> with X, Y and Z regular numbers. With devfs, the
347 devices are <path>/dev/hostX/targetY/partZ</path> or symlinked from
348 <path>/dev/cciss/cXdY</path>.
349 </p>
350
351 <p>
352 If this is the case, don't forget to update your <path>/etc/fstab</path> and
353 bootloader configuration files accordingly.
354 </p>
355
356 <p>
357 The same happens with all-round symlinks that used to exist in
358 <path>/dev</path>, such as <path>/dev/mouse</path>, which <c>udev</c> doesn't
359 create anymore. Be certain to check your X configuration file and see if the
360 Device rule for your mouse points to an existing device file.
361 </p>
362
363 <p>
364 Another issue is the difference in naming of terminals between devfs and udev.
365 While devfs calls its terminals <c>tty</c>, udev calls them <c>vc</c> and
366 <c>tty</c>. This could lead to a problem in case you are restricting root
367 logins from consoles using <path>/etc/securetty</path>. You will need to make
368 sure that both <c>tty1</c> and <c>vc/1</c> are listed in
369 <path>/etc/securetty</path> to ensure that root can login using the console.
370 </p>
371
372 </body>
373 </section>
374 <section>
375 <title>Device renaming</title>
376 <body>
377
378 <p>
379 Recent versions of udev (104 and up) along with newer kernel versions (2.6.19
380 and up) may change your disc device names, due to a change in the kernel's
381 libata implementation. A CD-RW device at <path>/dev/hdc</path> may be changed to
382 <path>/dev/sr0</path>. While this is not normally a problem, it may cause issues
383 for some applications that are hardcoded to look for devices at other locations.
384 For example, <c>media-sound/rip</c> expects to find discs at
385 <path>/dev/cdrom</path>, which becomes a problem if you use a newer kernel and
386 udev renames your device to <path>/dev/cdrom1</path>.
387 </p>
388
389 <p>
390 To work around these issues, you must edit
391 <path>/etc/udev/rules.d/70-persistent-cd.rules</path> and assign the correct
392 name to the device.
393 </p>
394
395 <p>
396 For more information on writing udev rules, be sure to read Daniel Drake's <uri
397 link="http://www.reactivated.net/udevrules.php">guide</uri>.
398 </p>
399
400 </body>
401 </section>
402 <section>
403 <title>udev loads modules in an unpredictable order</title>
404 <body>
405
406 <p>
407 Sometimes udev loads modules in an undesired, unpredictable, or seemingly random
408 order. This is especially common for systems that have multiple devices of the
409 same type, as well as multimedia devices. This can affect the assigned numbers
410 of devices; for example, sound cards may sometimes swap numbers.
411 </p>
412
413 <p>
414 There are a few solutions to fix device numbers and/or module load order.
415 Ideally, you can just use module parameters to specify your desired device
416 number. Some modules, such as ALSA, include the "index" parameter. Modules that
417 use the index parameter can be adjusted as shown. This example is for a system
418 with two sound cards. The card with an index of 0 is designated as the first
419 card. Once the parameters are changed, the module config files must be updated.
420 </p>
421
422 <pre caption="Specifying module parameters">
423 # <i>echo "option snd-ice1724 index=0" >> /etc/modules.d/alsa</i>
424 # <i>echo "option snd-ymfpci index=1" >> /etc/modules.d/alsa</i>
425 # <i>update-modules</i>
426 </pre>
427
428 <p>
429 The above example is the preferred solution, but not all modules support
430 parameters such as index. For these modules, you'll have to force the correct
431 module load order. First, you must stop udev from autoloading the modules by
432 blacklisting them. Be sure to use the exact name of the module being loaded.
433 For PCI devices, you'll need to use the module names obtained from the output of
434 <c>pcimodules</c>, available in the <c>pciutils</c> package. The following
435 example uses DVB modules.
436 </p>
437
438 <pre caption="Blacklisting modules">
439 # <i>echo "blacklist b2c2-flexcop-pci" >> /etc/modules.d/dvb</i>
440 # <i>echo "blacklist budget" >> /etc/modules.d/dvb</i>
441 # <i>update-modules</i>
442 </pre>
443
444 <p>
445 Next, load the modules in the correct order. Add them to
446 <path>/etc/modules.autoload.d/kernel-2.6</path> <e>in the exact order you want
447 them loaded</e>.
448 </p>
449
450 <pre caption="Loading modules in the correct order">
451 # <i>echo "budget" >> /etc/modules.autoload.d/kernel-2.6</i>
452 # <i>echo "b2c2-flexcop-pci" >> /etc/modules.autoload.d/kernel-2.6</i>
453 </pre>
454
455 </body>
456 </section>
457 <section>
458 <title>Other issues</title>
459 <body>
460
461 <p>
462 If device nodes are not created when a module is loaded from
463 <path>/etc/modules.autoload.d/kernel-2.6</path> but they appear when you load
464 the module manually with modprobe then you should try upgrading to
465 <c>sys-apps/baselayout-1.8.12</c> or later.
466 </p>
467
468 <p>
469 Support for the framebuffer devices (<path>/dev/fb/*</path>) comes with the
470 kernel starting from version 2.6.6-rc2.
471 </p>
472
473 <p>
474 For kernels older than 2.6.4 you have to explicitly include support for the
475 <path>/dev/pts</path> filesystem.
476 </p>
477
478 <pre caption="Enabling the /dev/pts filesystem">
479 File systems ---&gt;
480 Pseudo filesystems ---&gt;
481 [*] /dev/pts file system for Unix98 PTYs
482 </pre>
483
484 </body>
485 </section>
486 </chapter>
487
488 <chapter>
489 <title>Resources &amp; Acknowledgements</title>
490 <section>
491 <body>
492
493 <p>
494 The udev talk on the Linux Symposium (Ottawa, Ontario Canada - 2003) given by
495 Greg Kroah-Hartman (IBM Corporation) provided a solid understanding on the udev
496 application.
497 </p>
498
499 <p>
500 <uri link="http://webpages.charter.net/decibelshelp/LinuxHelp_UDEVPrimer.html">Decibel's
501 UDEV Primer</uri> is an in-depth document about udev and Gentoo.
502 </p>
503
504 <p>
505 <uri link="http://www.reactivated.net/udevrules.php">Writing udev rules</uri> by
506 fellow Gentoo developer Daniel Drake is an excellent document to learn how to
507 customize your udev installation.
508 </p>
509
510 </body>
511 </section>
512 </chapter>
513 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20