From 120c8e6002bee85aa1dc8952ae6979b5dad1edd9 Mon Sep 17 00:00:00 2001 From: Joachim Wiberg Date: Thu, 29 Jan 2026 12:32:35 +0100 Subject: [PATCH] man: add fine manual for keventd(8) Signed-off-by: Joachim Wiberg --- man/Makefile.am | 4 + man/keventd.8 | 231 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 235 insertions(+) create mode 100644 man/keventd.8 diff --git a/man/Makefile.am b/man/Makefile.am index 0be59995..078e13cd 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -1,2 +1,6 @@ dist_man8_MANS = finit.8 initctl.8 dist_man5_MANS = finit.conf.5 + +if KEVENTD +dist_man8_MANS += keventd.8 +endif diff --git a/man/keventd.8 b/man/keventd.8 new file mode 100644 index 00000000..90d5b983 --- /dev/null +++ b/man/keventd.8 @@ -0,0 +1,231 @@ +.\" Hey, EMACS: -*- nroff -*- +.\" First parameter, NAME, should be all caps +.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection +.\" other parameters are allowed: see man(7), man(1) +.Dd Jan 29, 2026 +.\" Please adjust this date whenever revising the manpage. +.Dt KEVENTD 8 SMM +.Os Linux +.Sh NAME +.Nm keventd +.Nd Finit device manager daemon +.Sh SYNOPSIS +.Nm +.Op Fl c +.Op Fl d +.Op Fl h +.Op Fl n +.Op Fl v +.Sh DESCRIPTION +.Nm +is a built-in device manager bundled with +.Xr finit 8 . +It listens for kernel uevents on a +.Dv NETLINK_KOBJECT_UEVENT +socket and handles device node creation, persistent symlinks, firmware +loading, kernel module loading, and condition management. +.Pp +It replaces the need for external device managers like +.Nm mdev , +.Nm mdevd , +or +.Nm udevd +on systems where a lighter-weight solution is preferred, particularly +on embedded systems. +.Sh OPTIONS +.Bl -tag -width Ds +.It Fl c +Run coldplug at startup. Walks the +.Pa /sys/devices +tree and writes +.Cm add +to each +.Pa uevent +file, causing the kernel to re-emit add events for all devices already +present. This populates +.Pa /dev +with nodes for hardware that existed before +.Nm +started. +.It Fl d +Enable debug mode. Implies +.Fl n . +All received uevents are logged to stderr. +.It Fl h +Show help text and exit. +.It Fl n +Run in foreground, do not daemonize. Log messages are written to +stderr instead of syslog. +.It Fl v +Show version and exit. +.El +.Sh DEVICE NODES +On receiving an +.Cm add +event with +.Cm MAJOR , +.Cm MINOR , +and +.Cm DEVNAME +fields, +.Nm +creates the device node in +.Pa /dev +using +.Xr mknod 2 . +Parent directories are created as needed, e.g.\& +.Pa /dev/input/ +for +.Pa /dev/input/event0 . +.Pp +On +.Cm remove +events the device node and its associated symlinks are cleaned up. +.Pp +Permissions are assigned based on built-in rules matching on device +subsystem and name. For example, block devices default to mode 0660 +owned by root:disk, TTY devices to root:tty, and common devices like +.Pa /dev/null +and +.Pa /dev/zero +are world-readable (0666). +.Sh PERSISTENT SYMLINKS +For block devices, +.Nm +creates symlinks in +.Pa /dev/disk/ : +.Bl -tag -width by-path -offset indent -compact +.It Pa by-id +Based on device serial number and model, read from sysfs. +.It Pa by-path +Based on the device topology path. +.El +.Pp +For input devices, symlinks are created in +.Pa /dev/input/ : +.Bl -tag -width by-path -offset indent -compact +.It Pa by-id +Based on the device name from sysfs. +.It Pa by-path +Based on the physical device path. +.El +.Pp +Symlinks are tracked internally and automatically removed when the +device is unplugged. +.Sh FIRMWARE LOADING +When a kernel driver requests firmware via +.Fn request_firmware , +the kernel emits a uevent with a +.Cm FIRMWARE +field. +.Nm +handles this by searching for the firmware file in the following order: +.Pp +.Bl -enum -compact -offset indent +.It +.Pa /lib/firmware/updates// +.It +.Pa /lib/firmware/updates/ +.It +.Pa /lib/firmware// +.It +.Pa /lib/firmware/ +.El +.Pp +The firmware is loaded by writing to the device's sysfs +.Pa loading +and +.Pa data +attributes. +.Sh MODULE LOADING +When a device add event includes a +.Cm MODALIAS +field, +.Nm +spawns +.Cm modprobe -bq +to load the matching kernel module. Module loading is asynchronous +to avoid blocking event processing. +.Sh CONDITIONS +.Nm +provides conditions for Finit's dependency system by creating and +removing symlinks in +.Pa /run/finit/cond/ . +.Ss Device Conditions +When a device node is created, +.Nm +asserts a corresponding +.Cm dev/ +condition. For example, creating +.Pa /dev/sda +asserts +.Cm dev/sda . +This allows services to depend on specific devices: +.Bd -literal -offset indent +service mdadm { + description = "RAID monitor" + runlevel = "2345" + conditions = { "dev/sda" } + command = "/usr/sbin/mdadm" +} + +service gpsd { + description = "GPS daemon" + runlevel = "2345" + conditions = { "dev/ttyUSB0" } + command = "/usr/sbin/gpsd" +} +.Ed +.Pp +When the device is removed, the condition is cleared and Finit stops +the dependent services. +.Ss Power Supply Conditions +.Nm +monitors the +.Cm power_supply +subsystem and provides: +.Bl -tag -width sys/pwr/ac -offset indent -compact +.It Cm sys/pwr/ac +Asserted when AC power is connected. +.El +.Pp +Useful for preventing power-hungry services from running on battery: +.Bd -literal -offset indent +service cron { + description = "Cron daemon" + runlevel = "2345" + conditions = { "sys/pwr/ac" } + command = "cron -f" +} +.Ed +.Sh SIGNALS +.Bl -tag -width SIGUSR1 +.It Dv SIGUSR1 +Toggle debug logging at runtime. +.It Dv SIGTERM +Graceful shutdown. +.El +.Sh FILES +.Bl -tag -width /run/finit/cond/dev/ -compact +.It Pa /dev/ +Device nodes managed by +.Nm . +.It Pa /dev/disk/by-id/ , Pa /dev/disk/by-path/ +Persistent block device symlinks. +.It Pa /dev/input/by-id/ , Pa /dev/input/by-path/ +Persistent input device symlinks. +.It Pa /lib/firmware/ +Firmware search path. +.It Pa /run/finit/cond/dev/ +Device condition symlinks. +.It Pa /run/finit/cond/sys/pwr/ +Power supply condition symlinks. +.El +.Sh SEE ALSO +.Xr finit 8 , +.Xr finit.conf 5 , +.Xr initctl 8 , +.Xr mknod 2 , +.Xr modprobe 8 +.Sh AUTHORS +.An Joachim Wiberg Aq Mt troglobit@gmail.com