/[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.54 - (hide annotations) (download) (as text)
Sun Sep 11 08:43:18 2011 UTC (2 years, 7 months ago) by swift
Branch: MAIN
Changes since 1.53: +9 -25 lines
File MIME type: application/xml
Fix bug #382457 - Update all references to outdated /etc/modules.autoload.d

1 swift 1.1 <?xml version='1.0' encoding="UTF-8"?>
2     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 swift 1.54 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/udev-guide.xml,v 1.53 2011/03/12 05:44:14 nightmorph Exp $ -->
4 neysx 1.4
5 nightmorph 1.51 <guide>
6 swift 1.1 <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.54 <version>9</version>
27     <date>2011-09-11</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 nightmorph 1.53 Every time a change happens within the device structure, the kernel emits a
75     <e>uevent</e> which gets picked up by udev. udev then follows the rules as
76     declared in the <path>/etc/udev/rules.d</path> and
77     <path>/lib/udev/rules.d</path> directories. Based on the information contained
78     within the uevent, it finds the rule or rules it needs to trigger and performs
79     the required actions. These actions can be creating or deleting device files,
80     but can also trigger the loading of particular firmware files into the
81     kernel memory.
82 swift 1.1 </p>
83    
84     </body>
85     </section>
86     </chapter>
87    
88     <chapter>
89     <title>Using udev on Gentoo</title>
90     <section>
91     <title>Requirements</title>
92     <body>
93    
94     <p>
95 swift 1.8 udev is meant to be used in combination with a 2.6 kernel (like
96 nightmorph 1.53 <c>gentoo-sources</c> with the default 10.0 profile). If you're using such a
97     kernel then you just should have no issues whatsoever with using udev as the
98     necessary support is built-in in all stable <c>sys-apps/baselayout</c>
99     versions. Normally, udev should already be installed on your system, but if
100     this is not the case, then it is easy to install:
101 swift 1.1 </p>
102    
103 swift 1.8 <pre caption="Installing udev">
104     # <i>emerge udev</i>
105 swift 1.1 </pre>
106    
107     <p>
108 swift 1.21 Kernelwise, be sure to activate the following options:
109 swift 1.1 </p>
110    
111     <pre caption="Required kernel options">
112 nightmorph 1.53 General Setup ---&gt;
113     <comment>(Make sure the following item is *not* enabled)</comment>
114     [ ] enable deprecated sysfs features to support old userspace tools
115    
116     File Systems ---&gt;
117     [*] Inotify support for userspace
118 swift 1.1 Pseudo filesystems ---&gt;
119     [*] Virtual memory file system support (former shm fs)
120     </pre>
121    
122     <p>
123 nightmorph 1.48 If you use <c>genkernel</c>, you don't need to do anything special. Genkernel
124     sets up udev by default.
125 swift 1.21 </p>
126    
127 swift 1.1 </body>
128     </section>
129 swift 1.8 </chapter>
130    
131     <chapter>
132     <title>Known Issues</title>
133     <section>
134     <title>Missing device node files at boot</title>
135     <body>
136    
137     <p>
138 neysx 1.9 If you can't boot successfully because you get an error about
139 swift 1.8 <path>/dev/null</path> not found, or because the initial console is missing, the
140     problem is that you lack some device files that must be available <e>before</e>
141     <path>/dev</path> is mounted and handled by udev. This is common on Gentoo
142     machines installed from old media.
143     </p>
144    
145     <p>
146     If you run <c>sys-apps/baselayout-1.8.12</c> or later, this problem is
147     alleviated since the boot process should still manage to complete. However, to
148 swift 1.10 get rid of those annoying warnings, you should create the missing device nodes
149 swift 1.8 as described below.
150     </p>
151    
152     <p>
153     To see which devices nodes are present before the <path>/dev</path> filesystem
154     is mounted, run the following commands:
155     </p>
156    
157     <pre caption="Listing device nodes available at boot">
158     # <i>mkdir test</i>
159     # <i>mount --bind / test</i>
160     # <i>cd test/dev</i>
161     # <i>ls</i>
162     </pre>
163    
164     <p>
165 neysx 1.9 The devices needed for a successful boot are <path>/dev/null</path> and
166 swift 1.8 <path>/dev/console</path>. If they didn't show up in the previous test, you have
167 cam 1.12 to create them manually. Issue the following commands in the
168     <path>test/dev/</path> directory:
169 swift 1.1 </p>
170    
171     <pre caption="Creating necessary device node files">
172 cam 1.11 # <i>mknod -m 660 console c 5 1</i>
173     # <i>mknod -m 660 null c 1 3</i>
174 swift 1.1 </pre>
175    
176     <p>
177 swift 1.8 When you're finished, don't forget to unmount the <path>test/</path> directory:
178 swift 1.1 </p>
179    
180 swift 1.8 <pre caption="Unmounting the test/ directory">
181 cam 1.11 # <i>cd ../..</i>
182 swift 1.8 # <i>umount test</i>
183 cam 1.11 # <i>rmdir test</i>
184 swift 1.8 </pre>
185    
186     </body>
187     </section>
188     <section>
189     <title>udev and nvidia</title>
190     <body>
191    
192 swift 1.1 <p>
193 swift 1.8 If you use the proprietary driver from nVidia and the X server fails to start on
194 swift 1.54 a udev-only system, then make sure you have the <c>nvidia</c> module listed in
195     <path>/etc/conf.d/modules</path>.
196 swift 1.1 </p>
197    
198     </body>
199     </section>
200     <section>
201 swift 1.18 <title>No Consistent Naming between DevFS and udev</title>
202     <body>
203    
204     <p>
205 swift 1.45 Even though our intention is to have a consistent naming scheme between both
206 swift 1.18 dynamical device management solutions, sometimes naming differences do occur.
207 swift 1.22 </p>
208    
209     <p>
210 swift 1.18 One reported clash is with a HP Smart Array 5i RAID controller (more precisely
211     the <c>cciss</c> kernel module). With udev, the devices are named
212     <path>/dev/cciss/cXdYpZ</path> with X, Y and Z regular numbers. With devfs, the
213     devices are <path>/dev/hostX/targetY/partZ</path> or symlinked from
214     <path>/dev/cciss/cXdY</path>.
215     </p>
216    
217     <p>
218     If this is the case, don't forget to update your <path>/etc/fstab</path> and
219     bootloader configuration files accordingly.
220     </p>
221    
222 swift 1.22 <p>
223     The same happens with all-round symlinks that used to exist in
224     <path>/dev</path>, such as <path>/dev/mouse</path>, which <c>udev</c> doesn't
225     create anymore. Be certain to check your X configuration file and see if the
226 swift 1.23 Device rule for your mouse points to an existing device file.
227 swift 1.22 </p>
228    
229 fox2mike 1.29 <p>
230     Another issue is the difference in naming of terminals between devfs and udev.
231 nightmorph 1.31 While devfs calls its terminals <c>tty</c>, udev calls them <c>vc</c> and
232     <c>tty</c>. This could lead to a problem in case you are restricting root
233     logins from consoles using <path>/etc/securetty</path>. You will need to make
234     sure that both <c>tty1</c> and <c>vc/1</c> are listed in
235     <path>/etc/securetty</path> to ensure that root can login using the console.
236 fox2mike 1.29 </p>
237    
238 swift 1.18 </body>
239     </section>
240     <section>
241 nightmorph 1.49 <title>Block device renaming</title>
242 nightmorph 1.41 <body>
243    
244     <p>
245     Recent versions of udev (104 and up) along with newer kernel versions (2.6.19
246     and up) may change your disc device names, due to a change in the kernel's
247     libata implementation. A CD-RW device at <path>/dev/hdc</path> may be changed to
248     <path>/dev/sr0</path>. While this is not normally a problem, it may cause issues
249     for some applications that are hardcoded to look for devices at other locations.
250     For example, <c>media-sound/rip</c> expects to find discs at
251     <path>/dev/cdrom</path>, which becomes a problem if you use a newer kernel and
252     udev renames your device to <path>/dev/cdrom1</path>.
253     </p>
254    
255     <p>
256     To work around these issues, you must edit
257     <path>/etc/udev/rules.d/70-persistent-cd.rules</path> and assign the correct
258     name to the device.
259     </p>
260    
261     <p>
262     For more information on writing udev rules, be sure to read Daniel Drake's <uri
263     link="http://www.reactivated.net/udevrules.php">guide</uri>.
264     </p>
265    
266     </body>
267     </section>
268     <section>
269 nightmorph 1.49 <title>Network device renaming</title>
270     <body>
271    
272     <p>
273     Sometimes unplugging and replugging a network device (like a USB WiFi card) can
274     rename your net device each time, incrementing the number by one.
275     </p>
276    
277     <p>
278     When this happens, you'll see it become <c>wlan0</c>, <c>wlan1</c>,
279     <c>wlan2</c>, etc. This is because udev is adding additional rules to its rules
280     file, instead of reloading the existing rules. Since udev watches its rules
281     directory via inotify, you need inotify support in your kernel config:
282     </p>
283    
284     <pre caption="Enabling inotify support in the kernel">
285     File systems ---&gt;
286     [*] Inotify file change notification support
287     [*] Inotify support for userspace
288     </pre>
289    
290     <p>
291     Now udev will retain proper names for your network devices.
292     </p>
293    
294     </body>
295     </section>
296     <section>
297 nightmorph 1.44 <title>udev loads modules in an unpredictable order</title>
298     <body>
299    
300     <p>
301     Sometimes udev loads modules in an undesired, unpredictable, or seemingly random
302     order. This is especially common for systems that have multiple devices of the
303     same type, as well as multimedia devices. This can affect the assigned numbers
304     of devices; for example, sound cards may sometimes swap numbers.
305     </p>
306    
307     <p>
308     There are a few solutions to fix device numbers and/or module load order.
309     Ideally, you can just use module parameters to specify your desired device
310     number. Some modules, such as ALSA, include the "index" parameter. Modules that
311     use the index parameter can be adjusted as shown. This example is for a system
312     with two sound cards. The card with an index of 0 is designated as the first
313     card. Once the parameters are changed, the module config files must be updated.
314     </p>
315    
316     <pre caption="Specifying module parameters">
317 nightmorph 1.50 # <i>echo "option snd-ice1724 index=0" >> /etc/modprobe.d/alsa.conf</i>
318     # <i>echo "option snd-ymfpci index=1" >> /etc/modprobe.d/alsa.conf</i>
319 nightmorph 1.44 # <i>update-modules</i>
320     </pre>
321    
322     <p>
323     The above example is the preferred solution, but not all modules support
324     parameters such as index. For these modules, you'll have to force the correct
325     module load order. First, you must stop udev from autoloading the modules by
326     blacklisting them. Be sure to use the exact name of the module being loaded.
327     For PCI devices, you'll need to use the module names obtained from the output of
328 nightmorph 1.52 <c>lspci -k</c>, available in the <c>pciutils</c> package. The following example
329     uses DVB modules.
330 nightmorph 1.44 </p>
331    
332     <pre caption="Blacklisting modules">
333 nightmorph 1.46 # <i>echo "blacklist b2c2-flexcop-pci" >> /etc/modprobe.d/dvb</i>
334     # <i>echo "blacklist budget" >> /etc/modprobe.d/dvb</i>
335 nightmorph 1.44 # <i>update-modules</i>
336     </pre>
337    
338     <p>
339     Next, load the modules in the correct order. Add them to
340 swift 1.54 <path>/etc/conf.d/modules</path> <e>in the exact order you want
341 nightmorph 1.44 them loaded</e>.
342     </p>
343    
344     <pre caption="Loading modules in the correct order">
345 swift 1.54 # <i>nano -w /etc/conf.d/modules</i>
346    
347     modules="<i>budget b2c2-flexcop-pci</i>"
348 nightmorph 1.44 </pre>
349    
350     </body>
351     </section>
352     <section>
353 swift 1.8 <title>Other issues</title>
354 swift 1.1 <body>
355    
356 swift 1.8 <p>
357     Support for the framebuffer devices (<path>/dev/fb/*</path>) comes with the
358     kernel starting from version 2.6.6-rc2.
359 swift 1.7 </p>
360    
361     <p>
362 swift 1.8 For kernels older than 2.6.4 you have to explicitly include support for the
363     <path>/dev/pts</path> filesystem.
364 swift 1.1 </p>
365    
366 swift 1.8 <pre caption="Enabling the /dev/pts filesystem">
367     File systems ---&gt;
368     Pseudo filesystems ---&gt;
369     [*] /dev/pts file system for Unix98 PTYs
370     </pre>
371    
372 swift 1.1 </body>
373     </section>
374     </chapter>
375    
376     <chapter>
377     <title>Resources &amp; Acknowledgements</title>
378     <section>
379     <body>
380    
381     <p>
382     The udev talk on the Linux Symposium (Ottawa, Ontario Canada - 2003) given by
383     Greg Kroah-Hartman (IBM Corporation) provided a solid understanding on the udev
384     application.
385     </p>
386    
387     <p>
388 swift 1.45 <uri link="http://webpages.charter.net/decibelshelp/LinuxHelp_UDEVPrimer.html">Decibel's
389 swift 1.1 UDEV Primer</uri> is an in-depth document about udev and Gentoo.
390     </p>
391    
392 swift 1.8 <p>
393     <uri link="http://www.reactivated.net/udevrules.php">Writing udev rules</uri> by
394     fellow Gentoo developer Daniel Drake is an excellent document to learn how to
395     customize your udev installation.
396     </p>
397    
398 swift 1.1 </body>
399     </section>
400     </chapter>
401     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20