From 4984158b95c5a0c3922cd34940c393652d080f99 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Sun, 14 Jan 2018 17:54:42 +0000 Subject: New mdevd model, prepare for 0.1.0.0 - mdevd-netlink removed - mdevd listens to the netlink itself - mdevd-coldplug writes nothing to stdout, but triggers the kernel to create uevents --- doc/index.html | 5 +- doc/mdevd-coldplug.html | 25 ++++------ doc/mdevd-netlink.html | 124 ------------------------------------------------ doc/mdevd.html | 44 ++++++++--------- doc/upgrade.html | 11 +++++ 5 files changed, 42 insertions(+), 167 deletions(-) delete mode 100644 doc/mdevd-netlink.html (limited to 'doc') diff --git a/doc/index.html b/doc/index.html index c11b508..19a43a4 100644 --- a/doc/index.html +++ b/doc/index.html @@ -53,7 +53,7 @@ entirely compatible with advanced mdev usage such as The Linux kernel must be 2.6.10 or later.

GNU make, version 3.81 or later

skalibs version -2.6.0.2 or later. It's a build-time requirement. It's also a run-time +2.6.3.0 or later. It's a build-time requirement. It's also a run-time requirement if you link against the shared version of the skalibs library.

@@ -69,7 +69,7 @@ library.

The current released version of mdevd is -0.0.1.0.

0.1.0.0

Alternatively, you can checkout a copy of the mdevd git repository: @@ -100,7 +100,6 @@ the previous versions of mdevd and the current one.

mdevd-coldplug performs a coldplug: it scans /sys for all registered devices a uevent manager would -want to perform actions on, and generates uevents for all these -devices. +want to perform actions on, and tells the kernel to generate uevents +for all these devices.

Interface

mdevd-coldplug scans /sys for devices.
For every suitable device it finds, it generates a -uevent and writes it to its stdout, using the same format -as mdevd-netlink.
It exits when it has finished scanning.
For every suitable device it finds, it tells the kernel +to generate an event. If a device manager such as +as mdevd is listening to the netlink +at this point, it will pick up the series of events.
mdevd-coldplug exits when it has finished scanning.

- This implies that the mdevd-coldplug | mdevd command line -will function as a coldplug manager, just like mdev -s. -

Options

slashsys

/sys

mdevd-coldplug is a short-lived program, just like -mdev -s.
Unlike mdev -s, however, mdevd-coldplug does -not act on the uevents it generates. It simply prints them. -This allows for easy debugging.
To act on the uevents, simply pipe the output of -mdevd-coldplug into mdevd.

mdev -s

udevadm trigger

mdevd: the mdevd-netlink program

-mdevd
-Software
-skarnet.org -

The `mdevd-netlink` program

-mdevd-netlink listens to the netlink interface for uevents -(also called "hotplug" or "udev" events), and writes those uevents to -its standard output, using a simple format. -

-mdevd expects uevents in the same -format mdevd-netlink writes them. So the -mdevd-netlink | mdevd command line will function as -a daemon reading uevents from the netlink and handling them. -

Interface

-     mdevd-netlink [ -d notif ] [ -v verbosity ] [ -b kbufsz ]
-

mdevd-netlink binds to the netlink interface and listens for -hotplug events, as the udevd program does.
It writes event information to its stdout. The output contains -null characters, so a terminal will not display them correctly. To -properly use mdevd-netlink, it should be piped into a handler -program such as mdevd.
mdevd-netlink is a long-lived program. -When it receives a SIGTERM, it stops listening to hotplug events; -it will exit as soon as it has flushed its event queue to stdout.

Options

-d notif : when ready (actually -listening to the netlink), write a newline to file descriptor notif -then close it. This allows mdevd-netlink to use the -s6 mechanism to -notify readiness. notif cannot be lesser than 3. If this -option is not given, no readiness notification is sent.
-v verbosity : be more or less verbose. -Default verbosity is 1. 0 will only print fatal error messages, 3 will -print warnings every time the netlink interface sends something -unexpected.
-b kbufsz : try and reserve a kernel buffer of -kbufsz bytes for the netlink queue. Too large a buffer wastes kernel memory; -too small a buffer risks losing events. The default is 65536 (which is on -the large side).

Protocol

An event is a series of null-terminated strings as they are sent by -the kernel to the netlink; mdevd-netlink adds a final empty string -(i.e. an additional null character) to mark the end of the series.
The first string is a short description of the event; it normally -contains the string "@/". Other strings after the first are of the form -"VARIABLE=value", and describe the environment which a hotplug helper -for the event (registered in /proc/sys/kernel/hotplug) would be -spawned with.

Example (newlines added for clarity):

-add@/class/input/input9/mouse2\0
-ACTION=add\0
-DEVPATH=/class/input/input9/mouse2\0
-SUBSYSTEM=input\0
-SEQNUM=106\0
-PHYSDEVPATH=/devices/pci0000:00/0000:00:1d.1/usb2/22/22:1.0
-PHYSDEVBUS=usb\0
-PHYSDEVDRIVER=usbhid\0
-MAJOR=13\0
-MINOR=34\0
-\0

