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

[Rob Landley <rob@landley.net>]

On Wednesday 18 July 2007 7:40:20 pm Greg KH wrote:
> On Wed, Jul 18, 2007 at 01:39:53PM -0400, Rob Landley wrote:
> > PICK ONE!  JUST #*%(&#%& PICK ONE!  AAAAAAAAHHHHHHH!!!!!!!!!
> >
> > I don't care where it is.  Just put it somewhere I can find it, and keep
> > it there.  All this gratuitous moving stuff around serves NO PURPOSE
> > other than to break userspace.  I'm trying to document this so that the
> > next time you go "oh wait, it should be at "/sys/tarantula/fruitbat" I
> > can show that you're breaking an existing documented userspace API.
> >
> > There's a kernel config option to make symlinks from the old
> > location.  /sys/block makes as much sense as any other location, and it's
> > what's there now.
>
> Read the sysfs documentation file we just added, it describes how this
> is all documented and should be used.  So well that I do not think you
> need to try to document it again.

I'm not trying to document all of sysfs, I'm trying to document hotplug.  I 
realize now I should have been more clear about that.

I've been working on the document I just posted on and off since may,  
(Possibly longer but I lost a lot of data in the hard drive crash on my 
laptop last month.  For example, I can't find a copy of my 
half-finished "history of hotplug" document and will probably need to start 
over, although I've still got a few places to look to see if I backed up a 
copy...)

This document has been sitting mostly unchanged on my hard drive since OLS, 
until I finally tracked down example code to do the netlink bit so I could 
finish it.  I tried to bounce a copy of the "everything but netlink" version 
off of kay by replying to his email with notes from OLS, and that's when I 
bumped into the "he's spam-blocking me" issue.  It got lost in the shuffle of 
OLS, and I just got back to it at the start of this thread.

Earlier today I read (and commented on, in the message to Cornelia Huck) the 
copy of Documentation/sysfs-rules.txt.  (Ah, darn it.  I have too many open 
windows on my desktop.  Hits "send" on message to Cornelia huck I _wrote_ 
earlier today.)

Documentation/sysfs-rules.txt doesn't talk about /sbin/hotplug or netlink 
hotplug.  It doesn't say how to distinguish a char device from a block 
device.  It mostly talks about finding stuff under the "/sys/devices" 
directory, most of which isn't relevant to populating /dev.  It doesn't 
clearly distinguish where you can find information in current kernels (2.6.22 
and earlier) from stuff that hasn't gone into any existing release.  Ideally 
I'd like to identify a subset of that information which is not only present 
in current kernels but should remain findable at that location in future 
kernels.  Over half the document is about what _not_ to do, and consists of 
warnings about "buggy apps", despite the assumption that anything _not_ 
explicitly documented is forbidden because most of the things sysfs exports 
are considered unmaintainable.

I've read the stuff under Documentation/ABI/{stable,testing}, and would be 
happy to refer to it rather than duplicating if I could get the info I needed 
out of it.  Documentation/filesystems/sysfs.txt is still from Patrick Mochel 
in 2003 and mostly about the kernel side rather than an API exported to 
userspace, and sysfs-pci.txt in that directory is similar.  Is there more I 
missed?

> thanks,
>
> greg k-h

Sorry, I'm not trying to be a pain.  I'm trying to document something I had to 
figure out for myself experimentally in 2005, which has been broken for me by 
kernel changes twice since then (when the "device" symlink went in back 
around 2.6.14, and when subdirs turned to symlinks recently), and I'm told is 
changing again with the additon of /sys/class/block (which means /sys/class/* 
no longer contains just char devices).

Ideally I'd like to come up with documentation that allows somebody to write 
one program that works on existing AND on new kernels, hence "stable API".

Rob
-- 
"One of my most productive days was throwing away 1000 lines of code."
  - Ken Thompson.