/[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.16 - (hide annotations) (download) (as text)
Sun Aug 29 12:38:38 2004 UTC (13 years, 10 months ago) by swift
Branch: MAIN
Changes since 1.15: +11 -4 lines
File MIME type: application/xml
#60966 - Dont automount devfs if you want to use udev

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.16 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/udev-guide.xml,v 1.15 2004/07/30 12:23:34 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.16 <version>0.12</version>
23     <date>August 29, 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     [*] Virtual memory file system support (former shm fs)
215     </pre>
216    
217     <p>
218     You can leave the <c>/dev file system support (OBSOLETE)</c> active if you
219 swift 1.16 wish but you have to make sure that "Automatically mount at boot" is disabled:
220 swift 1.1 </p>
221    
222 swift 1.16 <pre caption="Don't automatically mount devfsd">
223     File systems ---&gt;
224     Pseudo Filesystems ---&gt;
225     [*] /dev file system support (OBSOLETE)
226     [ ] Automatically mount at boot
227     </pre>
228    
229 swift 1.1 </body>
230     </section>
231     <section>
232     <title>Configuration</title>
233     <body>
234    
235     <p>
236 neysx 1.5 If you want to use the udev-tweaks Gentoo added to make your life
237 swift 1.15 comfortable, then read no more. Gentoo will use udev but keep a static
238     <path>/dev</path> so that you will never have any missing device nodes.
239     The Gentoo init scripts won't run the devfsd daemon and will deactivate devfs
240     when you boot up.
241 swift 1.1 </p>
242    
243     <p>
244     But if you are a die-hard and want to run a udev-only, no-tweaked system as is
245 swift 1.2 intended by the udev development (including the difficulties of missing device
246     nodes because udev doesn't support them yet), by all means, read on :)
247 swift 1.1 </p>
248    
249     <p>
250 bennyc 1.13 We'll deactivate the rules that save the device file nodes: edit the
251 swift 1.2 <c>RC_DEVICE_TARBALL</c> variable in <path>/etc/conf.d/rc</path> and set it to
252     <c>no</c>:
253     </p>
254 swift 1.1
255 swift 1.2 <pre caption="/etc/conf.d/rc">
256     RC_DEVICE_TARBALL="no"
257 swift 1.1 </pre>
258    
259     <p>
260 swift 1.8 If you have included devfs support in your kernel, you can deactivate it in
261 swift 1.14 the bootloader configuration: add <c>gentoo=nodevfs</c> as a kernel parameter.
262     If you want to use devfs and deactivate udev, add <c>gentoo=noudev</c> as kernel
263 swift 1.8 parameter.
264     </p>
265    
266     </body>
267     </section>
268     </chapter>
269    
270     <chapter>
271     <title>Known Issues</title>
272     <section>
273     <title>Missing device node files at boot</title>
274     <body>
275    
276     <p>
277 neysx 1.9 If you can't boot successfully because you get an error about
278 swift 1.8 <path>/dev/null</path> not found, or because the initial console is missing, the
279     problem is that you lack some device files that must be available <e>before</e>
280     <path>/dev</path> is mounted and handled by udev. This is common on Gentoo
281     machines installed from old media.
282     </p>
283    
284     <p>
285     If you run <c>sys-apps/baselayout-1.8.12</c> or later, this problem is
286     alleviated since the boot process should still manage to complete. However, to
287 swift 1.10 get rid of those annoying warnings, you should create the missing device nodes
288 swift 1.8 as described below.
289     </p>
290    
291     <p>
292     To see which devices nodes are present before the <path>/dev</path> filesystem
293     is mounted, run the following commands:
294     </p>
295    
296     <pre caption="Listing device nodes available at boot">
297     # <i>mkdir test</i>
298     # <i>mount --bind / test</i>
299     # <i>cd test/dev</i>
300     # <i>ls</i>
301     </pre>
302    
303     <p>
304 neysx 1.9 The devices needed for a successful boot are <path>/dev/null</path> and
305 swift 1.8 <path>/dev/console</path>. If they didn't show up in the previous test, you have
306 cam 1.12 to create them manually. Issue the following commands in the
307     <path>test/dev/</path> directory:
308 swift 1.1 </p>
309    
310     <pre caption="Creating necessary device node files">
311 cam 1.11 # <i>mknod -m 660 console c 5 1</i>
312     # <i>mknod -m 660 null c 1 3</i>
313 swift 1.1 </pre>
314    
315     <p>
316 swift 1.8 When you're finished, don't forget to unmount the <path>test/</path> directory:
317 swift 1.1 </p>
318    
319 swift 1.8 <pre caption="Unmounting the test/ directory">
320 cam 1.11 # <i>cd ../..</i>
321 swift 1.8 # <i>umount test</i>
322 cam 1.11 # <i>rmdir test</i>
323 swift 1.8 </pre>
324    
325     </body>
326     </section>
327     <section>
328     <title>udev and nvidia</title>
329     <body>
330    
331 swift 1.1 <p>
332 swift 1.8 If you use the proprietary driver from nVidia and the X server fails to start on
333     a udev-only system, then make sure you have:
334 swift 1.1 </p>
335    
336 swift 1.8 <ul>
337     <li>
338     the <c>nvidia</c> module listed in
339     <path>/etc/modules.autoload.d/kernel-2.6</path>
340     </li>
341     <li>
342 swift 1.10 a version of <c>nvidia-kernel</c> equal to or greater than
343 swift 1.8 <c>media-video/nvidia-kernel-1.0.5336-r2</c>
344     </li>
345     <li>
346     a version of baselayout equal to or greater than
347     <c>sys-apps/baselayout-1.8.12</c>
348     </li>
349     </ul>
350    
351 swift 1.1 </body>
352     </section>
353     <section>
354 swift 1.8 <title>Other issues</title>
355 swift 1.1 <body>
356    
357 swift 1.8 <p>
358     If device nodes are not created when a module is loaded from
359     <path>/etc/modules.autoload.d/kernel-2.6</path> but they appear when you load
360     the module manually with modprobe then you should try upgrading to
361     <c>sys-apps/baselayout-1.8.12</c> or later.
362     </p>
363 swift 1.7
364     <p>
365 swift 1.8 Support for the framebuffer devices (<path>/dev/fb/*</path>) comes with the
366     kernel starting from version 2.6.6-rc2.
367 swift 1.7 </p>
368    
369     <p>
370 swift 1.8 For kernels older than 2.6.4 you have to explicitly include support for the
371     <path>/dev/pts</path> filesystem.
372 swift 1.1 </p>
373    
374 swift 1.8 <pre caption="Enabling the /dev/pts filesystem">
375     File systems ---&gt;
376     Pseudo filesystems ---&gt;
377     [*] /dev/pts file system for Unix98 PTYs
378     </pre>
379    
380 swift 1.1 </body>
381     </section>
382     </chapter>
383    
384     <chapter>
385     <title>Resources &amp; Acknowledgements</title>
386     <section>
387     <body>
388    
389     <p>
390     The udev talk on the Linux Symposium (Ottawa, Ontario Canada - 2003) given by
391     Greg Kroah-Hartman (IBM Corporation) provided a solid understanding on the udev
392     application.
393     </p>
394    
395     <p>
396     <uri link="http://webpages.charter.net/decibelshelp/LinuxHelp_UDEVPrimer.html">Decibel's
397     UDEV Primer</uri> is an in-depth document about udev and Gentoo.
398     </p>
399    
400 swift 1.8 <p>
401     <uri link="http://www.reactivated.net/udevrules.php">Writing udev rules</uri> by
402     fellow Gentoo developer Daniel Drake is an excellent document to learn how to
403     customize your udev installation.
404     </p>
405    
406 swift 1.1 </body>
407     </section>
408     </chapter>
409    
410     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20