$Id: README,v 1.6 2001/06/08 21:55:08 stevewilliams Exp $

WHAT DO WE HAVE HERE?
---------------------
Hotplugging scripts that should work on 2.2 and 2.4 kernels.

This particular version won't work on test versions of the 2.4 kernels,
and (NOTE!) needs modutils 2.4.2 or later; for your two letter country
code (cz, jp, tw, us, etc) use this FTP site:

    ftp://ftp.COUNTRY.kernel.org/pub/linux/utils/kernel/modutils/v2.4/

Linux kernel hotplugging support relies on kernels to be configured with
HOTPLUG; and, for loading modular drivers, KMOD.  Configure USB, NET, and
PCI (for Cardbus support) as appropriate for your environment.

For more information about Linux hotplugging:

    http://linux-hotplug.sourceforge.net/

These tools are are GPL'd, and are available at the web site above.



NOTES ABOUT THIS VERSION
------------------------
This version does not support 2.4.0 test or prerelease kernels.

    - Most of the functionality is in /etc/hotplug/* files.
      Read the scripts to see how they work.

    - You're expected to know how to hook up a boot script on
      your distribution.  The /etc/rc.d/init.d/hotplug script
      should behave on RedHat style systems, although Redhat 7.1
      handles some of these issues differently:  it uses an
      older snapshot of the hotplug scripts.
    
    - The USB agent uses modutils 2.4.2 style "usbmap" syntax files to
      configure drivers without kernel hotplug support, or devices without
      kernel drivers.  "/etc/usb/drivers/*" scripts are gone, and systems
      based on kernel 2.2 just use their own "usbmap" file rather than
      expecting "modutils" to create one.

PCI agent code (for Cardbus, Compact PCI, Hotplug PCI, and even
for devices that are only "cold" plugged) is included.


INSTALLING
----------
For all hotplug-enabled 2.2 and 2.4 kernels, try to use a fully
modular USB configuration.

 (1)  Extract everything into a temporary directory, and make
      that be the working directory for your root shell.

 (2)  Install the "/sbin/hotplug" script:

	# cp sbin/hotplug /sbin/hotplug
 
 (3)  Populate the "/etc/hotplug" directory:

	# mkdir -p /etc/hotplug
	# cp -r etc/hotplug/* /etc/hotplug

 (4)  Make the directory in /var/run for use remove support:

	# mkdir -p /var/run/usb
	# chmod 700 /var/run/usb

 (5)  Make your system start hotplugging (and maybe coldplugging,
      if you installed the right usb and pci utilities) after it's
      booted and filesystems are mounted.  On RedHat systems:

	# cp etc/rc.d/init.d/hotplug /etc/rc.d/init.d/hotplug
	# cd /etc/rc.d/init.d
	# chkconfig --add hotplug

These scripts aren't intentionally specific to RedHat; let us know if
we accidentally create a problem.  At some point, these may become
dependent on BASH version 2; older distributions of the hotplug scripts
will still be available.  (RedHat 6.2 is one of the distributions with
older versions.)

On Kernel 2.4 based systems, you may want to avoid installing the separate
"pcmcia_cs" package.  It's not integrated with kernel hotplugging, and
appears not to handle Cardbus as well as needed.  On the other hand, if
you need to use PCMCIA (16 bit) cards, you'll likely need it.

There are updates to the "usbutils-0.7" package to incorporate a new
"usbmodules" command, and to "pciutils-2.1.8" to incorporate a similar
"pcimodules".  See the website above for more information, or search
the web (list, rpmfind) for RPM or APT support.  Those programs help
support "cold plugging".


"COLD" PLUGGING AT BOOT TIME
----------------------------
Initializing devices that are present at boot time is easy to handle if
you install the "usbmodules" or "pcimodules" commands, and package most
kernel components (such as "usbcore") as dynamically linked modules.
(RedHat 7.1 handles this problem using "Kudzu" instead, which works more
selectively than "pcimodules".)

"Cold" plugging is different from hotplugging in that it happens while
the system is still warming up ("booting").  That means module loading
may not yet be possible when devices are first detected ... so these
scripts may need to scan the busses later, and synthesise hotplug events
to force the modules to load.  This is a particular issue for drivers
that are statically linked into the system kernel (perhaps so that they
can be used during system booting in some configuration).

If coldplugging isn't working for you (some device present at boot
time isn't properly set up), first try to unplug it and replug it.
If that works (you hotplugged it) it was a coldboot-only problem.


USB MICE AND KEYBOARDS
----------------------
If you need to use a USB mouse with X11, the X server needs to be able to
open "/dev/input/mice".  That means you can't hotplug a mouse you plan
to use with X11; it needs some modules preloaded.  If you haven't compiled
them into your kernel, try putting this line into /etc/sysconfig/usb:

    X11_USBMICE_HACK=true

If you're booting with a USB keyboard and/or mouse, and want to defend
against boot failures like missing modules, you should probably use
static linking for the "hid", "keybdev" (and/or "mousedev"), "input",
"usbcore", and USB Host Controller modules. 


RUNNING WITHOUT USB HOTPLUGGING
-------------------------------
If you are going to use USB but don't want to use USB Hotplugging, you
can change how the rc.usb and policy scripts act.  You may also prevent
all hotplugging with the kernel CONFIG_HOTPLUG option, or by putting an
empty pathname in /proc/sys/kernel/hotplug.

Just provide an /etc/sysconfig/usb file looking something like this:

    USBD_ENABLE=false
    STATIC_MODULE_LIST="audio keybdev hid"

That configuration will preload the USB audio and keyboard support,
if you've set up /etc/hotplug/usb.rc to run during system bootstrap.

(So far there's no corresponding control for PCI hotplugging, or for
pcmcia_cs integration.  Current revisions of the pcmcia_cs package
will however ignore all drivers listed in "modules.pcimap", so they
get safely handled by hotplugging rather than "cardmgr".)


SPECIALIZED USB DEVICE OR DRIVER SUPPORT
----------------------------------------
Devices often need specialized support, and this package is intended to
support that in the same way for both 2.2 and 2.4 based systems.  The
idea is that applications should be able to rely on the administrative
conventions established by this package.

Some of the mechanisms available are:

    - For kernel drivers that don't have MODULE_DEVICE_TABLE hotplug
      support add entries to /etc/hotplug/usb.handmap using the syntax
      of /lib/modules/`uname -r`/modules.usbmap

	  EXAMPLE:  With the 2.4.0 kernel, most HID devices (joysticks,
	  tablets, etc) need such support.  Until 2.4.1, so did the
	  usb-storage devices.
    
    - Drivers may provide a per-device setup script that's invoked after
      they modprobe:  /etc/hotplug/usb/MODULENAME is called.

	  EXAMPLE:  When you connect your USB PDA, you might want to
	  automatically start its hotsync daemon.  (visor)
    
    - For usermode drivers (using /proc/bus/usb/BBB/DDD files), you can
      add entries to /etc/hotplug/usb.usermap, again using the syntax of
      "modules.usbmap".  The "module name" will just identify a setup
      script (as above); it's not modprobed.
	
	  EXAMPLE:  This has been done with Rio MP3 players and with
	  digital cameras supported by gPhoto2; a "chmod" can enforce
	  more granular security policies than "usbdevfs" mount options.
    
    - Sometimes several kernel drivers may be able to handle a given
      device, and you don't want some drivers to be automatically loaded.
      (Only the first one will really hotplug, usually in alphabetical
      order.)  Just add those driver names to /etc/hotplug/blacklist
      and they won't be modprobed by these scripts.

	  EXAMPLE:  uhci and usb-uhci; the many variants of tulip; and
	  sometimes other vendor or development versions of drivers.

If you add a new hotpluggable module to a 2.4 based system, "modutils"
will make it automatically hotplug (using MODULE_DEVICE_TABLE).  For 2.2
based systems, without such modutils support, you should add the device
to /etc/hotplug/usb.handmap in order for it to hotplug.
