OLD/hotplug_usb_firewire.txt

   1 AUTHOR: Kelledin <kelledin@users.sourceforge.net>
   2 DATE: 2003-09-20
   3 LICENSE: GNU Free Documentation License
   4 SYNOPSIS: Managing hot-pluggable devices with Murasaki
   5 DESCRIPTION:
   6 The Linux 2.4 kernel sports a new, more unified infrastructure for
   7 hot-pluggable devices (USB, IEEE1394, HotPlug PCI, etc).  This new
   8 infrastructure is designed to support automatic device and driver
   9 management by privileged userspace apps.  One such app designed for
  10 the purpose is murasaki.
  11
  12 PREREQUISITES: LFS 3.3 or later, kernel 2.4.1 or later
  13
  14 HINT:
  15 1. Background Information
  16 ------------------------------------------------------------------------------
  17 The Linux 2.4.x kernel sports a nifty little method of handling hot-pluggable
  18 devices (USB, IEEE1394, CardBus, hot-plug PCI).  Essentially, whenever the
  19 kernel detects the connection or disconnection of a hot-plug device, it will
  20 call a specified user-space program to handle loading/unloading of the
  21 associated driver.  Although an admin can load/unload the necessary drivers
  22 manually via modprobe, it's rather convenient to have a background process
  23 do this automatically.
  24
  25 This is where murasaki comes in.  It's based closely on an older application
  26 called usbmgr; in fact, it comes from many of the same authors and shares
  27 much of the same code.  usbmgr, however, only supports USB devices.
  28
  29 When the "murasaki" service is started, it will register
  30 "/sbin/hotplug.murasaki" as the user-space process that should be called to
  31 handle loading/unloading of hot-plug device drivers.  Currently, this is done
  32 by setting the contents of /proc/sys/kernel/hotplug to
  33 "/sbin/hotplug.murasaki"; the default value assigned by the kernel on boot is
  34 "/sbin/hotplug".
  35
  36 If you're wondering how this package came by the name Murasaki...I don't know.
  37 Google tells me that Murasaki is Japanese for "purple", and it happens to be
  38 the first name of the world's first novelist (Murasaki Shikibu).
  39
  40
  41 2. Caveats
  42 ------------------------------------------------------------------------------
  43 murasaki works quite well for USB and FireWire, but for CardBus/PCMCIA
  44 devices, pcmcia-cs is the preferred solution.  Fortunately, the two can
  45 coexist, although you should prevent murasaki's PCMCIA loader from running,
  46 just to be safe.  This is a simple matter of setting certain parameters in a
  47 configuration file; this will be described later.
  48
  49 Not all hot-plug devices are supported (obviously).  You can check the status
  50 of your devices at http://www.dotaster.com/~shuu/murasaki/device.html .
  51
  52 Also, note that not all PCI implementations are hot-plug PCI.  Hot-plug PCI
  53 features is currently only present in a few heavy-duty x86 servers, such as
  54 those from Compaq, and they require support from both the motherboard (or PCI
  55 backplane) and the PCI peripheral being hot-plugged.  Check your system
  56 documentation to determine whether your hardware supports hot-plug PCI; DO
  57 NOT JUST YANK RUNNING PCI CARDS TO EXPERIMENT, as this could very easily damage
  58 your hardware!!!  Also, make sure your specific hot-plug PCI implementation is
  59 supported by your Linux kernel.
  60
  61
  62 3. Detailed prerequisites
  63 ------------------------------------------------------------------------------
  64 In order to get Murasaki working, you will first need a 2.4.x kernel.  2.4.0
  65 does not cooperate with Murasaki without some patching, which I won't cover
  66 here.  Get your preferred kernel from ftp.kernel.org or one of its many
  67 mirrors, if you haven't already.
  68
  69 When you compile this kernel, you will need to make sure it has HotPlug
  70 support (CONFIG_HOTPLUG) and /proc filesystem support (CONFIG_PROC_FS), in
  71 addition to all the other options you normally use.  If you wish to use the
  72 kernel's PCMCIA hardware modules, you should enable these as well, otherwise
  73 DISABLE "PCMCIA support" in the kernel.  Currently it is recommended that you
  74 disable "PCMCIA support" in the kernel and rely upon the modules from pcmcia-cs
  75 to serve your PCMCIA support needs.
  76
  77 Also, in the (unlikely) event that your system has a working, usable hot-plug
  78 PCI implementation, you might want to enable the appropriate kernel driver
  79 for this functionality.
  80
  81 You will also (obviously) need Murasaki.  At the time of this writing, the
  82 latest "stable" version is 0.6.11, located at
  83
  84     http://www.dotaster.com/~shuu/murasaki/0.6/0.6.11/murasaki-0.5.4.tar.gz
  85
  86 Although this may not be necessary, you should also get the latest preload
  87 and device maps at http://www.dotaster.com/~shuu/linux/murasaki/ .  They
  88 should be listed separately among the other package downloads.  These files
  89 should add the most current level of device support to Murasaki.
  90
  91
  92 4. Compiling
  93 ------------------------------------------------------------------------------
  94 I refuse to hold your hand through a kernel compile.  If you don't know how
  95 to compile your own kernel, you shouldn't be using LFS in the first place.
  96
  97 Compiling Murasaki is easy.  First untar the source in your favorite compiling
  98 directory and cd to the resulting source-tree directory.  Before you actually
  99 run "make", however, you should make a few decisions.
 100
 101 Murasaki defaults to putting binaries in /sbin, config files in /etc/murasaki,
 102 the init script under /etc/rc.d/init.d, and runlevel symlinks under /etc/rc.d.
 103 While this is generally sensible, you may want to make a few changes.  For
 104 instance, I like for init scripts to go under /etc/init.d (as per the
 105 LSB+FHS), and runlevel symlinks to go under /etc.  Plus, I prefer to make my
 106 runlevel symlinks manually.  In order to make such changes yourself, edit the
 107 make.defs file in the Murasaki source tree and search for the definitions of
 108 BIN_DIR, CONF_DIR, RC_DIR, and RC_INIT_DIR.  If you are like me (you prefer to
 109 create runlevel symlinks yourself), or you use a BSD-style init, you can
 110 simply set RC_DIR to point to some middle-of-nowhere path in /tmp and scrap
 111 the files Murasaki creates under there after you're done.  Just be sure to set
 112 RC_INIT_DIR properly whenever you change RC_DIR.
 113
 114 Also, if you have an /etc/murasaki/murasaki.preload file left around from an
 115 earlier version, and you would like it replaced by the file from 0.5.4,
 116 be sure to remove /etc/murasaki/murasaki.preload before you run "make".
 117
 118 Now run the following commands:
 119
 120     make &&
 121     make install
 122
 123 Now copy the separate preload and device maps you downloaded to /etc/murasaki
 124 (or whatever location you specified for CONF_DIR).
 125
 126
 127 5. Enabling Murasaki
 128 ------------------------------------------------------------------------------
 129 First, you may want to enable or disable murasaki's handling of certain device
 130 types.  This involves editing your murasaki.conf file to (located in CONF_DIR).
 131 In particular, you may wish to disable the "pci" functionality, which happens
 132 to encompass both PCMCIA and hot-plug PCI.
 133
 134 Now you can now go about enabling Murasaki.  The preferred way to do this is
 135 is to use its SysV init script (i.e. run "/etc/init.d/murasaki start").  This
 136 takes care of some additional setup that may be necessary--mainly checking
 137 your PCI device tables to see what USB/FireWire controller chip you're using,
 138 and loading the appropriate driver.
 139
 140 You could also simply create a symlink called "/sbin/hotplug" to your
 141 hotplug.murasaki exectuable (usually /sbin/hotplug.murasaki), but you then
 142 lose the automatic initial setup.  You may be able to get by like this, but
 143 you're on your own if you try it.
 144
 145 To check and see if the murasaki service has been started, you can run
 146
 147     cat /proc/sys/kernel/hotplug
 148
 149 and see if the output is identical to the full path of your hotplug.murasaki
 150 executable.  If it is, Murasaki will handle all requests for driver
 151 loading/unloading whenever an appropriate hot-plug device is connected or
 152 disconnected.
 153
 154 You can now connect your favorite (supported) USB/FireWire device.  When you
 155 plug it in, you should hear your PC speaker beep rather unobtrusively (unless
 156 you've disabled the beep somehow), and the device driver should be loaded
 157 automatically.
 158
 159 Congratulations, you (probably) have a properly working Murasaki service.  If
 160 you don't, well, you're more-or-less on your own. ;)
 161
 162 ------------------------------------------------------------------------------
 163
 164 CHANGELOG:
 165 [2003-09-20]
 166 * Updated to expand details and
 167 * Rewrote to accommodate new hints format.