$Id: README,v 1.2 2001/01/17 17:16:36 dbrownell Exp $

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.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.
Be sure you apply the hotplug patch associated with modutils 2.4.1
(else USB hotplugging won't work).

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

PCI agent code (for Cardbus, Compact PCI, Hotplug PCI) 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 shell.

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

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

	# mkdir -p /etc/hotplug
	# cp etc/hotplug/* /etc/hotplug
 
 (4)  Make your system start hotplugging after it's booted and
      filesystems are mounted.  On RedHat systems:

	# cp etc/rc.d/init.d/hotplug /etc/rc.d/init.d/hotplug

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 statically link 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.

Revisions of the "etc/hotplug/*.agent" script will likely address this
issue.  Until then, workarounds are known at least for USB.  If you can
make USB be fully modular, use it that way; it'll start cleanly.
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!

