Re: Rules on how to use sysfs in userspace programs

["Jesper Juhl" <jesper.juhl@gmail.com>]

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