/[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 - (show annotations) (download) (as text)
Sun Sep 11 08:43:18 2011 UTC (2 years, 10 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 <?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.53 2011/03/12 05:44:14 nightmorph Exp $ -->
4
5 <guide>
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>9</version>
27 <date>2011-09-11</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 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 </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 udev is meant to be used in combination with a 2.6 kernel (like
96 <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 </p>
102
103 <pre caption="Installing udev">
104 # <i>emerge udev</i>
105 </pre>
106
107 <p>
108 Kernelwise, be sure to activate the following options:
109 </p>
110
111 <pre caption="Required kernel options">
112 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 Pseudo filesystems ---&gt;
119 [*] Virtual memory file system support (former shm fs)
120 </pre>
121
122 <p>
123 If you use <c>genkernel</c>, you don't need to do anything special. Genkernel
124 sets up udev by default.
125 </p>
126
127 </body>
128 </section>
129 </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 If you can't boot successfully because you get an error about
139 <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 get rid of those annoying warnings, you should create the missing device nodes
149 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 The devices needed for a successful boot are <path>/dev/null</path> and
166 <path>/dev/console</path>. If they didn't show up in the previous test, you have
167 to create them manually. Issue the following commands in the
168 <path>test/dev/</path> directory:
169 </p>
170
171 <pre caption="Creating necessary device node files">
172 # <i>mknod -m 660 console c 5 1</i>
173 # <i>mknod -m 660 null c 1 3</i>
174 </pre>
175
176 <p>
177 When you're finished, don't forget to unmount the <path>test/</path> directory:
178 </p>
179
180 <pre caption="Unmounting the test/ directory">
181 # <i>cd ../..</i>
182 # <i>umount test</i>
183 # <i>rmdir test</i>
184 </pre>
185
186 </body>
187 </section>
188 <section>
189 <title>udev and nvidia</title>
190 <body>
191
192 <p>
193 If you use the proprietary driver from nVidia and the X server fails to start on
194 a udev-only system, then make sure you have the <c>nvidia</c> module listed in
195 <path>/etc/conf.d/modules</path>.
196 </p>
197
198 </body>
199 </section>
200 <section>
201 <title>No Consistent Naming between DevFS and udev</title>
202 <body>
203
204 <p>
205 Even though our intention is to have a consistent naming scheme between both
206 dynamical device management solutions, sometimes naming differences do occur.
207 </p>
208
209 <p>
210 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 <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 Device rule for your mouse points to an existing device file.
227 </p>
228
229 <p>
230 Another issue is the difference in naming of terminals between devfs and udev.
231 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 </p>
237
238 </body>
239 </section>
240 <section>
241 <title>Block device renaming</title>
242 <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 <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 <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 # <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 # <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 <c>lspci -k</c>, available in the <c>pciutils</c> package. The following example
329 uses DVB modules.
330 </p>
331
332 <pre caption="Blacklisting modules">
333 # <i>echo "blacklist b2c2-flexcop-pci" >> /etc/modprobe.d/dvb</i>
334 # <i>echo "blacklist budget" >> /etc/modprobe.d/dvb</i>
335 # <i>update-modules</i>
336 </pre>
337
338 <p>
339 Next, load the modules in the correct order. Add them to
340 <path>/etc/conf.d/modules</path> <e>in the exact order you want
341 them loaded</e>.
342 </p>
343
344 <pre caption="Loading modules in the correct order">
345 # <i>nano -w /etc/conf.d/modules</i>
346
347 modules="<i>budget b2c2-flexcop-pci</i>"
348 </pre>
349
350 </body>
351 </section>
352 <section>
353 <title>Other issues</title>
354 <body>
355
356 <p>
357 Support for the framebuffer devices (<path>/dev/fb/*</path>) comes with the
358 kernel starting from version 2.6.6-rc2.
359 </p>
360
361 <p>
362 For kernels older than 2.6.4 you have to explicitly include support for the
363 <path>/dev/pts</path> filesystem.
364 </p>
365
366 <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 </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 <uri link="http://webpages.charter.net/decibelshelp/LinuxHelp_UDEVPrimer.html">Decibel's
389 UDEV Primer</uri> is an in-depth document about udev and Gentoo.
390 </p>
391
392 <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 </body>
399 </section>
400 </chapter>
401 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20