AUTHOR: Kelledin DATE: 2003-09-20 LICENSE: GNU Free Documentation License SYNOPSIS: Managing hot-pluggable devices with Murasaki DESCRIPTION: The Linux 2.4 kernel sports a new, more unified infrastructure for hot-pluggable devices (USB, IEEE1394, HotPlug PCI, etc). This new infrastructure is designed to support automatic device and driver management by privileged userspace apps. One such app designed for the purpose is murasaki. PREREQUISITES: LFS 3.3 or later, kernel 2.4.1 or later HINT: 1. Background Information ------------------------------------------------------------------------------ The Linux 2.4.x kernel sports a nifty little method of handling hot-pluggable devices (USB, IEEE1394, CardBus, hot-plug PCI). Essentially, whenever the kernel detects the connection or disconnection of a hot-plug device, it will call a specified user-space program to handle loading/unloading of the associated driver. Although an admin can load/unload the necessary drivers manually via modprobe, it's rather convenient to have a background process do this automatically. This is where murasaki comes in. It's based closely on an older application called usbmgr; in fact, it comes from many of the same authors and shares much of the same code. usbmgr, however, only supports USB devices. When the "murasaki" service is started, it will register "/sbin/hotplug.murasaki" as the user-space process that should be called to handle loading/unloading of hot-plug device drivers. Currently, this is done by setting the contents of /proc/sys/kernel/hotplug to "/sbin/hotplug.murasaki"; the default value assigned by the kernel on boot is "/sbin/hotplug". If you're wondering how this package came by the name Murasaki...I don't know. Google tells me that Murasaki is Japanese for "purple", and it happens to be the first name of the world's first novelist (Murasaki Shikibu). 2. Caveats ------------------------------------------------------------------------------ murasaki works quite well for USB and FireWire, but for CardBus/PCMCIA devices, pcmcia-cs is the preferred solution. Fortunately, the two can coexist, although you should prevent murasaki's PCMCIA loader from running, just to be safe. This is a simple matter of setting certain parameters in a configuration file; this will be described later. Not all hot-plug devices are supported (obviously). You can check the status of your devices at http://www.dotaster.com/~shuu/murasaki/device.html . Also, note that not all PCI implementations are hot-plug PCI. Hot-plug PCI features is currently only present in a few heavy-duty x86 servers, such as those from Compaq, and they require support from both the motherboard (or PCI backplane) and the PCI peripheral being hot-plugged. Check your system documentation to determine whether your hardware supports hot-plug PCI; DO NOT JUST YANK RUNNING PCI CARDS TO EXPERIMENT, as this could very easily damage your hardware!!! Also, make sure your specific hot-plug PCI implementation is supported by your Linux kernel. 3. Detailed prerequisites ------------------------------------------------------------------------------ In order to get Murasaki working, you will first need a 2.4.x kernel. 2.4.0 does not cooperate with Murasaki without some patching, which I won't cover here. Get your preferred kernel from ftp.kernel.org or one of its many mirrors, if you haven't already. When you compile this kernel, you will need to make sure it has HotPlug support (CONFIG_HOTPLUG) and /proc filesystem support (CONFIG_PROC_FS), in addition to all the other options you normally use. If you wish to use the kernel's PCMCIA hardware modules, you should enable these as well, otherwise DISABLE "PCMCIA support" in the kernel. Currently it is recommended that you disable "PCMCIA support" in the kernel and rely upon the modules from pcmcia-cs to serve your PCMCIA support needs. Also, in the (unlikely) event that your system has a working, usable hot-plug PCI implementation, you might want to enable the appropriate kernel driver for this functionality. You will also (obviously) need Murasaki. At the time of this writing, the latest "stable" version is 0.6.11, located at http://www.dotaster.com/~shuu/murasaki/0.6/0.6.11/murasaki-0.5.4.tar.gz Although this may not be necessary, you should also get the latest preload and device maps at http://www.dotaster.com/~shuu/linux/murasaki/ . They should be listed separately among the other package downloads. These files should add the most current level of device support to Murasaki. 4. Compiling ------------------------------------------------------------------------------ I refuse to hold your hand through a kernel compile. If you don't know how to compile your own kernel, you shouldn't be using LFS in the first place. Compiling Murasaki is easy. First untar the source in your favorite compiling directory and cd to the resulting source-tree directory. Before you actually run "make", however, you should make a few decisions. Murasaki defaults to putting binaries in /sbin, config files in /etc/murasaki, the init script under /etc/rc.d/init.d, and runlevel symlinks under /etc/rc.d. While this is generally sensible, you may want to make a few changes. For instance, I like for init scripts to go under /etc/init.d (as per the LSB+FHS), and runlevel symlinks to go under /etc. Plus, I prefer to make my runlevel symlinks manually. In order to make such changes yourself, edit the make.defs file in the Murasaki source tree and search for the definitions of BIN_DIR, CONF_DIR, RC_DIR, and RC_INIT_DIR. If you are like me (you prefer to create runlevel symlinks yourself), or you use a BSD-style init, you can simply set RC_DIR to point to some middle-of-nowhere path in /tmp and scrap the files Murasaki creates under there after you're done. Just be sure to set RC_INIT_DIR properly whenever you change RC_DIR. Also, if you have an /etc/murasaki/murasaki.preload file left around from an earlier version, and you would like it replaced by the file from 0.5.4, be sure to remove /etc/murasaki/murasaki.preload before you run "make". Now run the following commands: make && make install Now copy the separate preload and device maps you downloaded to /etc/murasaki (or whatever location you specified for CONF_DIR). 5. Enabling Murasaki ------------------------------------------------------------------------------ First, you may want to enable or disable murasaki's handling of certain device types. This involves editing your murasaki.conf file to (located in CONF_DIR). In particular, you may wish to disable the "pci" functionality, which happens to encompass both PCMCIA and hot-plug PCI. Now you can now go about enabling Murasaki. The preferred way to do this is is to use its SysV init script (i.e. run "/etc/init.d/murasaki start"). This takes care of some additional setup that may be necessary--mainly checking your PCI device tables to see what USB/FireWire controller chip you're using, and loading the appropriate driver. You could also simply create a symlink called "/sbin/hotplug" to your hotplug.murasaki exectuable (usually /sbin/hotplug.murasaki), but you then lose the automatic initial setup. You may be able to get by like this, but you're on your own if you try it. To check and see if the murasaki service has been started, you can run cat /proc/sys/kernel/hotplug and see if the output is identical to the full path of your hotplug.murasaki executable. If it is, Murasaki will handle all requests for driver loading/unloading whenever an appropriate hot-plug device is connected or disconnected. You can now connect your favorite (supported) USB/FireWire device. When you plug it in, you should hear your PC speaker beep rather unobtrusively (unless you've disabled the beep somehow), and the device driver should be loaded automatically. Congratulations, you (probably) have a properly working Murasaki service. If you don't, well, you're more-or-less on your own. ;) ------------------------------------------------------------------------------ CHANGELOG: [2003-09-20] * Updated to expand details and * Rewrote to accommodate new hints format.