

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 USB agent uses modutils 2.4.2 style "usbmap" syntax files to
      configure drivers without kernel hotplug support, or devices without
      kernel drivers. Default "*map" files are included for old systems.

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 hotplug files with:

	# make install

      The files that are installed are:

	/sbin/hotplug       Policy agent, called by the kernel.
	/etc/hotplug        Agent scripts, called by the policy agent.
	/etc/hotplug.conf   Global configuration file .
	/etc/init.d/hotplug Init script for coldplugging.
 
 (3)  


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.  The hotplug scripts though
should work for cold plugging even without these programs installed but they
will take more time to run and you might experience problems.

"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 load the modules.  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 coldplug-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.  A solution to this is to add the
following lines to /etc/modules.conf:

    alias char-major-13 input
    above input evdev keybdev mousedev joydev

This way, all the input modules should get automatically loaded when the
"/dev/input" files are accessed (by the X server).


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/DRIVERNAME.usbmap 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 in place of
      modprobe:  /etc/hotplug/usb/DRIVERNAME.agent 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/DRIVERNAME.usbmap, again using the syntax of
      "modules.usbmap".
	
	  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
      an empty /etc/hotplug/usb/DRIVERNAME.agent file.

	  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, "depmod" 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.usbmap in order for it to hotplug.
