Re: Documentation for sysfs, hotplug, and firmware loading.

Cornelia Huck
2007-07-18T07:59:18Z

On Tue, 17 Jul 2007 17:03:31 -0400,
Rob Landley <rob@landley.net> wrote:

> Here's some sysfs/hotplug/firmware loading documentation I wrote. I finally
> tracked down the netlink bits to finish it up, so I can send it out to the
> world.
>
> What's wrong with it? :)

OK, some comments from me:

> Entires for block devices are found at the following locations:
^^^^^^^ typo
>
> /sys/block/*/dev
> /sys/block/*/*/dev

Note that this will change to /sys/class/block/ in the future.

> Entries for char devices are found at the following locations:
>
> /sys/bus/*/devices/*/dev
> /sys/class/*/*/dev

Uh, that is actually the generic location?

It may be enough (and less confusing) to just state that the dev
attribute will belong to the associated "class" device sitting
under /sys/class/ (with the current exception of /sys/block/).

(And how about referring to Documentation/sysfs-rules.txt?)

> A simple bash script to record variables from hotplug events might look like:

Using a bash script is actually a very bad idea in the general case. It
can lead to OOM very quickly on large installations.

> It's possible to disable the usermode helper hotplug mechanism (by writing an
> empty string into /proc/sys/kernel/hotplug), but there's little reason to
> do this since a usermode helper won't be spawned if /sbin/hotplug doesn't
> exist, and negative dentries will record the fact it doesn't exist after
> the first lookup attempt.

AFAIK, the normal mode of operation is to use the hotplug mechanism
during early setup but to disable it once you have a listener on
netlink in place. My systems have an empty /proc/sys/kernel/hotplug.

> ACTION
> The current hotplug action: "add" to add the device...
> [QUESTION: Full list of actions?]

Would be good. See lib/kobject_uevent.c.

> DEVPATH
> Path under /sys at which this device's sysfs directory can be found.
> If $DEVPATH begins with /block/ the event refers to a block device,
> otherwise it refers to a char device.

Huh? That's just the path in sysfs. And there's more than block and
char :) Check SUBSYSTEM for what your device actually is.

> SUBSYSTEM
> If this is "block", it's a block device. Anything else is a char device.

No. For devices, SUBSYSTEM may be the class (like 'scsi_device') or the
bus (like 'pci').

> DRIVER
> If present, a suggested driver (module) for handling this device. No
> relation to whether or not a driver is currently handling the device.

No, this actually is the current driver.

> stable_api_nonsense:
> ====================
>
> Note: Sysfs exports a lot of kernel internal state, and the maintainers of
> sysfs do not believe that exposing information to userspace for use by
> userspace programs constitues an "API" that must be "stable". The sysfs
> infrastructure is maintained by the author of
> Documentation/stable_api_nonsense.txt, who seems to believe it applies to
> userspace as well. Therefore, at best only a subset of the information in
> sysfs can be considered stable from version to version.
>
> The information documented here should remain stable. Some other parts
> of sysfs are documented under Documentation/API, although that
> directory comes with a warning that anything documented there can go
> away after two years. Any other information exported by sysfs should be
> considered debugging info at best, and probably shouldn't have been
> exported at all since it's not a "stable API" intended for use by
> actual programs.

Uh. Please refer to Documentation/sysfs-rules.txt.