udev.xml 16 KB

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