/[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.47 - (hide annotations) (download) (as text)
Tue Aug 19 12:51:15 2008 UTC (9 years, 6 months ago) by swift
Branch: MAIN
Changes since 1.46: +5 -5 lines
File MIME type: application/xml
#234913 - Change wording on tweaks

1 swift 1.1 <?xml version='1.0' encoding="UTF-8"?>
2     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 swift 1.47 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/udev-guide.xml,v 1.46 2008/06/16 08:10:56 nightmorph Exp $ -->
4 neysx 1.4
5 swift 1.1 <guide link="/doc/en/udev-guide.xml">
6     <title>Gentoo udev Guide</title>
7    
8     <author title="Author">
9 nightmorph 1.34 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
10 swift 1.8 </author>
11     <author title="Contributor">
12 neysx 1.24 <mail link="greg_g@gentoo.org">Gregorio Guidi</mail>
13 swift 1.1 </author>
14 nightmorph 1.44 <author title="Editor">
15     <mail link="nightmorph"/>
16     </author>
17 swift 1.1
18     <abstract>
19     This document explains what udev is and how you can use udev to fit your needs.
20     </abstract>
21    
22 nightmorph 1.43 <!-- The content of this document is licensed under the CC-BY-SA license -->
23     <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
24 swift 1.1 <license/>
25    
26 swift 1.47 <version>2</version>
27     <date>2008-08-19</date>
28 swift 1.1
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 swift 1.3 people who believe Linux is some sort of virus or brand of coffee, the use of
38 swift 1.1 "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 swift 1.3 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 swift 1.1 the first one disappears? How will that affect ongoing transactions? Wouldn't it
56 swift 1.45 be fun that a printing job is suddenly moved from your supernew laserprinter to
57 swift 1.1 your almost-dead matrix printer because your mom decided to pull the plug of the
58 swift 1.20 laserprinter which happened to be the first printer?
59 swift 1.1 </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 swift 1.3 <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 swift 1.1 </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 swift 1.3 by LANANA, used by the majority of Linux systems currently and therefore very
94 swift 1.1 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 swift 1.45 The <e>bus device number</e> step checks the device bus number. For
121 swift 1.1 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 swift 1.3 a given setting provided by the user, the accompanying name is used.
132 swift 1.1 </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 swift 1.45 substitute name will be used.
138 swift 1.1 </p>
139    
140     <p>
141 swift 1.45 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 swift 1.1 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 nightmorph 1.39 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 swift 1.1 </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 swift 1.8 udev is meant to be used in combination with a 2.6 kernel (like
185 nightmorph 1.39 <c>gentoo-sources</c> with the default 2007.0 profile). If you're using such a
186 nightmorph 1.37 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 swift 1.1 </p>
189    
190 swift 1.8 <pre caption="Installing udev">
191     # <i>emerge udev</i>
192 swift 1.1 </pre>
193    
194     <p>
195 swift 1.21 Kernelwise, be sure to activate the following options:
196 swift 1.1 </p>
197    
198     <pre caption="Required kernel options">
199 swift 1.6 General setup ---&gt;
200 swift 1.1 [*] 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 swift 1.21 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 swift 1.1 </body>
215     </section>
216     <section>
217     <title>Configuration</title>
218     <body>
219    
220     <p>
221 swift 1.47 If you want to use the udev settings Gentoo provides to make your life
222 swift 1.15 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 swift 1.45 The Gentoo init scripts won't run the devfsd daemon and will deactivate devfs
225     when you boot up.
226 swift 1.1 </p>
227    
228     <p>
229 swift 1.47 But if you are a die-hard and want to run a udev-only, unmodified system as is
230 swift 1.2 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 swift 1.1 </p>
233    
234     <p>
235 swift 1.45 We'll deactivate the rules that save the device file nodes: edit the
236 swift 1.2 <c>RC_DEVICE_TARBALL</c> variable in <path>/etc/conf.d/rc</path> and set it to
237     <c>no</c>:
238     </p>
239 swift 1.1
240 swift 1.2 <pre caption="/etc/conf.d/rc">
241     RC_DEVICE_TARBALL="no"
242 swift 1.1 </pre>
243    
244     <p>
245 swift 1.8 If you have included devfs support in your kernel, you can deactivate it in
246 swift 1.45 the bootloader configuration: add <c>gentoo=nodevfs</c> as a kernel parameter.
247 swift 1.14 If you want to use devfs and deactivate udev, add <c>gentoo=noudev</c> as kernel
248 swift 1.8 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 neysx 1.9 If you can't boot successfully because you get an error about
263 swift 1.8 <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 swift 1.10 get rid of those annoying warnings, you should create the missing device nodes
273 swift 1.8 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 neysx 1.9 The devices needed for a successful boot are <path>/dev/null</path> and
290 swift 1.8 <path>/dev/console</path>. If they didn't show up in the previous test, you have
291 cam 1.12 to create them manually. Issue the following commands in the
292     <path>test/dev/</path> directory:
293 swift 1.1 </p>
294    
295     <pre caption="Creating necessary device node files">
296 cam 1.11 # <i>mknod -m 660 console c 5 1</i>
297     # <i>mknod -m 660 null c 1 3</i>
298 swift 1.1 </pre>
299    
300     <p>
301 swift 1.8 When you're finished, don't forget to unmount the <path>test/</path> directory:
302 swift 1.1 </p>
303    
304 swift 1.8 <pre caption="Unmounting the test/ directory">
305 cam 1.11 # <i>cd ../..</i>
306 swift 1.8 # <i>umount test</i>
307 cam 1.11 # <i>rmdir test</i>
308 swift 1.8 </pre>
309    
310     </body>
311     </section>
312     <section>
313     <title>udev and nvidia</title>
314     <body>
315    
316 swift 1.1 <p>
317 swift 1.8 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 swift 1.1 </p>
320    
321 swift 1.8 <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 swift 1.1 </body>
333     </section>
334     <section>
335 swift 1.18 <title>No Consistent Naming between DevFS and udev</title>
336     <body>
337    
338     <p>
339 swift 1.45 Even though our intention is to have a consistent naming scheme between both
340 swift 1.18 dynamical device management solutions, sometimes naming differences do occur.
341 swift 1.22 </p>
342    
343     <p>
344 swift 1.18 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 swift 1.22 <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 swift 1.23 Device rule for your mouse points to an existing device file.
361 swift 1.22 </p>
362    
363 fox2mike 1.29 <p>
364     Another issue is the difference in naming of terminals between devfs and udev.
365 nightmorph 1.31 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 fox2mike 1.29 </p>
371    
372 swift 1.18 </body>
373     </section>
374     <section>
375 nightmorph 1.41 <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 nightmorph 1.44 <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 nightmorph 1.46 # <i>echo "blacklist b2c2-flexcop-pci" >> /etc/modprobe.d/dvb</i>
440     # <i>echo "blacklist budget" >> /etc/modprobe.d/dvb</i>
441 nightmorph 1.44 # <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 swift 1.8 <title>Other issues</title>
459 swift 1.1 <body>
460    
461 swift 1.8 <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 swift 1.7
468     <p>
469 swift 1.8 Support for the framebuffer devices (<path>/dev/fb/*</path>) comes with the
470     kernel starting from version 2.6.6-rc2.
471 swift 1.7 </p>
472    
473     <p>
474 swift 1.8 For kernels older than 2.6.4 you have to explicitly include support for the
475     <path>/dev/pts</path> filesystem.
476 swift 1.1 </p>
477    
478 swift 1.8 <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 swift 1.1 </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 swift 1.45 <uri link="http://webpages.charter.net/decibelshelp/LinuxHelp_UDEVPrimer.html">Decibel's
501 swift 1.1 UDEV Primer</uri> is an in-depth document about udev and Gentoo.
502     </p>
503    
504 swift 1.8 <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 swift 1.1 </body>
511     </section>
512     </chapter>
513     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20