finit/doc/keventd.md

Bundled Device Manager

The kernel event daemon keventd is a built-in device manager bundled with Finit. It replaces the need for external device managers like mdev, mdevd, or udevd on systems where a lighter-weight solution is preferred, particularly on embedded systems.

It is enabled by default since Finit v5. To disable it and use an external device manager instead: ./configure --without-keventd

Features

When started, keventd listens on a NETLINK_KOBJECT_UEVENT socket for kernel events and handles:

• Device node creation: creates and removes /dev nodes with correct permissions on device add/remove events
• Persistent symlinks: creates /dev/disk/by-id/, /dev/disk/by-path/, and /dev/input/by-id/, /dev/input/by-path/ symlinks for stable device naming
• Firmware loading: responds to kernel firmware requests by searching /lib/firmware/ and writing firmware data to sysfs
• Module loading: parses MODALIAS from uevents and spawns modprobe to load the appropriate kernel module
• Coldplug: with the -c flag, walks /sys/devices and triggers add events for all devices present at boot
• Power supply monitoring: tracks AC power status and provides the sys/pwr/ac condition
• Device conditions: sets dev/* conditions in the Finit condition system when device nodes appear or disappear

Device Nodes

On receiving an add event with MAJOR, MINOR, and DEVNAME fields, keventd creates the corresponding device node in /dev using mknod(). Parent directories are created automatically (e.g., /dev/input/ for /dev/input/event0).

On remove events, the device node and its associated symlinks and conditions are cleaned up.

Default Permissions

keventd applies permissions based on built-in rules that match on device subsystem and name:

Subsystem	Pattern	Mode	Owner:Group
block	sd*, vd*, nvme*, mmcblk*, loop*, dm-, md	0660	root:disk
tty	tty[0-9]*	0620	root:tty
tty	ttyS*, ttyUSB*, ttyACM*	0660	root:dialout
input	event*, mouse*, mice	0660	root:root
sound	*	0660	root:audio
video4linux	*	0660	root:video
drm	card*, render*	0660	root:video
(any)	null, zero, full, random, urandom	0666	root:root
(any)	console	0600	root:root
(default)		0660	root:root

Persistent Symlinks

For block devices, keventd creates symlinks under /dev/disk/:

• by-id: based on the device serial number and model, read from sysfs attributes (/sys/.../device/vendor, model, serial)
• by-path: based on the device topology path

For input devices, symlinks are created under /dev/input/:

• by-id: based on the device name from sysfs
• by-path: based on the physical device path

These symlinks are tracked internally and automatically removed when the corresponding device is unplugged.

Firmware Loading

When a kernel driver requests firmware (via request_firmware()), the kernel sends a uevent with a FIRMWARE= field. keventd handles this by:

1. Searching for the firmware file in order:
   • /lib/firmware/updates/<kernel-version>/<name>
   • /lib/firmware/updates/<name>
   • /lib/firmware/<kernel-version>/<name>
   • /lib/firmware/<name>
2. Writing 1 to /sys/<devpath>/loading to signal start
3. Copying the firmware data to /sys/<devpath>/data
4. Writing 0 to /sys/<devpath>/loading on success (or -1 on failure)

This is particularly important early in boot when drivers for graphics cards, network adapters, and other hardware need firmware before they can operate.

Module Loading

When a device add event includes a MODALIAS field, keventd spawns modprobe -bq <modalias> to load the matching kernel module. Module loading is done asynchronously (keventd does not wait for modprobe to complete) to avoid blocking other event processing.

Coldplug

To handle devices that were present before keventd started, it supports a coldplug mode activated with the -c flag. This walks the entire /sys/devices tree and writes add to each uevent file, causing the kernel to re-emit add events for all existing devices.

This replaces the separate coldplug script previously used with mdev.

Conditions

keventd provides conditions in two namespaces:

Device Conditions (dev/)

When a device node is created, keventd asserts a corresponding condition in /run/finit/cond/dev/. This allows services to wait for specific devices:

service mdadm {
    description = "RAID monitor"
    runlevel    = "2345"
    conditions  = { "dev/sda" }
    command     = "/usr/sbin/mdadm --monitor /dev/md0"
}

service gps-daemon {
    description = "GPS daemon"
    runlevel    = "2345"
    conditions  = { "dev/ttyUSB0" }
    command     = "/usr/sbin/gps-daemon"
}

When the device is removed, the condition is cleared and Finit stops the dependent services.

Power Supply Conditions (sys/pwr/)

keventd monitors the power_supply subsystem and provides:

• sys/pwr/ac -- asserted when AC power is connected

This is useful for preventing power-hungry services from running on battery:

service cron {
    description = "Cron daemon"
    runlevel    = "2345"
    conditions  = { "sys/pwr/ac", "pid/syslogd" }
    command     = "cron -f"
}

Usage

keventd [-cdhnv]

Options:
  -c        Run coldplug at startup
  -d        Enable debug mode (foreground, verbose)
  -h        Show help text
  -n        Run in foreground (no daemon)
  -v        Show version

In normal operation, Finit starts keventd automatically via its system configuration. The -d flag is useful for debugging device issues -- it runs keventd in the foreground and logs all received uevents.

Debug logging can also be toggled at runtime by sending SIGUSR1:

kill -USR1 $(pidof keventd)

Integration with Finit

keventd is a standalone daemon started by Finit as an internal service. It communicates with Finit exclusively through the filesystem-based condition system -- creating and removing symlinks in /run/finit/cond/.

This means keventd can also be tested independently:

# Run in debug mode to see all kernel events
keventd -d

# Run with coldplug to populate /dev from scratch
keventd -c -n

When keventd is enabled, it conflicts with external device managers. Only one device manager should be active at a time. The system configuration uses the conflict: directive to enforce this:

service conflict:udevd,mdevd,mdev [...] keventd -c -- Finit device manager