mirror of
https://github.com/troglobit/finit.git
synced 2026-10-09 16:50:59 +07:00
Joachim Wiberg
292e87c0d1
The udev parity gaps that were blocked on IPC -- settle, trigger,
info, queue introspection, runtime rule reload -- become bus methods.
keventd serves its own socket the way Finit serves /run/finit/bus:
brokerless, libink, one socket per daemon, no forwarding between the
two.
Settle(u) -> b parked until the queue drains or the timeout
passes; true when settled
Trigger(s, s) replay events, action + subsystem glob
Info(s) -> a{ss} /run/udev/data properties for a devpath
RulesReload() -> u re-read rules dirs, returns rule count
QueueEmpty (b), SeqnumProcessed (t) properties
DeviceProcessed (ss) signal after each fully handled event
The queue state is the highest kernel seqnum keventd has handled,
baselined at startup, against /sys/kernel/uevent_seqnum. keventd -S
now asks the running daemon first and falls back to seqnum polling.
In passive mode Trigger and RulesReload refuse. Adds
link_call_connection() for the park bookkeeping.
Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
315 lines
7.5 KiB
Plaintext
315 lines
7.5 KiB
Plaintext
.\" 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 g Ar group
|
|
.Op Fl G
|
|
.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 g Ar group
|
|
Override the netlink multicast group mask used for uevent rebroadcast.
|
|
The default is 4 (group 0x4), which is the
|
|
.Sy libudev-zero
|
|
convention.
|
|
Bit 0 is always masked out to prevent a feedback loop with the kernel
|
|
group.
|
|
See
|
|
.Sx NETLINK REBROADCAST
|
|
below.
|
|
.It Fl G
|
|
Disable netlink uevent rebroadcast entirely.
|
|
See
|
|
.Sx NETLINK REBROADCAST
|
|
below.
|
|
.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/<kernel-version>/<name>
|
|
.It
|
|
.Pa /lib/firmware/updates/<name>
|
|
.It
|
|
.Pa /lib/firmware/<kernel-version>/<name>
|
|
.It
|
|
.Pa /lib/firmware/<name>
|
|
.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 D-BUS INTERFACE
|
|
With D-Bus support,
|
|
.Nm
|
|
serves
|
|
.Cm org.finit.Device1
|
|
at
|
|
.Pa /org/finit/device
|
|
on its own brokerless bus,
|
|
.Pa unix:path=/run/keventd/bus ,
|
|
the same way
|
|
.Xr finit 8
|
|
serves
|
|
.Cm org.finit .
|
|
Methods:
|
|
.Bl -tag -width RulesReload -offset indent -compact
|
|
.It Cm Settle (u) -> b
|
|
Wait until the device event queue drains, timeout in seconds
|
|
.It Cm Trigger (ss)
|
|
Replay events: action and subsystem glob, empty glob matches all
|
|
.It Cm Info (s) -> a{ss}
|
|
Device properties for a devpath, from /run/udev/data
|
|
.It Cm RulesReload () -> u
|
|
Re-read the udev rules directories, returns the rule count
|
|
.El
|
|
.Pp
|
|
Properties
|
|
.Cm QueueEmpty (b)
|
|
and
|
|
.Cm SeqnumProcessed (t)
|
|
expose the queue state; the
|
|
.Cm DeviceProcessed (ss)
|
|
signal fires after each fully handled event.
|
|
.Sh NETLINK REBROADCAST
|
|
The Linux kernel sends uevents to netlink multicast group 1 (bit 0) of
|
|
.Dv NETLINK_KOBJECT_UEVENT .
|
|
Only the device manager listens on this raw kernel group. Userspace
|
|
consumers such as applications using
|
|
.Sy libudev
|
|
expect to receive processed events on a separate netlink group.
|
|
.Pp
|
|
.Sy systemd/udevd
|
|
established the convention of rebroadcasting to a separate group, and
|
|
.Sy libudev-zero ,
|
|
a daemonless replacement for libudev, listens on group 0x4 for these
|
|
events. Without rebroadcast, graphical applications, Wayland and X11
|
|
compositors, libinput, and other libudev consumers will not receive
|
|
device hotplug events.
|
|
.Pp
|
|
.Nm
|
|
rebroadcasts by default to netlink group 4 (bit 2, i.e.\&
|
|
.Li 0x4 ) .
|
|
A second netlink socket is created at startup, and after each uevent
|
|
has been fully processed (device nodes created, modules loaded,
|
|
etc.\&), the original event is sent to the configured group. This
|
|
ensures that device nodes and symlinks already exist by the time
|
|
consumers receive the event.
|
|
.Pp
|
|
Use
|
|
.Fl g
|
|
to override the default group mask, or
|
|
.Fl G
|
|
to disable rebroadcast entirely.
|
|
.Pp
|
|
See also:
|
|
.Lk https://github.com/illiliti/libudev-zero "libudev-zero" ,
|
|
.Lk https://skarnet.org/software/mdevd/ "mdevd" .
|
|
.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
|