base/udev/readme-udev-arch.txt

   1 ==========================
   2 Cold/Hotplugging with Udev
   3 ==========================
   4 Version 1.1.5
   5 written by Tobias Powalowski <tpowa@archlinux.org>
   6
   7 ---------------
   8 * Requirements:
   9 ---------------
  10 - recommended kernel >=2.6.18 for this udev to work properly.
  11 - No more DevFS device paths!  If you have them, update /etc/fstab:
  12   /dev/discs/... etc. has been deprecated in favor of the old style:
  13     /dev/discs/disc0/part1 -> /dev/hda1
  14     /dev/discs/disc1/part2 -> /dev/hdb2
  15 - /etc/modprobe.conf should be cleaned from old install entries (see below).
  16
  17 ---------------
  18 * Udev Changes:
  19 ---------------
  20 - The syntax of udev rules has been changed in >=098 release, please update your rules.
  21   --- Snip Changelog Udev 098
  22   Renaming of some key names:
  23   BUS -> SUBSYSTEMS
  24   ID -> KERNELS
  25   SYSFS -> ATTRS
  26   DRIVER -> DRIVERS
  27   ATTR{file}="value" can be used now, to write to a sysfs file of the
  28   event device. Instead of:
  29     ..., SYSFS{type}=="0|7|14", RUN+="/bin/sh -c 'echo 60 > /sys$$DEVPATH/timeout'"
  30   we now can do:
  31     ..., ATTR{type}=="0|7|14", ATTR{timeout}="60"
  32   All the PHYSDEV* keys are deprecated and will be removed from a
  33   future kernel:
  34     PHYDEVPATH -    is the path of a parent device and should not be
  35                     needed at all.
  36     PHYSDEVBUS -    is just a SUBSYSTEM value of a parent, and can be
  37                     matched with SUBSYSTEMS==
  38     PHYSDEVDRIVER - for bus devices it is available as ENV{DRIVER}.
  39                     Newer kernels will have DRIVER in the environment,
  40                     for older kernels udev puts in. Class device will
  41                     no longer carry this property of a parent and
  42                     DRIVERS== can be used to match such a parent value.
  43   Note that ENV{DRIVER} is only available for a few bus devices, where
  44   the driver is already bound at device event time. On coldplug, the
  45   events for a lot devices are already bound to a driver, and they will have
  46   that value set. But on hotplug, at the time the kernel creates the device,
  47   it can't know what driver may claim the device after that, therefore
  48   in most cases it will be empty.
  49   --- snap Changelog Udev 098
  50 - optional udev >= 099 Persistent rules generator for network and cd/dvd devices was added.
  51
  52 ---------------
  53 * How it works:
  54 ---------------
  55 - Udev replaces the functionality of hotplug and hwdetect scripts.
  56 - Udev does autoloading of modules and coldplugging.
  57 - Udev loads the modules simultaneously, which is much faster,
  58   but can cause some troubles with multiple network/sound/etc devices
  59   (see below).
  60 - To reload your rules please use /etc/start_udev.
  61
  62 ======================
  63 * Autoloading modules:
  64 ======================
  65
  66 -------------------------------------------------------------------------
  67 * Module autoloading is controlled by MOD_AUTOLOAD="" in /etc/rc.conf
  68 -------------------------------------------------------------------------
  69 MOD_AUTOLOAD="yes" in /etc/rc.conf is necessary:
  70 - if you want module autodetection
  71 - if you want modules be loaded by udev (hotplugging and coldplugging)
  72
  73 MOD_AUTOLOAD="no" is necessary:
  74 - if you want to load modules strictly using 'modprobe <module>'
  75 - if you want to load only the modules listed in the MODULES=() array
  76   in /etc/rc.conf
  77
  78 ---------------
  79 * Blacklisting:
  80 ---------------
  81 - means udev will never try to load the module, even if MOD_AUTOLOAD="yes"
  82   is set.
  83
  84 You can do this in 2 ways:
  85 - MOD_BLACKLIST=(moduleA moduleB)
  86 - MODULES=(!moduleA !moduleB)
  87
  88 Both entries mean the same thing to udev.  MOD_BLACKLIST was used by hwdetect.
  89 hwdetect does not understand the MODULES= syntax, but it doesn't have to -- it
  90 is only used in mkinitrd now.
  91
  92 ==================================
  93 * Boot parameter: load_modules=off
  94 ==================================
  95
  96 - No modules are loaded during boot using udev autoloading or the MODULES array
  97 - Useful for repairing your system if something goes wrong during udev startup
  98   and/or during loading modules
  99
 100 ==================================
 101 * Boot parameter: disablemodules=
 102 ==================================
 103
 104 - list modules there that shouldn't be loaded by udev
 105 - Syntax: disablemodules=module1,module2,module3,...
 106 - Useful for repairing your system if something goes wrong during udev startup
 107   and/or during loading modules and you know the module that causes the trouble.
 108
 109 ========================================
 110 * Persistent CD/DVD symlinks (optional):
 111 ========================================
 112
 113 - To enable this feature copy in /etc/udev/rules.d
 114   75-cd-aliases-generator.rules.optinal
 115   to 75-cd-aliases-generator.rules
 116   Also disable this part in /etc/udev/rules.d/udev.rules by putting a # in front:
 117   --- snip
 118   ACTION=="add", SUBSYSTEMS=="ide", KERNEL=="hd[a-z]", ATTR{removable}=="1", ATTRS{media}=="cdrom*", RUN+="/lib/udev/cdsymlinks.sh"
 119   ACTION=="add", SUBSYSTEMS=="scsi", KERNEL=="sr[0-9]*", ATTRS{type}=="5", RUN+="/lib/udev/cdsymlinks.sh"
 120   ACTION=="add", SUBSYSTEMS=="scsi", KERNEL=="sg[0-9]*", ATTRS{type}=="5", RUN+="/lib/udev/cdsymlinks.sh"
 121   ACTION=="remove", SUBSYSTEMS=="block", KERNEL=="hd[a-z]", RUN+="/lib/udev/cdsymlinks.sh"
 122   ACTION=="remove", SUBSYSTEMS=="block", KERNEL=="sr[0-9]*", RUN+="/lib/udev/cdsymlinks.sh"
 123   ACTION=="remove", SUBSYSTEMS=="block", KERNEL=="sg[0-9]*", RUN+="/lib/udev/cdsymlinks.sh"
 124 --- snap
 125
 126 - To get the same device name for CD/DVD symlinks each time you boot,
 127   a rule will be generated during bootup or by executing /etc/start_udev.
 128 - Examples: dvd, cdrom ,cdrw etc.
 129 - If you want to change those links,
 130   modify '/etc/udev/rules.d/70-peristent-cd.rules' to your needs.
 131
 132 Known issues:
 133 The symlink name is then bound to the hardware pci adress,
 134 if you change your CD/DVD device, you have to check the
 135 /etc/udev/rules.d/70-peristent-net.rules file for correctness.
 136
 137 ======================================
 138 * Persistent Network names (optional):
 139 ======================================
 140
 141 - To enable this feature copy in /etc/udev/rules.d
 142   75-persistent-net-generator.rules.optional
 143   to 75-persistent-net-generator.rules
 144 - To get the same network device name each time you boot,
 145   a rule will be generated during bootup or by executing /etc/start_udev.
 146 - Examples: eth0, eth1, wlan0 etc.
 147 - If you want to change those names,
 148   modify '/etc/udev/rules.d/70-peristent-net.rules' to your needs.
 149 - NAME= determines the name of your network card. Use these names in your
 150   network configuration in rc.conf as well.
 151
 152 Known issues:
 153 The interface name is then bound to the hardware mac adress,
 154 if you change your network card, you have to check the
 155 /etc/udev/rules.d/70-peristent-net.rules file for correctness.
 156
 157 ====================================
 158 * Known Problems Hardware:
 159 ====================================
 160
 161 - BusLogic devices are broken and will cause a freeze during startup
 162 Solution:
 163 This is a kernel bug and no fix has been provided yet.
 164
 165 - PCMCIA Card readers are not treated as removabel devices.
 166 Solution:
 167 To get access to them with hal's pmount backend add them to /etc/pmount.allow
 168
 169 ====================================
 170 * Known Problems MOD_AUTOLOAD="yes":
 171 ====================================
 172
 173 -----------------------------------------------------------------------------
 174 * Sound is not working or modules (eg. parport) are not loaded automatically:
 175 -----------------------------------------------------------------------------
 176 Solution:
 177 - Do you have a clean /etc/modprobe.conf?
 178   - A clean /etc/modprobe.conf is empty.  The stock modprobe.conf file
 179     contains nothing
 180 - alsaconf can write output to modprobe.conf. Please keep that in mind.
 181
 182 ---------------------------------------------
 183 * Devices get mixed up eg. Network/Soundcards
 184 ---------------------------------------------
 185 - Because udev loads all the modules at once, sometimes devices are initialized
 186   in different orders (eg. network cards switch eth0 and eth1, sound cards
 187   the same)
 188
 189 Solution:
 190 - Load them in MODULES=() array in the order you need them
 191 - eg: MODULES=(moduleA moduleB)
 192
 193 Second solution for network:
 194 - The "proper" way to configure net interfaces to hold static names within
 195   udev rules.  Add lines like these to a custom rules file such as
 196   /etc/udev/rules.d/01-network.rules:
 197     SUBSYSTEM=="net", SYSFS{address}=="aa:bb:cc:dd:ee:ff", NAME="lan0"
 198     SUBSYSTEM=="net", SYSFS{address}=="ff:ee:dd:cc:bb:aa", NAME="wlan0"
 199
 200 - To get the right mac address use this command:
 201     udevinfo -a -p /sys/class/net/<yourdevice>
 202 - Make sure you use lower-case hex values in your udev rules.
 203 - NAME= determines the name of your network card.  Use these names in your
 204   network configuration in rc.conf as well.
 205
 206 Third solution for network:
 207 - check Persistent Network part
 208
 209 -----------------------------------
 210 * Network 8139too & 8139cp problem:
 211 -----------------------------------
 212 - Both modules have the same kernel entry, which can cause problems.
 213 Solution:
 214 - Enter the one you need in MODULES=() and blacklist the other one
 215 - eg: MODULES=(!8139cp 8139too)
 216 - The example tells udev to ignore 8139cp module and load 8139too afterwards.
 217
 218 --------------------------------------------------------
 219 * You need a special loading order to get devices going:
 220 --------------------------------------------------------
 221 - Kernel loads modules in wrong order.
 222 Solution:
 223 - Load them in the correct order in MODULES=()
 224
 225 -----------------------------
 226 * Module is not autodetected:
 227 -----------------------------
 228 - If your device does not provide a modalias in /sys it cannot be autodetected.
 229 - If modalias is not combined to a kernel module it cannot be autodetected.
 230 Known modules that are not autodetected:
 231 - SCSI CONTROLLER:
 232   scsi_transport_sas ultrastor qlogicfas eata BusLogic pas16 wd7000 sym53c416
 233   g_NCR5380_mmio fdomain u14-34f dtc initio in2000 imm t128 aha1542 aha152x
 234   atp870u g_NCR5380 NCR53c406a qlogicfas408 megaraid_mm advansys
 235 - NETWORK CARDS:
 236   hp ne de4x5 wd cs89x0 eepro smc9194 seeq8005 ni52 ni65 ac3200 smc-ultra
 237   at1700 hp-plus depca eexpress 82596 de600 eth16i de620 lance ewrk3 e2100
 238   lp486e 3c501 3c503 3c505 3c507 3c509 3c515 myri10ge
 239 Solution:
 240 - Enter the one you need in MODULES=()
 241
 242 =======================================
 243 * Known Problems with MOD_AUTOLOAD="no"
 244 =======================================
 245
 246 -----------------------------------------------------------------
 247 * Modules are not loaded anymore during coldplug or hotplug event
 248 -----------------------------------------------------------------
 249 - Udev is usually responsible for this, but the MOD_AUTOLOAD switch will
 250   now disable it.  If you want automatic hot/cold-plugging, turn on
 251   MOD_AUTOLOAD.  Otherwise you will have to load all your modules manually,
 252   either with /sbin/modprobe or entries in the MODULES=() array.
 253 Solution:
 254 - For bootup (coldplug) enter this in rc.conf: MODULES=(moduleA moduleB)
 255 - After bootup (hotplug) use this: modprobe <moduleA>
 256
 257 =========================================
 258 * Known problems for custom kernel users:
 259 =========================================
 260
 261 ----------------------------
 262 * Udev doesn't start at all:
 263 ----------------------------
 264 - Check Requirements list