The wikis are now using the new authentication system.
If you did not migrate your account yet, visit https://idp-portal-info.suse.com/

SDB:SUSE Linux Hotplug System Overview

Şuraya atla: kullan, ara


SUSE Linux Hotplug System Overview

The SUSE Linux Hotplug System is derived from the Linux Hotplug Project, but behaves somewhat differently. The main difference is that the event multiplexer (/etc/hotplug.d/) is not used to initialize and stop devices. /sbin/hw{up,down} is used instead. This document describes the differences between the two methods and the complete SUSE Linux Hotplug System.

HOW IT WORKS

Hotplug Always Used

The hotplug system is not only used for devices that can be plugged or unplugged at runtime, but for all devices detected after the kernel has booted. This means that before hotplug or coldplug is started, only basic devices are initialized, such as the main bus system (mostly PCI), boot disks, and keyboard. All devices handled by hotplug have an entry in sysfs.

Devices and Interfaces

Hotplug handles both devices and interfaces. In this document, we distinguish between devices and interfaces to devices. A device is that part that is connected to any kind of bus or interface. An interface is what is provided by this device for connecting another device or an application. In sysfs, devices can be found in /sys/devices. Interfaces are listed in /sys/class or /sys/block. All interfaces should have a link to their devices in sysfs, but there are still some drivers that do not add a link.
Examples:

  • A PCI network card is a device connected to the PCI bus. (/sys/devices/pci0000:00/0000:00:1e.0/0000:02:00.0). This device provides a network interface that is used by network services or where virtual network devices (for example, a tunnel or VLAN) are connected (/sys/class/net/eth0).
  • A PCI SCSI controller is a device (/sys/devices/pci0000:20/0000:20:01.1) that provides several physical interfaces in the form of a bus (/sys/class/scsi_host/host1).
  • A SCSI disk is a device (/sys/devices/pci0000:20/0000:20:01.1/host1/1:0:0:0) with multiple interfaces (/sys/block/sda*)

Hotplug Events

All other devices and interfaces are initialized via hotplug. There is a hotplug event for each device or interface that is handled by the appropriate hotplug agent. Hotplug device events are triggered in two different ways:

  • By the kernel when the connection to a device is established. Again, there are two cases:
    • The bus or interface where the device is connected is already active and the device is plugged physically (USB, PCMCIA, sometimes PCI, etc.). The bus driver generates an event for each plugged device.
    • The device was already physically connected, but the underlying bus or interface was not initialized. When the bus is initialized, the bus driver scans the bus for all connected devices and generates an event for each device.
  • By coldplug, which rescans important buses and generates events for all devices that are still not initialized.

Additionally, there are interface events that are triggered by the kernel as soon as a driver registers an interface.

To generate a hotplug event means that a hotplug usermode tool is run, usually /sbin/hotplug. The kernel calls whatever is written to /proc/sys/kernel/hotplug. The usermode tool /sbin/hotplug looks for a hotplug agent matching the type of the event. If there is no agent for that event type and there is a file 'dev' in the device path, it calls generic_udev.agent.

If certain types of events should always be skipped, set them as HOTPLUG_SKIP_EVENTS in /etc/sysconfig/hotplug.

Hotplug Agents

Starting with the 2.6 kernel, there are so many different hotplug events that it is difficult to know them all. Every new driver may introduce a new event type. For all well known events, there are dedicated agents that execute the necessary actions.

Device agents mainly load kernel modules, but sometimes some extra commands may need to be called. For some hardware architectures, such as the IBM S390, each device must be enabled by writing special values somewhere in procfs or sysfs. SUSE Linux hotplug always calls /sbin/hw{up,down} to manage these jobs. It looks in /etc/sysconfig/hardware for a configuration that matches the device and uses that information. If hwup does not find a configuration, it falls back to automatic module loading. See "Automatic Module Loading" below. For details about hw{up,down}, refer to /usr/share/doc/packages/sysconfig/README and 'man hwup'. In future releases, old style automatic module loading will be skipped completely and hwup will trigger a configuration process if no configuration file is found.

Interface agents mainly have two jobs: setting up an interface and calling udev to create a device node. Setting up interfaces is done by /sbin/if{up,down}, which is currently only used for network interfaces. See the sysconfig document at /usr/share/doc/packages/sysconfig/README and 'man ifup' for details about if{up,down}. Also, udev has its own documentation and man pages.

If there is no agent for a certain event and the device path in sysfs for the interface contains a 'dev' file, a generic udev agent is called to make sure all needed device nodes are created.

Automatic Module Loading

