/[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.8 - (hide annotations) (download) (as text)
Mon Apr 26 09:52:41 2004 UTC (13 years, 6 months ago) by swift
Branch: MAIN
Changes since 1.7: +121 -33 lines
File MIME type: application/xml
#49018 - Updates to the udev guide to cope with recent changes in baselayout and such. Added Gregorio Guidi as contributor

1 swift 1.1 <?xml version='1.0' encoding="UTF-8"?>
2     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 neysx 1.4
4 swift 1.8 <!-- $Header: /home/cvsroot/gentoo/xml/htdocs/doc/en/udev-guide.xml,v 1.7 2004/04/25 16:44:49 swift Exp $ -->
5 neysx 1.4
6 swift 1.1 <guide link="/doc/en/udev-guide.xml">
7     <title>Gentoo udev Guide</title>
8    
9     <author title="Author">
10 swift 1.8 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
11     </author>
12     <author title="Contributor">
13     <mail link="g.guidi@sns.it">Gregorio Guidi</mail>
14 swift 1.1 </author>
15    
16     <abstract>
17     This document explains what udev is and how you can use udev to fit your needs.
18     </abstract>
19    
20     <license/>
21    
22 swift 1.8 <version>0.7</version>
23     <date>April 26, 2004</date>
24 swift 1.1
25     <chapter>
26     <title>What is udev?</title>
27     <section>
28     <title>The /dev Directory</title>
29     <body>
30    
31     <p>
32     When Linux-users talk about the hardware on their system in the vicinity of
33 swift 1.3 people who believe Linux is some sort of virus or brand of coffee, the use of
34 swift 1.1 "slash dev slash foo" will return a strange look for sure. But for the fortunate
35     user (and that includes you) using <path>/dev/hda1</path> is just a fast way of
36     explaining that we are talking about the primary master IDE, first partition. Or
37     aren't we?
38     </p>
39    
40     <p>
41     We all know what a device file is. Some even know why device files have special
42     numbers when we take a closer look at them when we issue <c>ls -l</c> in
43     <path>/dev</path>. But what we always take for granted is that the primary
44     master IDE disk is referred to as <path>/dev/hda</path>. You might not see it
45     this way, but this is a flaw by design.
46     </p>
47    
48     <p>
49 swift 1.3 Think about hotpluggable devices like USB, IEEE1394, hot-swappable PCI, ... What
50     is the first device? And for how long? What will the other devices be named when
51 swift 1.1 the first one disappears? How will that affect ongoing transactions? Wouldn't it
52 swift 1.3 be fun that a printing job is suddenly moved from your supernew laserprinter to
53 swift 1.1 your almost-dead matrix printer because your mom decided to pull the plug of the
54     inkjet which happened to be the first printer?
55     </p>
56    
57     <p>
58     Enter <e>udev</e>. The goals of the udev project are both interesting and
59     needed:
60     </p>
61    
62     <ul>
63 swift 1.3 <li>Runs in userspace</li>
64     <li>Dynamically creates/removes device files</li>
65     <li>Provides consistent naming</li>
66     <li>Provides a user-space API</li>
67 swift 1.1 </ul>
68    
69     <p>
70     To provide these features, udev is developed in three separate projects:
71     <e>namedev</e>, <e>libsysfs</e> and, of course, <e>udev</e>.
72     </p>
73    
74     </body>
75     </section>
76     <section>
77     <title>namedev</title>
78     <body>
79    
80     <p>
81     Namedev allows you to define the device naming separately from the udev program.
82     This allows for flexible naming policies and naming schemes developed by
83     separate entities. This device naming subsystem provides a standard interface
84     that udev can use.
85     </p>
86    
87     <p>
88     Currently only a single naming scheme is provided by namedev; the one provided
89 swift 1.3 by LANANA, used by the majority of Linux systems currently and therefore very
90 swift 1.1 suitable for the majority of Linux users.
91     </p>
92    
93     <p>
94     Namedev uses a 5-step procedure to find out the name of a given device. If the
95     device name is found in one of the given steps, that name is used. The steps
96     are:
97     </p>
98    
99     <ul>
100     <li>label or serial number</li>
101     <li>bus device number</li>
102     <li>bus topology</li>
103     <li>statically given name</li>
104     <li>kernel provided name</li>
105     </ul>
106    
107     <p>
108     The <e>label or serial number</e> step checks if the device has a unique
109     identifier. For instance USB devices have a unique USB serial number; SCSI
110     devices have a unique UUID. If namedev finds a match between this unique number
111     and a given configuration file, the name provided in the configuration file is
112     used.
113     </p>
114    
115     <p>
116     The <e>bus device number</e> step checks the device bus number. For
117     non-hot-swappable environments this procedure is sufficient to
118     identify a hardware device. For instance PCI bus numbers rarely change in the
119     lifetime of a system. Again, if namedev finds a match between this position and
120     a given configuration file, the name provided in that configuration file is
121     used.
122     </p>
123    
124     <p>
125     Likewise the <e>bus topology</e> is a rather static way of defining devices as
126     long as the user doesn't switch devices. When the position of the device matches
127 swift 1.3 a given setting provided by the user, the accompanying name is used.
128 swift 1.1 </p>
129    
130     <p>
131     The fourth step, <e>statically given name</e>, is a simple string replacement.
132     When the kernel name (the default name) matches a given replacement string, the
133     substitute name will be used.
134     </p>
135    
136     <p>
137     The final step (<e>kernel provided name</e>) is a catch-all: this one takes
138     the default name provided by the kernel. In the majority of cases this is
139     sufficient as it matches the device naming used on current Linux systems.
140     </p>
141    
142     </body>
143     </section>
144     <section>
145     <title>libsysfs</title>
146     <body>
147    
148     <p>
149     udev interacts with the kernel through the sysfs pseudo filesystem. The libsysfs
150     project provides a common API to access the information given by the sysfs
151     filesystem in a generic way. This allows for querying all kinds of hardware
152     without having to make assumptions on the kind of hardware.
153     </p>
154    
155     </body>
156     </section>
157     <section>
158     <title>udev</title>
159     <body>
160    
161     <p>
162     Every time the kernel notices an update in the device structure, it calls the
163     <path>/sbin/hotplug</path> program. Hotplug runs the applications linked in the
164     <path>/etc/hotplug.d/default</path> directory where you will also find a symlink
165     to the udev application. Hotplug directs the information given by the kernel to
166     the udev application which performs the necessary actions on the
167     <path>/dev</path> structure (creating or deleting device files).
168     </p>
169    
170     </body>
171     </section>
172     </chapter>
173    
174     <chapter>
175     <title>Using udev on Gentoo</title>
176     <section>
177     <title>Requirements</title>
178     <body>
179    
180     <p>
181 swift 1.8 udev is meant to be used in combination with a 2.6 kernel (like
182     <c>development-sources</c> or <c>gentoo-dev-sources</c>). If you're using such a
183     kernel then you just have to make sure that you have a recent
184     <c>sys-apps/baselayout</c> version. That's all you need.
185 swift 1.1 </p>
186    
187 swift 1.8 <pre caption="Installing udev">
188     # <i>emerge udev</i>
189 swift 1.1 </pre>
190    
191     <p>
192 swift 1.8 udev will install <c>hotplug-base</c> as one of it's dependencies. If you
193     intend to use hotplug to execute specific actions when you plug in your
194     favorite USB or IEEE1394 device then you should also emerge the whole bunch
195     of hotplug scripts.
196 swift 1.1 </p>
197    
198 swift 1.8 <pre caption="Installing optional hotplug scripts">
199     # <i>emerge hotplug</i>
200 swift 1.1 </pre>
201    
202     <p>
203     Kernelwise, if you're using the default set by <c>genkernel</c> then you're all
204     set. Otherwise be sure to activate the following options:
205     </p>
206    
207     <pre caption="Required kernel options">
208 swift 1.6 General setup ---&gt;
209 swift 1.1 [*] Support for hot-pluggable devices
210    
211     File systems ---&gt;
212     Pseudo filesystems ---&gt;
213     [*] /proc file system support
214     [*] /dev/pts file system for Unix98 PTYs
215     [*] Virtual memory file system support (former shm fs)
216     </pre>
217    
218     <p>
219     You can leave the <c>/dev file system support (OBSOLETE)</c> active if you
220     wish.
221     </p>
222    
223     </body>
224     </section>
225     <section>
226     <title>Configuration</title>
227     <body>
228    
229     <p>
230 neysx 1.5 If you want to use the udev-tweaks Gentoo added to make your life
231 swift 1.1 comfortable, then read no more. You're all set. The Gentoo init scripts won't
232 swift 1.3 run the devfsd daemon and will deactivate devfs when you boot up.
233 swift 1.1 </p>
234    
235     <p>
236     But if you are a die-hard and want to run a udev-only, no-tweaked system as is
237 swift 1.2 intended by the udev development (including the difficulties of missing device
238     nodes because udev doesn't support them yet), by all means, read on :)
239 swift 1.1 </p>
240    
241     <warn>
242     Do <e>not</e> complain if something goes wrong. You're going to remove the hard
243     work of many Gentoo developers that hacked our init scripts to get udev playing
244     nicely with Gentoo!
245     </warn>
246    
247     <p>
248 swift 1.8 We'll deactivate the rules hat save the device file nodes: edit the
249 swift 1.2 <c>RC_DEVICE_TARBALL</c> variable in <path>/etc/conf.d/rc</path> and set it to
250     <c>no</c>:
251     </p>
252 swift 1.1
253 swift 1.2 <pre caption="/etc/conf.d/rc">
254     RC_DEVICE_TARBALL="no"
255 swift 1.1 </pre>
256    
257     <p>
258 swift 1.8 If you have included devfs support in your kernel, you can deactivate it in
259     the bootloader configuration: add <c>devfs=nomount</c> as a kernel parameter. If
260     you want to use devfs and deactivate udev, add <c>gentoo=noudev</c> as kernel
261     parameter.
262     </p>
263    
264     </body>
265     </section>
266     </chapter>
267    
268     <chapter>
269     <title>Known Issues</title>
270     <section>
271     <title>Missing device node files at boot</title>
272     <body>
273    
274     <p>
275     If you can't boot succesfully because you get an error about
276     <path>/dev/null</path> not found, or because the initial console is missing, the
277     problem is that you lack some device files that must be available <e>before</e>
278     <path>/dev</path> is mounted and handled by udev. This is common on Gentoo
279     machines installed from old media.
280     </p>
281    
282     <p>
283     If you run <c>sys-apps/baselayout-1.8.12</c> or later, this problem is
284     alleviated since the boot process should still manage to complete. However, to
285     get rid of those annoying warnings, you should create he missing devices nodes
286     as described below.
287     </p>
288    
289     <p>
290     To see which devices nodes are present before the <path>/dev</path> filesystem
291     is mounted, run the following commands:
292     </p>
293    
294     <pre caption="Listing device nodes available at boot">
295     # <i>mkdir test</i>
296     # <i>mount --bind / test</i>
297     # <i>cd test/dev</i>
298     # <i>ls</i>
299     </pre>
300    
301     <p>
302     The devices needed for a succesful boot are <path>/dev/null</path> and
303     <path>/dev/console</path>. If they didn't show up in the previous test, you have
304     to create them manually. Issue the following commands in the <path>test/</path>
305     directory created previously:
306 swift 1.1 </p>
307    
308     <pre caption="Creating necessary device node files">
309 swift 1.8 # <i>mknod -m 660 dev/console c 5 1</i>
310     # <i>mknod -m 660 dev/null c 1 3</i>
311 swift 1.1 </pre>
312    
313     <p>
314 swift 1.8 When you're finished, don't forget to unmount the <path>test/</path> directory:
315 swift 1.1 </p>
316    
317 swift 1.8 <pre caption="Unmounting the test/ directory">
318     # <i>umount test</i>
319     </pre>
320    
321     </body>
322     </section>
323     <section>
324     <title>udev and nvidia</title>
325     <body>
326    
327 swift 1.1 <p>
328 swift 1.8 If you use the proprietary driver from nVidia and the X server fails to start on
329     a udev-only system, then make sure you have:
330 swift 1.1 </p>
331    
332 swift 1.8 <ul>
333     <li>
334     the <c>nvidia</c> module listed in
335     <path>/etc/modules.autoload.d/kernel-2.6</path>
336     </li>
337     <li>
338     a version of <c>nvidia-kernel</c> equal to or greater han
339     <c>media-video/nvidia-kernel-1.0.5336-r2</c>
340     </li>
341     <li>
342     a version of baselayout equal to or greater than
343     <c>sys-apps/baselayout-1.8.12</c>
344     </li>
345     </ul>
346    
347 swift 1.1 </body>
348     </section>
349     <section>
350 swift 1.8 <title>Other issues</title>
351 swift 1.1 <body>
352    
353 swift 1.8 <p>
354     If device nodes are not created when a module is loaded from
355     <path>/etc/modules.autoload.d/kernel-2.6</path> but they appear when you load
356     the module manually with modprobe then you should try upgrading to
357     <c>sys-apps/baselayout-1.8.12</c> or later.
358     </p>
359 swift 1.7
360     <p>
361 swift 1.8 Support for the framebuffer devices (<path>/dev/fb/*</path>) comes with the
362     kernel starting from version 2.6.6-rc2.
363 swift 1.7 </p>
364    
365     <p>
366 swift 1.8 For kernels older than 2.6.4 you have to explicitly include support for the
367     <path>/dev/pts</path> filesystem.
368 swift 1.1 </p>
369    
370 swift 1.8 <pre caption="Enabling the /dev/pts filesystem">
371     File systems ---&gt;
372     Pseudo filesystems ---&gt;
373     [*] /dev/pts file system for Unix98 PTYs
374     </pre>
375    
376 swift 1.1 </body>
377     </section>
378     </chapter>
379    
380     <chapter>
381     <title>Resources &amp; Acknowledgements</title>
382     <section>
383     <body>
384    
385     <p>
386     The udev talk on the Linux Symposium (Ottawa, Ontario Canada - 2003) given by
387     Greg Kroah-Hartman (IBM Corporation) provided a solid understanding on the udev
388     application.
389     </p>
390    
391     <p>
392     <uri link="http://webpages.charter.net/decibelshelp/LinuxHelp_UDEVPrimer.html">Decibel's
393     UDEV Primer</uri> is an in-depth document about udev and Gentoo.
394     </p>
395    
396 swift 1.8 <p>
397     <uri link="http://www.reactivated.net/udevrules.php">Writing udev rules</uri> by
398     fellow Gentoo developer Daniel Drake is an excellent document to learn how to
399     customize your udev installation.
400     </p>
401    
402 swift 1.1 </body>
403     </section>
404     </chapter>
405    
406     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20