ROCK-Plug ROCK-Plug aims to replace the original hotplug package and the current hardware detection technology of ROCK Linux, called hwscan. It is designed with the KISS principle in mind, fitting in the existing ROCK Linux framework (although we have to admit, that the task by definition is not really compatible with KISS). It features both scanning cold-plugged devices (present during bootup) and real hotplug events generated for devices plugged into a running system. Contents ======== 1. Licence 2. Configuration 2.1 System init 2.2 Sub-systems 2.2.1 PCI 2.2.2 ISAPNP 2.2.3 PCMCIA 2.2.4 USB 2.2.5 MACIO 2.2.6 IEEE1394 2.2.7 NET 2.2.8 SCSI 2.3 Scripts 3. Developer info 3.1 Overview of linux kernel interaction 3.1.1 Cardbus/PCI subsystem 3.1.2 USB subsystem 3.1.3 IEEE1394 3.1.4 NET 3.1.5 SCSI ============================================================================= 1. Licence ============================================================================= NOTE: Parts of the hotplugging code resp. ideas are taken from hotplug originally written by Greg K-H (available at https://sourceforge.net/projects/linux-hotplug/). The files did not contain explicit copyright statements, however its README file state its release is covered by the GPL. Copyright (C) 2003 Juergen "George" Sawinski Rene Rebe All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111, USA. ============================================================================= 2. Overview ============================================================================= Note: Some of the features described in the following document may not be implemented yet. See additional information in the TODO file. ROCK-Plug is intergrating hardware detection and hotplugging capabilities for the Linux kernel. ROCK-Plug does it's job in two stages, the first stage (system init) is done as long as the root file system is read-only. The second step, which is the actual hardware detection mechanism, requires write access. The second step consists of the following initialisation steps: -PCI/CardBus -ISAPNP -PCMCIA -USB -IEEE1394 (FireWire) -MACIO (MAC specific modules) Furthermore, hotplugging is supported by the kernel for the following sub-systems: -PCI -USB -NET -IEEE1394 -SCSI (kernel 2.5 and above only) ============================================================================= 2. Configuration ============================================================================= This section is arranged in three sections. First, we deal with the system or early hardware init (modules that should be loaded prior to any hardware detection and before filesystems are mounted read-write). Second, the configuration of each sub-system and third scripts, that may be called class or vendor/device or module specific. User resp. administrator configurable variables have generally the form ${PREFIX}_MODULES for modules, that are loaded on system initialization and ${PREFIX}_SKIP_MODULES for modules, that are generally skipped. Other variables may also be set depending on the sub-system (the repective prefixes in lower-case: pci, isapnp, pcmcia, usb, net, ieee1394, macio, scsi). All variables are a list of space-sperated modules unless otherwise noted. [...note about modules given in *_MODULES are probed in given order, relevant e.g for USB_HC[DI]...] ------------------------------------------------------- 2.1 System init ------------------------------------------------------- The system resp. "early hardware" init takes place before the file-system is mounted read-write. At this stage, no hardware detection is done at all. Configuration file: /etc/conf/hardware (@FIXME okay?) Variables: SYSINIT_MODULES ------------------------------------------------------- 2.2 Sub-systems ------------------------------------------------------- 2.2.1 PCI/CardBus PCI and CardBus (not PCMCIA!) are detected on boot and the kernel issues hotplug events (see 3.1.1). Configuration file: /etc/conf/pci: Variables: PCI_MODULES PCI_SKIP_MODULES Configuration file: /etc/conf/sound SOUND_SYSTEM either "OSS" or "ALSA" It should be noted, the usb drivers are currently skipped in the PCI detection due to the diversity of host controller interfaces resp. drivers (see 2.2.4). Here, we followed exactly the 2002 hotplug implementation and will keep it until the authors get aware of hotpluggable USB cards. 2.2.2 ISAPNP [Note: the auto-detection is currently not implemented] Configuration: /etc/conf/isapnp Variables: ISAPNP_MODULES ISAPNP_SKIP_MODULES 2.2.3 PCMCIA [... not implemented yet ...] 2.2.4 USB USB devices and hubs are detected on boot and the kernel issues hotplug events (see 3.1.1). Configuration file: /etc/conf/usb: Variables: USB_HCD module list of host controller drivers possible drivers are: ehci-hcd ohci-hcd uhci-hcd USB_HCI set this to the preferred host controller interface, possible drivers are: usb-ohci usb-uhci uhci USB_MODULES USB_SKIP_MODULES Note: For X11-3.3.6, add "mousedev" and "input" to the USB_MODULES list. 2.2.5 MACIO Configuration file: /etc/conf/macio Variables: MACIO_MODULES 2.2.6 IEEE1394 Configuration file: /etc/conf/ieee1394 Variables: IEEE1394_MODULES IEEE1394_SKIP_MODULES 2.2.7 NET Networking is highly administration dependant and therefore no configuration is done in the hotplug and hardware detection context. 2.2.8 SCSI Configuration file: /etc/conf/scsi Variables: SCSI_MODULES SCSI_SKIP_MODULES ------------------------------------------------------- 2.3 Scripts and usermaps ------------------------------------------------------- [... conf/{pci,usb,...}.usermap -> user scripts ...] =========================================================================== 3. Developer info ============================================================================= ------------------------------------------------------- 3.1 Overview of linux kernel interaction ------------------------------------------------------- On a hotplug event, the kernel executes /sbin/rockplug (the executable can be set via /proc/sys/kernel/hotplug) with pci,usb,ieee1394,net or scsi as argument and passes all relevant information via environment variables. The hotplug script then calls the respective plugger script. 3.1.1 Cardbus/PCI subsystem Parameters passed on a "pci" hotplug event: ACTION=%s [add|remove] PCI_CLASS=%06X PCI_ID=%04X:%04X PCI_SLOT_NAME=%s PCI_SUBSYS_ID=%04X:%04X If /proc is mounted, /proc/bus/pci/$PCI_SLOT_NAME is almost the name of the binary device descriptor file ... just change ':' to '/'. 3.1.2 USB subsystem Parameters passed on a "usb" hotplug event: ACTION=%s [add|remove] PRODUCT=%x/%x/%x INTERFACE=%d/%d/%d TYPE=%d/%d/%d And if usbfs (originally called usbdevfs) is configured, also: DEVFS=/proc/bus/usb DEVICE=/proc/bus/usb/%03d/%03d 3.1.3 IEEE1394 Parameters passed on a "ieee1394" hotplug event: ACTION=%s [add|remove] VENDOR_ID=%x (24 bit vendor id) GUID=%x (64 bit globally unique id) SPEFICIER_ID=%x (24 bit id of owner of specification) VERSION=%x (version of specification) See IEEE1212 for details on these parameters. 3.1.4 NET Parameters passed on a "net" hotplug event: ACTION=%s [add|remove] INTERFACE=%s (interface name, eg. eth0) 3.1.5 SCSI The "scsi" hotplug event was introduced in the 2.5 kernel series. Parameters passed on a "scsi" hotplug event: ACTION=add DEVPATH=%s (format: devices/scsi0/0:0:0:0) ------------------------------------------------------- 3.2 Implementations ------------------------------------------------------- 3.2.1 /sbin/rockplug 3.2.2 /sbin/rockscan 3.2.3 /etc/rockplug/functions 3.2.4 /etc/rockplug/{pci,usb,[...]}.{config,functions,init,plug}