From 32759d402e7327865ea18a203bd1c09f98735bd1 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Sun, 22 Oct 2017 17:09:25 +0000 Subject: Initial commit --- doc/index.html | 115 ++++++++++++++++++++++++++++++++++++++++++ doc/mdevd-coldplug.html | 74 +++++++++++++++++++++++++++ doc/mdevd-netlink.html | 123 +++++++++++++++++++++++++++++++++++++++++++++ doc/mdevd.html | 130 ++++++++++++++++++++++++++++++++++++++++++++++++ doc/upgrade.html | 28 +++++++++++ 5 files changed, 470 insertions(+) create mode 100644 doc/index.html create mode 100644 doc/mdevd-coldplug.html create mode 100644 doc/mdevd-netlink.html create mode 100644 doc/mdevd.html create mode 100644 doc/upgrade.html (limited to 'doc') diff --git a/doc/index.html b/doc/index.html new file mode 100644 index 0000000..91c01d3 --- /dev/null +++ b/doc/index.html @@ -0,0 +1,115 @@ + + + + + + mdevd - A mdev-compatible Linux hotplug manager daemon + + + + + + +

+Software
+skarnet.org +

+ +

mdevd

+ +

What is it ?

+ +

+ mdevd is a small daemon managing kernel hotplug events, similarly to udevd. +

+ +

+ It uses the same configuration file as +mdev, +which is a hotplug manager integrated in the +Busybox suite of tools. +However, mdev needs to be registered in +/proc/sys/kernel/hotplug, and the kernel forks +an instance of mdev for every event; by contrast, mdevd is a daemon +and does not fork. +

+ +

+ The point of mdevd is to provide a drop-in replacement to mdev +that does not fork, so it can handle large influxes of events +at boot time without a performance drop. mdevd is designed to be +entirely compatible with advanced mdev usage such as +mdev-like-a-boss. +

+ +

Installation

+ +

Requirements

+ +

A Linux-based system with a standard C development environment. +The Linux kernel must be 2.6.10 or later.
GNU make, version 3.81 or later
skalibs version +2.6.0.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.

+ +

Licensing

+ +

+ mdevd is free software. It is available under the +ISC license. +

+ +

Download

+ +

The current released version of mdevd is +0.0.1.0.
Alternatively, you can checkout a copy of the +mdevd +git repository: +
```
 git clone git://git.skarnet.org/mdevd 
```
There's also a +GitHub mirror +of the mdevd git repository.

+ +

Compilation

+ +

See the enclosed INSTALL file for installation details.

+ +

Upgrade notes

+ +

This page lists the differences to be aware of between +the previous versions of mdevd and the current one.

+ +

Reference

+ +

Commands

+ +

Related resources

+ +

mdevd is discussed on the +skaware mailing-list.

+ + + diff --git a/doc/mdevd-coldplug.html b/doc/mdevd-coldplug.html new file mode 100644 index 0000000..8355df3 --- /dev/null +++ b/doc/mdevd-coldplug.html @@ -0,0 +1,74 @@ + + + + + + mdevd: the mdevd-coldplug program + + + + + + +

+mdevd
+Software
+skarnet.org +

+ +

The `mdevd-coldplug` program

+ +

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

+ +

Interface

+ +

+     mdevd-coldplug [ -s slashsys ]
+

+ +

mdevd-coldplug scans /sys for devices.
For every suitable device it finds, it generates an +uevent and writes it to its stdout, using the same format +as mdevd-netlink.
It 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

+ +

-s slashsys : assume the sysfs +pseudo-filesystem is mounted on slashsys. Default is /sys.

+ +

Exit codes

+ +

0: success
111: system call failed

+ +

Notes

+ +

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.

+ + + diff --git a/doc/mdevd-netlink.html b/doc/mdevd-netlink.html new file mode 100644 index 0000000..9747f13 --- /dev/null +++ b/doc/mdevd-netlink.html @@ -0,0 +1,123 @@ + + + + + + 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.

+ + + diff --git a/doc/mdevd.html b/doc/mdevd.html new file mode 100644 index 0000000..b5b8a36 --- /dev/null +++ b/doc/mdevd.html @@ -0,0 +1,130 @@ + + + + + + mdevd: the mdevd program + + + + + + +

+mdevd
+Software
+skarnet.org +

+ +

The `mdevd` program

+ +

+mdevd is an uevent manager. It reads a series of +uevents on its stdin; 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. +

+ +

+ mdevd's configuration file uses the exact same +format as +mdev. +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 +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 reads and parses its configuration file /etc/mdev.conf.
It then reads its stdin, waiting for uevents. +
It exits when it has finished scanning.

+ +

Exit codes

+ +

0: EOF read on mdevd's stdin
1: received an invalid event
100: wrong usage
111: system call failed

+ +

Signals

+ +

+ mdevd reacts to the following signals: +

+ +

SIGHUP: re-read the configuration file

+ +

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.
-n : dry run. mdevd will not create or delete +device nodes, and it will not spawn commands. Instead, it will print to stdout +the commands it would have spawned.
-f conffile : read the configuration +file from conffile. Default is /etc/mdev.conf.
-s slashsys : assume the sysfs +pseudo-filesystem is mounted on slashsys. Default is /sys.
-d slashdev : assume the device nodes +are to be found in slashdev. Default is /dev.
-F fwbase : assume the firmware files, if any, +are to be found in fwbase. Default is /lib/firmware.

+ +

Configuration file

+ +

+ mdevd uses mdev's configuration file format. +A good mdev.conf example is available +here. +

+ +

+ If mdevd cannot find its configuration file, it will use a simple, basic default +configuration where it can create device nodes as root or delete them, and does +nothing else. +

+ +

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.

+ + + diff --git a/doc/upgrade.html b/doc/upgrade.html new file mode 100644 index 0000000..06c1654 --- /dev/null +++ b/doc/upgrade.html @@ -0,0 +1,28 @@ + + + + + + mdevd: how to upgrade + + + + + + +

+mdevd
+Software
+skarnet.org +

+ +

What has changed in mdevd

+ +

in 0.0.1.0

+ +

Initial release.

+ + + -- cgit v1.2.3

mdevd

What is it ?

Installation

Requirements

Licensing

Download

Compilation

Upgrade notes

Reference

Commands

Related resources

The mdevd-coldplug program

Interface

Options

Exit codes

Notes

The mdevd-netlink program

Interface

Options

Protocol

Notes

The mdevd program

Interface

Exit codes

Signals

Options

Configuration file

Notes

What has changed in mdevd

in 0.0.1.0

The `mdevd-coldplug` program

The `mdevd-netlink` program

The `mdevd` program