/[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.1 - (hide annotations) (download) (as text)
Thu Feb 26 16:39:46 2004 UTC (13 years, 7 months ago) by swift
Branch: MAIN
File MIME type: application/xml
New guide: udev and Gentoo

1 swift 1.1 <?xml version='1.0' encoding="UTF-8"?>
2     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3     <guide link="/doc/en/udev-guide.xml">
4     <title>Gentoo udev Guide</title>
5    
6     <author title="Author">
7     <mail link="swift@gentoo.org">Sven Vermeulen</mail>
8     </author>
9    
10     <abstract>
11     This document explains what udev is and how you can use udev to fit your needs.
12     </abstract>
13    
14     <license/>
15    
16     <version>0.1</version>
17     <date>February 26, 2003</date>
18    
19     <chapter>
20     <title>What is udev?</title>
21     <section>
22     <title>The /dev Directory</title>
23     <body>
24    
25     <p>
26     When Linux-users talk about the hardware on their system in the vicinity of
27     people that believe Linux is some sort of virus or brand of coffee, the use of
28     "slash dev slash foo" will return a strange look for sure. But for the fortunate
29     user (and that includes you) using <path>/dev/hda1</path> is just a fast way of
30     explaining that we are talking about the primary master IDE, first partition. Or
31     aren't we?
32     </p>
33    
34     <p>
35     We all know what a device file is. Some even know why device files have special
36     numbers when we take a closer look at them when we issue <c>ls -l</c> in
37     <path>/dev</path>. But what we always take for granted is that the primary
38     master IDE disk is referred to as <path>/dev/hda</path>. You might not see it
39     this way, but this is a flaw by design.
40     </p>
41    
42     <p>
43     Think hotpluggable devices like USB, IEEE1394, hot-swappable PCI, ... What is
44     the first device? And for how long? What will the other devices be named to when
45     the first one disappears? How will that affect ongoing transactions? Wouldn't it
46     be fun that a printing job is suddenly moved from your supernew laserprinter to
47     your almost-dead matrix printer because your mom decided to pull the plug of the
48     inkjet which happened to be the first printer?
49     </p>
50    
51     <p>
52     Enter <e>udev</e>. The goals of the udev project are both interesting and
53     needed:
54     </p>
55    
56     <ul>
57     <li>Run in userspace</li>
58     <li>Dynamically create/remove device files</li>
59     <li>Provide consistent naming</li>
60     <li>Provide a user-space API</li>
61     </ul>
62    
63     <p>
64     To provide these features, udev is developed in three separate projects:
65     <e>namedev</e>, <e>libsysfs</e> and, of course, <e>udev</e>.
66     </p>
67    
68     </body>
69     </section>
70     <section>
71     <title>namedev</title>
72     <body>
73    
74     <p>
75     Namedev allows you to define the device naming separately from the udev program.
76     This allows for flexible naming policies and naming schemes developed by
77     separate entities. This device naming subsystem provides a standard interface
78     that udev can use.
79     </p>
80    
81     <p>
82     Currently only a single naming scheme is provided by namedev; the one provided
83     by LANANA, used by the majority of Linux systems currently and therefor very
84     suitable for the majority of Linux users.
85     </p>
86    
87     <p>
88     Namedev uses a 5-step procedure to find out the name of a given device. If the
89     device name is found in one of the given steps, that name is used. The steps
90     are:
91     </p>
92    
93     <ul>
94     <li>label or serial number</li>
95     <li>bus device number</li>
96     <li>bus topology</li>
97     <li>statically given name</li>
98     <li>kernel provided name</li>
99     </ul>
100    
101     <p>
102     The <e>label or serial number</e> step checks if the device has a unique
103     identifier. For instance USB devices have a unique USB serial number; SCSI
104     devices have a unique UUID. If namedev finds a match between this unique number
105     and a given configuration file, the name provided in the configuration file is
106     used.
107     </p>
108    
109     <p>
110     The <e>bus device number</e> step checks the device bus number. For
111     non-hot-swappable environments this procedure is sufficient to
112     identify a hardware device. For instance PCI bus numbers rarely change in the
113     lifetime of a system. Again, if namedev finds a match between this position and
114     a given configuration file, the name provided in that configuration file is
115     used.
116     </p>
117    
118     <p>
119     Likewise the <e>bus topology</e> is a rather static way of defining devices as
120     long as the user doesn't switch devices. When the position of the device matches
121     a given setting provided by the user, the accompagnying name is used.
122     </p>
123    
124     <p>
125     The fourth step, <e>statically given name</e>, is a simple string replacement.
126     When the kernel name (the default name) matches a given replacement string, the
127     substitute name will be used.
128     </p>
129    
130     <p>
131     The final step (<e>kernel provided name</e>) is a catch-all: this one takes
132     the default name provided by the kernel. In the majority of cases this is
133     sufficient as it matches the device naming used on current Linux systems.
134     </p>
135    
136     </body>
137     </section>
138     <section>
139     <title>libsysfs</title>
140     <body>
141    
142     <p>
143     udev interacts with the kernel through the sysfs pseudo filesystem. The libsysfs
144     project provides a common API to access the information given by the sysfs
145     filesystem in a generic way. This allows for querying all kinds of hardware
146     without having to make assumptions on the kind of hardware.
147     </p>
148    
149     </body>
150     </section>
151     <section>
152     <title>udev</title>
153     <body>
154    
155     <p>
156     Every time the kernel notices an update in the device structure, it calls the
157     <path>/sbin/hotplug</path> program. Hotplug runs the applications linked in the
158     <path>/etc/hotplug.d/default</path> directory where you will also find a symlink
159     to the udev application. Hotplug directs the information given by the kernel to
160     the udev application which performs the necessary actions on the
161     <path>/dev</path> structure (creating or deleting device files).
162     </p>
163    
164     </body>
165     </section>
166     </chapter>
167    
168     <chapter>
169     <title>Using udev on Gentoo</title>
170     <section>
171     <title>Requirements</title>
172     <body>
173    
174     <p>
175     To be able to use udev on Gentoo, you must install
176     <c>sys-apps/baselayout-1.8.6.13</c> or later and <c>sys-fs/udev</c>.
177     If necessary, edit <path>/etc/portage/package.keywords</path> so that your
178     system uses the ~ARCH tree for those two packages:
179     </p>
180    
181     <pre caption="/etc/portage/package.keywords">
182     sys-apps/baselayout ~x86
183     sys-fs/udev ~x86
184     </pre>
185    
186     <p>
187     If you haven't done so already, also install <c>sys-apps/hotplug</c>.
188     </p>
189    
190     <pre caption="Installing necessary tools">
191     # <i>emerge baselayout udev hotplug</i>
192     </pre>
193    
194     <p>
195     Kernelwise, if you're using the default set by <c>genkernel</c> then you're all
196     set. Otherwise be sure to activate the following options:
197     </p>
198    
199     <pre caption="Required kernel options">
200     Bus options (PCI, PCMCIA, EISA, MCA, ISA) ---&gt;
201     [*] Support for hot-pluggable devices
202    
203     File systems ---&gt;
204     Pseudo filesystems ---&gt;
205     [*] /proc file system support
206     [*] /dev/pts file system for Unix98 PTYs
207     [*] Virtual memory file system support (former shm fs)
208     </pre>
209    
210     <p>
211     You can leave the <c>/dev file system support (OBSOLETE)</c> active if you
212     wish.
213     </p>
214    
215     </body>
216     </section>
217     <section>
218     <title>Configuration</title>
219     <body>
220    
221     <p>
222     First activate <c>hotplug</c> and have it started when you boot up your system:
223     </p>
224    
225     <pre caption="Adding hotplug to the default runlevel">
226     <comment>(Make sure that "boot" is used, not "default")</comment>
227     # <i>rc-update add hotplug boot</i>
228     # <i>/etc/init.d/hotplug start</i>
229     </pre>
230    
231     <p>
232     Now, if you're interested in the udev-tweaks Gentoo added to make your life
233     comfortable, then read no more. You're all set. The Gentoo init scripts won't
234     run the devfsd daemon and deactivate devfs when you boot up.
235     </p>
236    
237     <p>
238     But if you are a die-hard and want to run a udev-only, no-tweaked system as is
239     intended by the udev development, by all means, read on :)
240     </p>
241    
242     <warn>
243     Do <e>not</e> complain if something goes wrong. You're going to remove the hard
244     work of many Gentoo developers that hacked our init scripts to get udev playing
245     nicely with Gentoo!
246     </warn>
247    
248     <p>
249     First of all we'll deactivate the rules that save the device file nodes from
250     <path>/etc/init.d/halt.sh</path> and <path>/sbin/rc</path> by commenting them
251     out:
252     </p>
253    
254     <pre caption="/etc/init.d/halt.sh">
255     # We need to properly terminate devfsd to save the permissions
256     if [ -n "`ps --no-heading -C 'devfsd'`" ]
257     then
258     ebegin "Stopping devfsd"
259     killall -15 devfsd &amp; &gt; /dev/null
260     eend $?
261     elif [ ! -e /dev/.devfsd -a -e /dev/.udev ]
262     then
263     ebegin "Saving device nodes"
264     <comment>##cd /dev</comment>
265     <comment>##try tar -jclpf "/tmp/devices-$$.tar.bz2" *</comment>
266     <comment>##try mv -f "/tmp/devices-$$.tar.bz2" /lib/udev-state/devices.tar.bz2</comment>
267     eend 0
268     fi
269     </pre>
270    
271     <pre caption="/sbin/rc">
272     # Fix weird bug where there is a /dev/.devfsd in a unmounted /dev
273     mymounts="$(awk '($3 == "devfs") { print "yes"; exit 0 }' /proc/mounts)"
274     if [ -e "/dev/.devfsd" -a "${mymounts}" != "yes" ]
275     then
276     rm -f /dev/.devfsd
277     fi
278    
279     if [ "${udev}" = "yes" ]
280     then
281     ebegin "Mounting ramfs at /dev"
282     try mount -n -t ramfs none /dev
283     eend $?
284     ebegin "Configuring system to use udev"
285     einfo " Populating /dev with device nodes..."
286     <comment>##try tar -jxpf /lib/udev-state/devices.tar.bz2 -C /dev</comment>
287     populate_udev
288     if [ -e /proc/sys/kernel/hotplug -a -x /sbin/hotplug ]
289     then
290     einfo " Using /sbin/hotplug for udev management..."
291    
292     elif [ -e /proc/sys/kernel/hotplug ]
293     then
294     einfo " Setting /sbin/udev as hotplug agent..."
295     echo "/sbin/udev" &gt; /proc/sys/kernel/hotplug
296     else
297     ewarn " Kernel was not compiled with hotplug support!"
298     fi
299     eend 0
300     # Create problematic directories
301     mkdir -p /dev/{pts,shm}
302     # Same thing as /dev/.devfsd
303     touch /dev/.udev
304     </pre>
305    
306     <p>
307     We also need to manually create some device node files in order for our system
308     to perform a succesful boot:
309     </p>
310    
311     <pre caption="Creating necessary device node files">
312     # <i>mknod -m 660 /dev/console c 5 1</i>
313     # <i>mknod -m 660 /dev/null c 1 3</i>
314     </pre>
315    
316     <p>
317     If you have included devfs support in your kernel, you can deactivate it from
318     the bootloader configuration: add <c>devfs=nomount</c> as kernel parameter.
319     </p>
320    
321     <p>
322     If you want to use devfs and deactivate udev, add <c>gentoo=noudev</c> as kernel
323     parameter.
324     </p>
325    
326     </body>
327     </section>
328     <section>
329     <title>Current Issues</title>
330     <body>
331    
332     <p>
333     Please report the <e>temporary fixes</e> to current issues to the Gentoo
334     Documentation Project by using the <uri link="http://bugs.gentoo.org">Gentoo
335     Bugzilla</uri> website.
336     </p>
337    
338     </body>
339     </section>
340     </chapter>
341    
342     <chapter>
343     <title>Resources &amp; Acknowledgements</title>
344     <section>
345     <body>
346    
347     <p>
348     The udev talk on the Linux Symposium (Ottawa, Ontario Canada - 2003) given by
349     Greg Kroah-Hartman (IBM Corporation) provided a solid understanding on the udev
350     application.
351     </p>
352    
353     <p>
354     <uri link="http://webpages.charter.net/decibelshelp/LinuxHelp_UDEVPrimer.html">Decibel's
355     UDEV Primer</uri> is an in-depth document about udev and Gentoo.
356     </p>
357    
358     </body>
359     </section>
360     </chapter>
361    
362     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20