WHAT DO WE HAVE HERE?
---------------------
Hotplugging scripts, USB focussed, 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 a kernel patch associated with modutils 2.4.1;

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.org/

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



NOTES ABOUT THIS VERSION
------------------------
This is a MAJOR REVISION.  Changes include:

    - The /sbin/hotplug script isn't a "reference" version with builtin
      support for USB, PCI, and NET hotplugging.  It always delegates to
      /etc/hotplug/* agent files.
    
    - Removing the  /etc/usb directory and contents, even for systems
      using 2.2.18 (and later) kernels.  The Linux direction is clear:
      hotplugging won't be USB-specific!
    
    - Splitting out the USB, PCI, and NET policy agents into their own
      files so they can be individually replaced or augmented with support
      for hotplugging other kernel subsystems. 
    
    - The USB agent uses modutils 2.4.1 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.

Don't use this version with 2.4.0 test or prerelease kernels; and be
sure you apply the hotplug patch associated with modutils 2.4.1 (else
USB hotplugging won't work).

Cardbus/PCI agent code isn't currently included.


INSTALLING
----------
For all hotplug-enabled 2.2 and 2.4 kernels, preferably using a fully
modular USB configuration:

 (1)  Extract into /etc/hotplug

 (2)  Install the "hotplug" script:

	# cp hotplug /sbin/hotplug
	# chmod a+x /sbin/hotplug
 
 (3)  If your OS distribution doesn't support USB, or if you want to
      be able to bring USB up and down, modify your boot sequence so
      that sometime after filesystems are mounted, it invokes:

	# Set up USB
	if [ -x /etc/hotplug/usb.rc ]; then
	    action "Starting USB" /etc/hotplug/usb.rc start
	fi

      On RedHat systems, that goes nicely in /etc/rc.d/rc.sysinit
      (optionally replacing what Redhat 7 includes).  One Debian
      user reports the end of /etc/init.d/mountall is the spot.

If you installed earlier versions, your init scripts should change;
step (3) uses /etc/hotplug/usb.rc instead of /etc/usb/rc.usb ... older
"rc.usb" scripts should still work, but hotplug scripts currently won't.

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.


HOTPLUGGING AT BOOT TIME
------------------------
If you use non-modular USB host controller drivers (or Cardbus bridges,
or network interfaces) then devices connected at boot time won't get
properly configured through hotplugging ... it can't work until the files
it relies on become available, relatively late in system booting.

Workarounds are known for USB.  If you can make USB be fully modular,
use it that way; it'll start cleanly from the /etc/hotplug/usb.rc script;
Otherwise, (re)plug in USB or PCI devices after the system has booted.


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 using a USB keyboard, you should probably have compiled "hid",
"keybdev", "input", the usb core, and an appropriate USB host controller
statically into your kernel.  (For USB mice, "mousedev" not "keybdev".)


RUNNING WITHOUT 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.


SPECIALIZED USB DEVICE 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 use 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.
    
    - 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.
    
    - 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.

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.distmap in order for it to hotplug.

NOTE:  Don't put any blank lines or comments into those "usbmap" syntax
files, except for one on the very first line.  At least, not yet!