All agents that must initialize devices try to find a driver module for the device if hwup failed. To do this, they process some module maps. All agents look first in a /etc/hotplug/*.handmap file and only if there was no hit do they look in /lib/modules/<kernelversion>/modules.*map. Therefore, if the default from the kernel's map does not fit your needs, enter an appropriate line in the handmap.

There are two extra rules for PCI and USB:

  • USB: The usb.agent also looks in /etc/hotplug/usb.usermap and /etc/hotplug/usb/*.usermap for usermode drivers. This means that executables for certain devices may be started.
  • PCI: The pci.agent first asks hwinfo for driver modules and only looks in the maps if hwinfo does not return a driver. Since hwinfo looks in pci.handmap and the kernel map this should normally not be needed. hwinfo has an additional database used after pci.handmap but before the kernel map.

Additionally, the pci.agent may be limited to loading only modules that are in certain subdirectories of /lib/modules/<kernelversion>/kernel/drivers. If there is at least one subdirectory name in HOTPLUG_PCI_DRIVERTYPE_WHITELIST, only modules from those subdirectories are loaded. Modules from subdirectories listed in HOTPLUG_PCI_DRIVERTYPE_BLACKLIST are never loaded.

Finally, there is /etc/hotplug/blacklist. This file contains one module name per line that should never be loaded by any agent.

If there are multiple modules matching in one map, loading stops after one module has been successfully loaded. Normally these extra modules are just alternative drivers. To have hotplug load all matching modules, set HOTPLUG_LOAD_MULTIPLE_MODULES=yes.

Remember that this does not affect module loading via hwup. Automatic module loading is just a fall back mechanism that will be dropped soon.

Network Devices and Their Interface Names

If there are multiple network devices that have different drivers, it could happen that interface names for these devices switch randomly at every boot. This is because hotplug events are handled asynchronously and therefore two drivers initialize their devices in parallel. This means that there may be a race between these processes.

To avoid this problem, network device events are queued. If this seems to be problematic for any reason, it can be switched off in /etc/sysconfig/hotplug with HOTPLUG_PCI_QUEUE_NIC_EVENTS=no.

The recommended way to achieve persistent interface names is to set dedicated interface names in the interface configuration files. Then queueing of events is no longer necessary. See the section about persistent names in /usr/share/doc/packages/sysconfig/README.

PCI Hotplugging

Some computers allow hotplugging of PCI devices. For proper PCI hotplugging, special kernel modules are loaded. These may harm non-PCI hotplug machines. Because hotplug PCI slots cannot be autodetected, this feature must be enabled manually by setting HOTPLUG_DO_REAL_PCI_HOTPLUG in /etc/sysconfig/hotplug.

Coldplug

Coldplug is concerned with devices that were plugged before the hotplug system became active. This is always the case at boot time. Coldplug is also concerned with devices that are not easily detected.

At first, coldplug calls hwup for each static hardware configuration in /etc/sysconfig/hardware (hwcfg-static-*). This way, old or exotic hardware may be initialized. This may also help to initialize devices in a certain order.

The /etc/hotplug/*.rc scripts scan for devices that are still not initialized and generate hotplug events for these devices. For PCI devices, there is a whitelist and a blacklist of device types that should be handled or skipped. These lists are described in the comments in /etc/sysconfig/hotplug.

The *.rc scripts print a character for each scanned device:

  • . device is already initialized and therefore skipped
  • * generate a hotplug event for this device
  • W the device is not in the whitelist and therefore skipped
  • B the device is in the blacklist and therefore skipped

CONFIGURING

/etc/sysconfig/hotplug

There is a set of variables in this file for changing the behavior of hotplug and coldplug. There are comments in this file that explain the impact of these variables.

/proc/sys/kernel/hotplug

This contains the name of the executable called by the kernel.

Boot Parameters

These are some parameters that may be set at the boot prompt:

  • NOHOTPLUG=yes If set to yes, hotplug events are not handled until 'rchotplug start' is called manually.
  • NOCOLDPLUG=yes If set to yes, coldplug is skipped.
  • HOTPLUG_TRACE=<N> If set, hotplug print sthe name of the module it is going to load to the console then waits N seconds.

DEBUGGING

Logging

With the default settings, hotplug only writes important messages to syslog. For more details of what is done by hotplug, set HOTPLUG_DEBUG=yes. If a bug is suspected in any of the scripts, HOTPLUG_DEBUG=max can be set. Then every shell command from these scripts is logged, resulting in extremely numerous lines in the log file.

By default, the hotplug system uses syslog. In other words, find all messages in /var/log/messages. However, when booting, syslog is started after hotplug and coldplug and a lot of messages are lost. Therefore, you may set HOTPLUG_SYSLOG to another value. Refer to the comments in /etc/sysconfig/hotplug for more information.

Boot Problems

If the machine hangs at boot time, it is possible to switch off hotplug (NOHOTPLUG=yes) and coldplug (NOCOLDPLUG=yes) at the boot prompt. NOHOTPLUG prevents hotplug from calling an agent no matter where the event comes from, but static hardware configurations (hwcfg-static-*) are still applied from coldplug. If hotplug is manually started later (not via runlevel switch), NOHOTPLUG is ignored. NOCOLDPLUG skips coldplug at boot time, meaning no device scan occurs and static hardware configurations are not applied, but that hotplug is still working.

If a module that hotplug loaded is the culprit, watch hotplug by setting HOTPLUG_TRACE=<N> at the boot prompt. Hotplug then writes the name of the module to load to the console and waits for N seconds before loading the module. There is no interactive mode.

The Event Recorder

There is a /sbin/hotplugeventrecorder program, which is always called by /sbin/hotplug and /sbin/hotplug-stopped. If a /events directory exists, all hotplug events are stored there in individual files. <keyword>coldplug,hotplug,usb,pci,hardware,scan,boot,ifdown,ifup,hwup,hwdown,sysfs</keyword>