Notes

mdevd-netlink is a daemon; it should be run under a proper supervision system such -as s6.
If you are running mdevd-netlink, the program you pipe its -output into should be the only program handling uevents; that means -that /proc/sys/kernel/hotplug should be empty.
The mdevd-netlink | mdevd command line is a quick -way of running a uevent manager, but there are ways to improve it: -
- Using the -execline scripting -language, the pipeline { mdevd-netlink } mdevd command -line will avoid leaving a shell around.
- The best way to use mdevd-netlink and mdevd is with a -supervision system: -under s6 or -s6-rc, write a service -pipeline where mdevd-netlink is a producer and -mdevd is a consumer. This setup has the advantage, among -others, that you can restart the netlink listener and the event handler -separately. The examples/ subdirectory of the mdevd -package contains example configurations for such a setup.

The `mdevd` program

-mdevd is a uevent manager. It reads a series of -uevents on its stdin; for every uevent it reads, it performs +mdevd is a uevent manager. It connects to the netlink and reads +a series of uevents; for every uevent it reads, it performs actions according to its configuration file. Actions can be inserting a kernel module, creating or modifying device entries in /dev, etc. @@ -36,35 +36,29 @@ The differences between mdevd and mdev are:

mdev needs to be registered as a hotplug manager and the kernel spawns an instance of mdev per uevent; for every uevent, -mdev has to parse its configuration file. By contrast, there -is only one instance of mdevd, reading a series of uevents and +mdev has to parse its configuration file. By contrast, mdevd is +a daemon: it's long-lived, and there is only one instance, +reading a series of uevents and performing actions without forking; the configuration file is read and parsed only once.
mdevd reads uevents on its stdin. It is not suitable as -a hotplug manager, and it does not connect to the netlink itself -either. It is meant to be used in conjunction with -mdevd-netlink, which reads -uevents from the netlink, or with -mdevd-coldplug, which generates -coldplug uevents.

Interface

-     mdevd [ -v verbosity ] [ -f conffile ] [ -n ] [ -s slashsys ] [ -d slashdev ] [ -F fwbase ]
+     mdevd [ -v verbosity ] [ -D notif ] [ -b kbufsz ] [ -f conffile ] [ -n ] [ -s slashsys ] [ -d slashdev ] [ -F fwbase ]

mdevd reads and parses its configuration file /etc/mdev.conf.
It then reads its stdin, waiting for uevents. -
It exits when the stream of uevents ends. (EOF on stdin.)
It then connects to the netlink and reads from it, waiting for uevents. +
It exits 0 on a SIGTERM.

Exit codes

0: EOF read on standard input
0: SIGTERM received, clean exit
1: received an invalid event
2: syntax error in the configuration file
100: wrong usage

SIGHUP: re-read the configuration file
SIGTERM: exit as soon as possible

Options

-v verbosity : be more or less verbose. Default verbosity is 1. 0 will only print fatal error messages, 3 or more is seriously verbose debugging.
-D notif : when ready +(actually listening to the netlink), +write a newline to file descriptor notif then close it. +This allows mdevd to use the +s6 mechanism to notify +readiness. notif cannot be lesser than 3. +If this option is not given, no readiness notification is sent.
-b kbufsz : try and reserve a kernel buffer of +kbufsz bytes for the netlink queue. Too large a buffer wastes kernel memory; +too small a buffer risks losing events. The default is 65536 (which is reasonable +for average systems).
-n : dry run. mdevd will not create or delete device nodes, and it will not spawn commands. Instead, it will print to stdout the actions it would have performed.

Notes

Strictly speaking, mdevd is a short-lived program: it has -a normal exit condition, which is when it receives EOF on its stdin. -That allows it to work as a coldplug manager when paired with -mdevd-coldplug.
However, when paired with mdevd-netlink, -it acts as a daemon, because mdev-netlink normally never exits until -the end of the machine lifetime and never closes its stdout, so -mdevd's stdin never receives EOF.
The examples/ subdirectory of the mdevd package contains examples on how to run mdevd under various init systems / supervisors.

What has changed in mdevd

in 0.1.0.0

skalibs +dependency bumped to 2.6.3.0.
The mdevd-netlink program doesn't exist anymore.
mdevd now listens to the netlink itself.
mdevd-coldplug does not print events +to stdout anymore. Instead, it makes the kernel trigger events.

in 0.0.1.0

-- cgit v1.2.3

Interface

Options

The mdevd-netlink program

Interface

Options

Protocol

Notes

The mdevd program

Interface

Exit codes

Options

Notes

What has changed in mdevd

in 0.1.0.0

in 0.0.1.0

The `mdevd-netlink` program

The `mdevd` program