udev.xml 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381
  1. <?xml version="1.0" encoding="ISO-8859-1"?>
  2. <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  3. "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  4. <!ENTITY % general-entities SYSTEM "../general.ent">
  5. %general-entities;
  6. ]>
  7. <sect1 id="ch-scripts-udev">
  8. <?dbhtml filename="udev.html"?>
  9. <title>Device and Module Handling on an LFS System</title>
  10. <indexterm zone="ch-scripts-udev">
  11. <primary sortas="a-Udev">Udev</primary>
  12. <secondary>usage</secondary>
  13. </indexterm>
  14. <para>In <xref linkend="chapter-building-system"/>, we installed the Udev
  15. package. Before we go into the details regarding how this works,
  16. a brief history of previous methods of handling devices is in
  17. order.</para>
  18. <para>Linux systems in general traditionally use a static device creation
  19. method, whereby a great many device nodes are created under <filename
  20. class="directory">/dev</filename> (sometimes literally thousands of nodes),
  21. regardless of whether the corresponding hardware devices actually exist. This
  22. is typically done via a <command>MAKEDEV</command> script, which contains a
  23. number of calls to the <command>mknod</command> program with the relevant
  24. major and minor device numbers for every possible device that might exist in
  25. the world.</para>
  26. <para>Using the Udev method, only those devices which are detected by the
  27. kernel get device nodes created for them. Because these device nodes will be
  28. created each time the system boots, they will be stored on a <systemitem
  29. class="filesystem">devtmpfs</systemitem> file system (a virtual file system
  30. that resides entirely in system memory). Device nodes do not require much
  31. space, so the memory that is used is negligible.</para>
  32. <sect2>
  33. <title>History</title>
  34. <para>In February 2000, a new filesystem called <systemitem
  35. class="filesystem">devfs</systemitem> was merged into the 2.3.46 kernel
  36. and was made available during the 2.4 series of stable kernels. Although
  37. it was present in the kernel source itself, this method of creating devices
  38. dynamically never received overwhelming support from the core kernel
  39. developers.</para>
  40. <para>The main problem with the approach adopted by <systemitem
  41. class="filesystem">devfs</systemitem> was the way it handled device
  42. detection, creation, and naming. The latter issue, that of device node
  43. naming, was perhaps the most critical. It is generally accepted that if
  44. device names are allowed to be configurable, then the device naming policy
  45. should be up to a system administrator, not imposed on them by any
  46. particular developer(s). The <systemitem
  47. class="filesystem">devfs</systemitem> file system also suffers from race
  48. conditions that are inherent in its design and cannot be fixed without a
  49. substantial revision to the kernel. It was marked as deprecated for a long
  50. period &ndash; due to a lack of maintenance &ndash; and was finally removed
  51. from the kernel in June, 2006.</para>
  52. <para>With the development of the unstable 2.5 kernel tree, later released
  53. as the 2.6 series of stable kernels, a new virtual filesystem called
  54. <systemitem class="filesystem">sysfs</systemitem> came to be. The job of
  55. <systemitem class="filesystem">sysfs</systemitem> is to export a view of
  56. the system's hardware configuration to userspace processes. With this
  57. userspace-visible representation, the possibility of seeing a userspace
  58. replacement for <systemitem class="filesystem">devfs</systemitem> became
  59. much more realistic.</para>
  60. </sect2>
  61. <sect2>
  62. <title>Udev Implementation</title>
  63. <sect3>
  64. <title>Sysfs</title>
  65. <para>The <systemitem class="filesystem">sysfs</systemitem> filesystem was
  66. mentioned briefly above. One may wonder how <systemitem
  67. class="filesystem">sysfs</systemitem> knows about the devices present on
  68. a system and what device numbers should be used for them. Drivers that
  69. have been compiled into the kernel directly register their objects with
  70. <systemitem class="filesystem">sysfs</systemitem> as they are detected by
  71. the kernel. For drivers compiled as modules, this registration will happen
  72. when the module is loaded. Once the <systemitem
  73. class="filesystem">sysfs</systemitem> filesystem is mounted (on <filename
  74. class="directory">/sys</filename>), data which the built-in drivers
  75. registered with <systemitem class="filesystem">sysfs</systemitem> are
  76. available to userspace processes and to <command>udevd</command> for
  77. processing (including modifications to device nodes).</para>
  78. </sect3>
  79. <sect3>
  80. <title>Udev Bootscripts</title>
  81. <para>The <command>/etc/rc.d/init.d/udev</command> initscript takes care
  82. of creating device nodes when Linux is booted. The script unsets the
  83. uevent handler from the default of <command>/sbin/hotplug</command>.
  84. This is done because the kernel no longer needs to call out to an
  85. external binary. Instead <command>udevd</command> will listen on a
  86. netlink socket for uevents that the kernel raises. Next, the bootscript
  87. copies any static device nodes that exist in <filename
  88. class="directory">/lib/udev/devices</filename> to <filename
  89. class="directory">/dev</filename>. This is necessary because some
  90. devices, directories, and symlinks are needed before the dynamic device
  91. handling processes are available during the early stages of booting a
  92. system, or are required by <command>udevd</command> itself. Creating
  93. static device nodes in <filename
  94. class="directory">/lib/udev/devices</filename> also provides an easy
  95. workaround for devices that are not supported by the dynamic device
  96. handling infrastructure. The bootscript then starts the Udev daemon,
  97. <command>udevd</command>, which will act on any uevents it receives.
  98. Finally, the bootscript forces the kernel to replay uevents for any
  99. devices that have already been registered and then waits for
  100. <command>udevd</command> to handle them.</para>
  101. <para>The <command>/etc/rc.d/init.d/udev_retry</command> initscript takes
  102. care of re-triggering events for subsystems whose rules may rely on
  103. filesystems that are not mounted until the <command>mountfs</command>
  104. script is run (in particular, /usr and /var may cause this). This script
  105. runs after the <command>mountfs</command> script, so those rules (if
  106. re-triggered) should succeed the second time around. It is configured
  107. from the <filename>/etc/sysconfig/udev_retry</filename> file; any words
  108. in this file other than comments are considered subsystem names to
  109. trigger at retry time. (To find the subsystem of a device, use
  110. <command>udevadm info --attribute-walk</command>.)</para>
  111. </sect3>
  112. <sect3>
  113. <title>Device Node Creation</title>
  114. <para>In recent version of udev, <command>udevd</command> no longer
  115. creates device files in <filename class="directory">/dev</filename>.
  116. Instead, this must be handled in the kernel, by the <systemitem
  117. class="filesystem">devtmpfs</systemitem> filesystem. Any driver that
  118. wishes to register a device node will go through <systemitem
  119. class="filesystem">devtmpfs</systemitem> (via the driver core) to do it.
  120. When a <systemitem class="filesystem">devtmpfs</systemitem> instance is
  121. mounted on <filename class="directory">/dev</filename>, the device node
  122. will initially be created with a fixed name, permissions, and owner.</para>
  123. <para>A short time later, the kernel will send a uevent to <command>
  124. udevd</command>. Based on the rules specified in the files within the
  125. <filename class="directory">/etc/udev/rules.d</filename>, <filename
  126. class="directory">/lib/udev/rules.d</filename>, and <filename
  127. class="directory">/run/udev/rules.d</filename> directories, <command>
  128. udevd</command> will create additional symlinks to the device node,
  129. or change its permissions, owner, or group, or modify the internal
  130. <command>udevd</command> database entry for that object.</para>
  131. <para>The rules in these three directories are numbered in a similar
  132. fashion to the LFS-Bootscripts package, and all three directories are
  133. merged together. If <command>udevd</command> can't find a rule for the
  134. device it is creating, it will leave the permissions and ownership at
  135. whatever <systemitem class="filesystem">devtmpfs</systemitem> used
  136. initially.</para>
  137. </sect3>
  138. <sect3>
  139. <title>Module Loading</title>
  140. <para>Device drivers compiled as modules may have aliases built into them.
  141. Aliases are visible in the output of the <command>modinfo</command>
  142. program and are usually related to the bus-specific identifiers of devices
  143. supported by a module. For example, the <emphasis>snd-fm801</emphasis>
  144. driver supports PCI devices with vendor ID 0x1319 and device ID 0x0801,
  145. and has an alias of <quote>pci:v00001319d00000801sv*sd*bc04sc01i*</quote>.
  146. For most devices, the bus driver exports the alias of the driver that
  147. would handle the device via <systemitem
  148. class="filesystem">sysfs</systemitem>. E.g., the
  149. <filename>/sys/bus/pci/devices/0000:00:0d.0/modalias</filename> file
  150. might contain the string
  151. <quote>pci:v00001319d00000801sv00001319sd00001319bc04sc01i00</quote>.
  152. The default rules provided with Udev will cause <command>udevd</command>
  153. to call out to <command>/sbin/modprobe</command> with the contents of the
  154. <envar>MODALIAS</envar> uevent environment variable (which should be the
  155. same as the contents of the <filename>modalias</filename> file in sysfs),
  156. thus loading all modules whose aliases match this string after wildcard
  157. expansion.</para>
  158. <para>In this example, this means that, in addition to
  159. <emphasis>snd-fm801</emphasis>, the obsolete (and unwanted)
  160. <emphasis>forte</emphasis> driver will be loaded if it is
  161. available. See below for ways in which the loading of unwanted drivers can
  162. be prevented.</para>
  163. <para>The kernel itself is also able to load modules for network
  164. protocols, filesystems and NLS support on demand.</para>
  165. </sect3>
  166. <sect3>
  167. <title>Handling Hotpluggable/Dynamic Devices</title>
  168. <para>When you plug in a device, such as a Universal Serial Bus (USB) MP3
  169. player, the kernel recognizes that the device is now connected and
  170. generates a uevent. This uevent is then handled by
  171. <command>udevd</command> as described above.</para>
  172. </sect3>
  173. </sect2>
  174. <sect2>
  175. <title>Problems with Loading Modules and Creating Devices</title>
  176. <para>There are a few possible problems when it comes to automatically
  177. creating device nodes.</para>
  178. <sect3>
  179. <title>A kernel module is not loaded automatically</title>
  180. <para>Udev will only load a module if it has a bus-specific alias and the
  181. bus driver properly exports the necessary aliases to <systemitem
  182. class="filesystem">sysfs</systemitem>. In other cases, one should
  183. arrange module loading by other means. With Linux-&linux-version;, Udev is
  184. known to load properly-written drivers for INPUT, IDE, PCI, USB, SCSI,
  185. SERIO, and FireWire devices.</para>
  186. <para>To determine if the device driver you require has the necessary
  187. support for Udev, run <command>modinfo</command> with the module name as
  188. the argument. Now try locating the device directory under
  189. <filename class="directory">/sys/bus</filename> and check whether there is
  190. a <filename>modalias</filename> file there.</para>
  191. <para>If the <filename>modalias</filename> file exists in <systemitem
  192. class="filesystem">sysfs</systemitem>, the driver supports the device and
  193. can talk to it directly, but doesn't have the alias, it is a bug in the
  194. driver. Load the driver without the help from Udev and expect the issue
  195. to be fixed later.</para>
  196. <para>If there is no <filename>modalias</filename> file in the relevant
  197. directory under <filename class="directory">/sys/bus</filename>, this
  198. means that the kernel developers have not yet added modalias support to
  199. this bus type. With Linux-&linux-version;, this is the case with ISA
  200. busses. Expect this issue to be fixed in later kernel versions.</para>
  201. <para>Udev is not intended to load <quote>wrapper</quote> drivers such as
  202. <emphasis>snd-pcm-oss</emphasis> and non-hardware drivers such as
  203. <emphasis>loop</emphasis> at all.</para>
  204. </sect3>
  205. <sect3>
  206. <title>A kernel module is not loaded automatically, and Udev is not
  207. intended to load it</title>
  208. <para>If the <quote>wrapper</quote> module only enhances the functionality
  209. provided by some other module (e.g., <emphasis>snd-pcm-oss</emphasis>
  210. enhances the functionality of <emphasis>snd-pcm</emphasis> by making the
  211. sound cards available to OSS applications), configure
  212. <command>modprobe</command> to load the wrapper after Udev loads the
  213. wrapped module. To do this, add a <quote>softdep</quote> line in any
  214. <filename>/etc/modprobe.d/<replaceable>&lt;filename&gt;</replaceable>.conf</filename>
  215. file. For example:</para>
  216. <screen role="nodump"><literal>softdep snd-pcm post: snd-pcm-oss</literal></screen>
  217. <para>Note that the <quote>softdep</quote> command also allows
  218. <literal>pre:</literal> dependencies, or a mixture of both
  219. <literal>pre:</literal> and <literal>post:</literal>. See the
  220. <filename>modprobe.d(5)</filename> manual page for more information
  221. on <quote>softdep</quote> syntax and capabilities.</para>
  222. <para>If the module in question is not a wrapper and is useful by itself,
  223. configure the <command>modules</command> bootscript to load this
  224. module on system boot. To do this, add the module name to the
  225. <filename>/etc/sysconfig/modules</filename> file on a separate line.
  226. This works for wrapper modules too, but is suboptimal in that case.</para>
  227. </sect3>
  228. <sect3>
  229. <title>Udev loads some unwanted module</title>
  230. <para>Either don't build the module, or blacklist it in a
  231. <filename>/etc/modprobe.d/blacklist.conf</filename> file as done with the
  232. <emphasis>forte</emphasis> module in the example below:</para>
  233. <screen role="nodump"><literal>blacklist forte</literal></screen>
  234. <para>Blacklisted modules can still be loaded manually with the
  235. explicit <command>modprobe</command> command.</para>
  236. </sect3>
  237. <sect3>
  238. <title>Udev creates a device incorrectly, or makes a wrong symlink</title>
  239. <para>This usually happens if a rule unexpectedly matches a device. For
  240. example, a poorly-writen rule can match both a SCSI disk (as desired)
  241. and the corresponding SCSI generic device (incorrectly) by vendor.
  242. Find the offending rule and make it more specific, with the help of the
  243. <command>udevadm info</command> command.</para>
  244. </sect3>
  245. <sect3>
  246. <title>Udev rule works unreliably</title>
  247. <para>This may be another manifestation of the previous problem. If not,
  248. and your rule uses <systemitem class="filesystem">sysfs</systemitem>
  249. attributes, it may be a kernel timing issue, to be fixed in later kernels.
  250. For now, you can work around it by creating a rule that waits for the used
  251. <systemitem class="filesystem">sysfs</systemitem> attribute and appending
  252. it to the <filename>/etc/udev/rules.d/10-wait_for_sysfs.rules</filename>
  253. file (create this file if it does not exist). Please notify the LFS
  254. Development list if you do so and it helps.</para>
  255. </sect3>
  256. <sect3>
  257. <title>Udev does not create a device</title>
  258. <para>Further text assumes that the driver is built statically into the
  259. kernel or already loaded as a module, and that you have already checked
  260. that Udev doesn't create a misnamed device.</para>
  261. <para>Udev has no information needed to create a device node if a kernel
  262. driver does not export its data to <systemitem
  263. class="filesystem">sysfs</systemitem>.
  264. This is most common with third party drivers from outside the kernel
  265. tree. Create a static device node in
  266. <filename>/lib/udev/devices</filename> with the appropriate major/minor
  267. numbers (see the file <filename>devices.txt</filename> inside the kernel
  268. documentation or the documentation provided by the third party driver
  269. vendor). The static device node will be copied to
  270. <filename class="directory">/dev</filename> by the
  271. <command>udev</command> bootscript.</para>
  272. </sect3>
  273. <sect3>
  274. <title>Device naming order changes randomly after rebooting</title>
  275. <para>This is due to the fact that Udev, by design, handles uevents and
  276. loads modules in parallel, and thus in an unpredictable order. This will
  277. never be <quote>fixed</quote>. You should not rely upon the kernel device
  278. names being stable. Instead, create your own rules that make symlinks with
  279. stable names based on some stable attributes of the device, such as a
  280. serial number or the output of various *_id utilities installed by Udev.
  281. See <xref linkend="ch-scripts-symlinks"/> and
  282. <xref linkend="ch-scripts-network"/> for examples.</para>
  283. </sect3>
  284. </sect2>
  285. <sect2>
  286. <title>Useful Reading</title>
  287. <para>Additional helpful documentation is available at the following
  288. sites:</para>
  289. <itemizedlist>
  290. <listitem>
  291. <para>A Userspace Implementation of <systemitem class="filesystem">devfs</systemitem>
  292. <ulink url="http://www.kroah.com/linux/talks/ols_2003_udev_paper/Reprint-Kroah-Hartman-OLS2003.pdf"/></para>
  293. </listitem>
  294. <listitem>
  295. <para>The <systemitem class="filesystem">sysfs</systemitem> Filesystem
  296. <ulink url="http://www.kernel.org/pub/linux/kernel/people/mochel/doc/papers/ols-2005/mochel.pdf"/></para>
  297. </listitem>
  298. <listitem>
  299. <para>Pointers to further reading
  300. <ulink url="http://www.kernel.org/pub/linux/utils/kernel/hotplug/udev.html"/>
  301. </para>
  302. </listitem>
  303. </itemizedlist>
  304. </sect2>
  305. </sect1>