Re: Rules on how to use sysfs in userspace programs

Jesper Juhl
2007-06-09T20:09:16Z

On 08/06/07, Greg KH <greg@kroah.com> wrote:
> Over time there have been a number of problems when sysfs has changed in
> "unexpected" ways. Here's a document that Kay wrote a while ago that
> I'd like to add to the kernel Documentation directory to help userspace
> programmers out.
>
> Any comments or critique of this is greatly appreciated.
>

Don't forget to update Documentation/00-INDEX when you add the document :-)

More comments below.

> thanks,
>
> greg k-h
>
> ------------------------------------
>
> Rules to access device-information in the Linux kernel sysfs
>
"Rules on how to access..." perhaps?

> The kernel exported sysfs exports internal kernel implementation-details
> and depends on internal kernel-structures and layout. It is agreed upon
> kernel developers, that the Linux kernel does not provide a stable

You write "It is agreed upon kernel developers..." I would write "It
is agreed upon by the kernel developers..."

> internal API. As sysfs is a direct export of kernel internal
> structures, the sysfs interface can't provide a stable interface too, it

Shouldn't that be "can't provide a stable interface either" ?

> may always change along with internal kernel changes.
>
> To minimize the risk of breaking users of sysfs, which are in most cases
> low-level userspace applications, with a new kernel release, the users
> of sysfs must follow some rules to use an abstract-as-possible way to

You write "to use an abstract-as-possible way to" I would have written
"to use an as abstract-as-possible way to"

> access this filesystem. The current udev and HAL programs already
> implement this and users are encouraged to plug, if possible, into the
> abstractions these both programs provide instead of accessing sysfs

shouldn't that be "both these" not "these both" ?

> directly.
>
> But if you really do want to access sysfs, please follow the following
> rules and then your programs should work for all future versions of
> sysfs.
>
[snip]
>
> - Properties of parent devices never belong into a child device.
> Always look at the parent devices themselves for determining device
> context properties. If the device 'eth0' or 'sda' does not have a
> "driver"-link, then it does not have a driver. It's value is empty.

"it's" is short for "it is", not the same as "its" which I believe is
what you want here.

> Never copy the value of the parent-device into a child-device. Parent
> device-properties may change dynamically without any notice to the
> child device.
>
> - Hierarchy in a single device-tree
> There is only one valid place in sysfs where hierarchy can be examined
> and this is below: /sys/devices.
> It is planned, the all device directories will end up in the tree

Don't you mean "that all device..." ?

> below this directory.
>
> - Classification by subsystem
> There are currently three places for classification of devices:
> /sys/block, /sys/class and /sys/bus. It is planned, that these will
> not contain any device-directories themselves, but only flat lists of
> symlinks pointing to the unified /sys/devices tree.
>
> All three places have completely different rules to access the

I believe that should be "rules on how to access the".

> information. It is planned to merge all three
> classification-directories into one place at /sys/subsystem/,
> following the current layout of the bus-directories. All buses and
> classes, including the converted block-subsystemm, will show up
> there.
> The devices of a subsystem will create a symlink in the "devices"
> directory at /sys/subsystem/<name>/devices/.
>
[snip]

--
Jesper Juhl <jesper.juhl@gmail.com>
Don't top-post http://www.catb.org/~esr/jargon/html/T/top-post.html
Plain text mails only, please http://www.expita.com/nomime.html