Documentation for sysfs, hotplug, and firmware loading.
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? :)
Note, I still need to actually confirm that /sbin/hotplug can be called from initramfs by a statically linked device to load firmware before init gets spawned. It should work, and was explicitly discussed as a design goal a year or two back, but it might need a bugfix patch to actually, you know, _work_.
(P.S. I'd cc Kay Sievers on this, but he's still spam-blocking my email. Thanks to Kay for answer lots of questions about this at OLS, and to Fank Sorenson who wrote a netlink implementation of mdev back in 2005 that I dug up to figure out how that part works.)
Signature · 2 lines
"One of my most productive days was throwing away 1000 lines of code." - Ken Thompson.
hotplug and firmware loading with sysfs.
========================================
The 2.6.x Linux kernels export a device tree through sysfs, which is a synthetic filesystem generally mounted at "/sys". Among other things, this filesystem tells userspace what hardware is available, so userspace tools (such as udev or mdev) can dynamically populate a "/dev" directory with device nodes representing the currently available hardware.
Notification when hardware is inserted or removed is provided by the hotplug mechanism. Linux provides two hotplug interfaces: /sbin/hotplug and netlink.
The combination of sysfs and hotplug obsoleted the older "devfs", which was removed from the 2.6.16 kernel.
Device nodes:
=============
Sysfs exports major and minor numbers for device nodes with which to populate /dev via mknod(2). These major and minor numbers are found in files named "dev", which contain two colon separated ascii decimal numbers followed by exactly one newline. I.E.
$ cat /sys/class/mem/zero/dev 1:5
Note that the name of the directory containing a dev entry is usually the traditional name for the device node. (The above entry is for "/dev/zero".)
Entires for block devices are found at the following locations:
/sys/block/*/dev
/sys/block/*/*/dev
Entries for char devices are found at the following locations:
/sys/bus/*/devices/*/dev
/sys/class/*/*/dev
A very simple bash script to populate /dev from /sys (without addressing ownership or permissions of the resulting /dev nodes) might look like:
#!/bin/bash
# Populate block devices
for i in /sys/block/*/dev /sys/block/*/*/dev
do
if [ -f $i ]
then
MAJOR=$(sed 's/:.*//' < $i)
MINOR=$(sed 's/.*://' < $i)
DEVNAME=$(echo $i | sed -e 's@/dev@@' -e 's@.*/@@')
mknod /dev/$DEVNAME b $MAJOR $MINOR
fi
done# Populate char devices
for i in /sys/bus/*/devices/*/dev /sys/class/*/*/dev
do
if [ -f $i ]
then
MAJOR=$(sed 's/:.*//' < $i)
MINOR=$(sed 's/.*://' < $i)
DEVNAME=$(echo $i | sed -e 's@/dev@@' -e 's@.*/@@')
mknod /dev/$DEVNAME c $MAJOR $MINOR
fi
doneHotplug:
========
The hotplug mechanism asynchronously notifies userspace when hardware is inserted, removed, or undergoes a similar significant state change. Linux provides two interfaces to hotplug; the kernel can spawn a usermode helper process, or it can send a message to an existing daemon listening to a netlink socket.
-- Usermode helper
The usermode helper hotplug mechanism spawns a new process to handle each hotplug event. Each such helper process belongs to the root user (UID 0) and is a child of the init task (PID 1). The kernel spawns one process per hotplug event, supplying environment variables to each new process describing that particular hotplug event. By default the kernel spawns instances of "/sbin/hotplug", but this default can be changed by writing a new path into "/proc/sys/kernel/hotplug" (assuming /proc is mounted).
A simple bash script to record variables from hotplug events might look like:
#!/bin/bash
env >> /filename
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.
-- Netlink
A daemon listening to the netlink socket receives a packet of data for each hotplug event, containing the same information a usermode helper would receive in environment variables.
The netlink packet contains a set of null terminated text lines. Each line but the first contains a KEYWORD=VALUE pair defining a hotplug event variable. The first line of the netlink packet combines the $ACTION and $DEVPATH values, separated by an @ (at sign).
Here's a C program to print hotplug nelink events to stdout:
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/poll.h>
#include <sys/socket.h>
#include <sys/types.h>
#include <unistd.h>
#include <linux/types.h>
#include <linux/netlink.h>
void die(char *s)
{
write(2,s,strlen(s));
exit(1);
}int main(int argc, char *argv[])
{
struct sockaddr_nl nls;
struct pollfd pfd;
char buf[512];
// Open hotplug event netlink socket
memset(&nls,0,sizeof(struct sockaddr_nl));
nls.nl_family = AF_NETLINK;
nls.nl_pid = getpid();
nls.nl_groups = -1;
pfd.events = POLLIN;
pfd.fd = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_KOBJECT_UEVENT);
if (pfd.fd==-1)
die("Not root\n");
// Listen to netlink socket
if (bind(pfd.fd, (void *)&nls, sizeof(struct sockaddr_nl)))
die("Bind failed\n");
while (-1!=poll(&pfd, 1, -1)) {
int i, len = recv(pfd.fd, buf, sizeof(buf), MSG_DONTWAIT);
if (len == -1) //die("recv\n");
// Print the data to stdout.
i = 0;
while (i<len) {
printf("%s\n", buf+i);
i += strlen(buf+i)+1;
}
}
die("poll\n");
// Dear gcc: shut up.
return 0;
}Hotplug event variables:
========================
Every hotplug event should provide at least the following variables:
ACTION
The current hotplug action: "add" to add the device... [QUESTION: Full list of actions?]
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.
SUBSYSTEM
If this is "block", it's a block device. Anything else is a char device.
The following variables are also provided for some devices:
MAJOR and MINOR
If these are present, a device node can be created in /dev for this device. Some devices (such as network cards) don't generate a /dev node.
[QUESTION: Any way to get the default name?]
DRIVER
If present, a suggested driver (module) for handling this device. No relation to whether or not a driver is currently handling the device.
INTERFACE and IFINDEX
When SUBSYSTEM=net, these variables indicate the name of the interface and a unique integer for the interface. (Note that "INTERFACE=eth0" could be paired with "IFINDEX=2" because eth0 isn't guaranteed to come before lo and the count doesn't start at 0.)
FIRMWARE
The system is requesting firmware for the device. See "Firmware loading" below.
Injecting events into hotplug via "uevent":
===========================================
Events can be injected into the hotplug mechanism through sysfs via the "uevent" files. Each directory in sysfs containing a "dev" file should also contain a "uevent" file.
Note that in newer kernel versions, "uevent" is readable. Reading from uevent provides the set of "extra" variables associated with this event.
Firmware loading
================
If the hotplug variable FIRMWARE is set, the kernel is requesting firmware for a device (identified by $DEVPATH). To provide the firmware to the kernel, do the following:
echo 1 > /sys/$DEVPATH/loading
cat /path/to/$FIRMWARE > /sys/$DEVPATH/data
echo 0 > /sys/$DEVPATH/loading
Note that "echo -1 > /sys/$DEVPATH/loading" will cancel the firmware load and return an error to the kernel, and /sys/class/firmware/timeout contains a timeout (in seconds) for firmware loads.
See Documentation/firmware_class for more information.
Loading firmware for statically linked devices
==============================================
An advantage of the usermode helper hotplug mechanism is that if initramfs contains an executable /sbin/hotplug, it can be called even before the kernel runs init. This allows /sbin/hotplug to supply firmware (out of initramfs) to statically linked device drivers. (The netlink mechanism requires a daemon to listen to a socket, and such a daemon cannot be spawned before init runs.)
For licensing reasons, binary-only firmware should not be linked into the kernel image, but instead placed in an externally supplied initramfs which can be passed to the Linux kernel through the old initrd mechanism. See Documentation/filesystems/ramfs-rootfs-initramfs.txt for details.
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.
Quoted 5 lines · On Tue, 17 Jul 2007 17:03:31 -0400 Rob Landley 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? :)
(1. It's an attachment. :)
2. Here's a C program to print hotplug nelink events to stdout:
s/nelink/netlink/
3. See Documentation/firmware_class for more information.
Perhaps add a '/' after "firmware_class" to indicate a directory?
---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***
Quoted 5 lines · Rob Landley
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:
Quoted 1 line
Entires for block devices are found at the following locations:
^^^^^^^ typo
Quoted 3 lines
/sys/block/*/dev
/sys/block/*/*/dev
Note that this will change to /sys/class/block/ in the future.
Quoted 4 lines
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?)
Quoted 1 line
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.
Quoted 5 lines
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/hotplugdoesn'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.
Quoted 3 lines
ACTION
The current hotplug action: "add" to add the device... [QUESTION: Full list of actions?]
Would be good. See lib/kobject_uevent.c.
Quoted 4 lines
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.
Quoted 2 lines
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').
Quoted 3 lines
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.
Quoted 11 lines
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.
Quoted 7 lines
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.
Quoted 7 lines · Cornelia Huck
On Tue, 17 Jul 2007 17:03:31 -0400,
Quoted 4 lines · Rob Landley
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.
Quoted 6 lines
Quoted 1 line
What's wrong with it? :)
OK, some comments from me:
Quoted 1 line
Entires for block devices are found at the following locations:
^^^^^^^ typo
Got it.
Quoted 4 lines
Quoted 2 lines
/sys/block/*/dev
/sys/block/*/*/devNote that this will change to
/sys/class/block/in the future.
At OLS, Kay Sievers said in a future version they were going to move it to "/sys/subsystem/block", which I can't document right now because no current kernel does this, and that path will never work with any previous kernel, but there should be a compatability symlink from the old path to the new one. He never mentioned /sys/class/block.
To all of this, I would like to humbly ask:
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.
Quoted 6 lines
Quoted 4 lines
Entries for char devices are found at the following locations:
/sys/bus/*/devices/*/dev
/sys/class/*/*/devUh, that is actually the generic location?
It's what Kay Sievers and Greg KH told me at OLS when I tracked them down to ask. I've also experimentally verified it working on Ubuntu 7.04. That was cut and pasted from Kay's email, and it works today.
Quoted 3 lines
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/).
Nope. If you recurse down under /sys/class following symlinks, you go into an endless loop bouncing off of /sys/devices and getting pointed back. If you don't follow symlinks, it works fine up until about 2.6.20 at which point things that were previously directories BECAME symlinks because the directories got moved, and it all broke.
Which is why I want it documented where to look for these suckers. Just give me ONE STABLE WAY TO FIND THIS INFORMATION, PLEASE.
This document is trying to document just enough information to make hotplug work using sysfs (which includes firmware loading if necessary).
Quoted 1 line
(And how about referring to
Documentation/sysfs-rules.txt?)
Because there isn't one in 2.6.22, and I've been writing this file on and off for a month as I tracked down various bits of information?
Quoted 5 lines
Quoted 2 lines
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.
I know. I'm just trying to show people how to do it. Notice that this script doesn't DO anything, it just dumps the variables (and proves
that /sys/hotplug got called). You're worried about the scalability of a debugging script.
Quoted 9 lines
Quoted 5 lines
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/hotplugdoesn'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.
And I documented how to blank it. However, lots of embedded systems stick with one mechanism because having two is something they won't waste space on. (I note that mdev is about 5k and can be made to use very little memory per instance.)
Also, you can hold off on all device probing until a netlink daemon is up and then echo "add" to all the "uevent" entries you find. At one point, udev did this, dunno what it's doing now.
Quoted 5 lines
Quoted 3 lines
ACTION
The current hotplug action: "add" to add the device... [QUESTION: Full list of actions?]Would be good. See
lib/kobject_uevent.c.
Ah, I left a TODO item in there that I forgot to mark TODO. :)
(Rummage) Seems to be "add, remove, change, online, offline, move"?
I can list 'em. Now I'm vaguely curious what generates online and offline events (MII transciever state transitions on a network card, or does this have to do with power saving modes?) And I have no idea what the difference between "change" and "move" is....
Quoted 7 lines
Quoted 4 lines
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.
If you are doing mknod, you need three pieces of information:
1) Major, 2) Minor, 3) Block or Char device. That's pretty much it. If you're trying to populate /dev you need that info.
Quoted 6 lines
Quoted 3 lines
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').
Do you make a /dev node for either one?
I'm trying to, at minimum, document what you pass to mknod. I consider it important to know.
Quoted 5 lines
Quoted 3 lines
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.
I've had it suggest drivers for devices that didn't have any loaded, and I had it _not_ specify drivers for devices that were loaded. (I checked.)
Could I get some clarification here?
Quoted 19 lines
Quoted 11 lines
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.Quoted 7 lines
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.
Quoted 1 line
Uh. Please refer to
Documentation/sysfs-rules.txt.
Where do I find this? It's not in 2.6.22, and -rc1 isn't out yet, so I assume you mean it's in the random git snapshot du jour?
(Rummages...)
Sigh. Missed that thread, and yes I've been working on this document since well before that was posted...
Ah yes. I replied to that when it was first posted. It's still "here's a list of things NOT to do" rather then telling you what you CAN do. I'm trying to document what you can do.
Useful documentation is not "Doing THIS is forbidden. Doing THIS is forbidden. Doing THIS is forbidden. What are you allowed to do? Guess! Oh, and anything I didn't explicitly mention could change at any time. Have fun."
Sysfs CAN export a stable API. It may only be a subset of what it's exporting, but it can still do so.
Sigh. I'll dig through this to try to find useful information amongst the "thou shalt nots", but I've got to catch a plane in a couple hours. Maybe on the flight...
Rob
Signature · 2 lines
"One of my most productive days was throwing away 1000 lines of code." - Ken Thompson.
Quoted 10 lines · Rob Landley
Quoted 4 lines
Quoted 2 lines
/sys/block/*/dev
/sys/block/*/*/devNote that this will change to
/sys/class/block/in the future.At OLS, Kay Sievers said in a future version they were going to move it to "
/sys/subsystem/block", which I can't document right now because no current kernel does this, and that path will never work with any previous kernel, but there should be a compatability symlink from the old path to the new one.
That will be the case.
Quoted 1 line
He never mentioned
/sys/class/block.
So? How about reading your email?
http://marc.info/?l=linux-kernel&m=118260305012165&w=2
You seem to miss the the very basic skills to collect the needed information to do the job of documenting something.
Quoted 3 lines
To all of this, I would like to humbly ask:
PICK ONE! JUST #*%(&#%& PICK ONE! AAAAAAAAHHHHHHH!!!!!!!!!
Man, you totally miss the point.
Quoted 10 lines
Quoted 6 lines
Quoted 4 lines
Entries for char devices are found at the following locations:
/sys/bus/*/devices/*/dev
/sys/class/*/*/devUh, that is actually the generic location?
It's what Kay Sievers and Greg KH told me at OLS when I tracked them down to ask. I've also experimentally verified it working on Ubuntu 7.04. That was cut and pasted from Kay's email, and it works today.
That is still true, but it still does not tell you the type of node to create, as you seem to insist on.
Quoted 9 lines
Quoted 3 lines
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/).Nope. If you recurse down under
/sys/classfollowing symlinks, you go into an endless loop bouncing off of/sys/devicesand getting pointed back. If you don't follow symlinks, it works fine up until about 2.6.20 at which point things that were previously directories BECAME symlinks because the directories got moved, and it all broke.
That's total nonsense.
Quoted 10 lines
Which is why I want it documented where to look for these suckers. Just give me ONE STABLE WAY TO FIND THIS INFORMATION, PLEASE.
This document is trying to document just enough information to make hotplug work using sysfs (which includes firmware loading if necessary).
Quoted 1 line
(And how about referring to
Documentation/sysfs-rules.txt?)Because there isn't one in 2.6.22, and I've been writing this file on and off for a month as I tracked down various bits of information?
I invested a lot of time explaining stuff to you in email and personally, but really, that seems just like a total waste of time. I will not reply to any of your mails until you have proven to have read the udevtrigger code, and got a clue how to do stuff reliably, and get the basic knowledge needed to document it.
Kay
Quoted 12 lines · Kay Sievers
Quoted 10 lines · Rob Landley
Quoted 4 lines
Quoted 2 lines
/sys/block/*/dev
/sys/block/*/*/devNote that this will change to
/sys/class/block/in the future.At OLS, Kay Sievers said in a future version they were going to move it to "
/sys/subsystem/block", which I can't document right now because no current kernel does this, and that path will never work with any previous kernel, but there should be a compatability symlink from the old path to the new one.
Quoted 6 lines
That will be the case.
Quoted 1 line
He never mentioned
/sys/class/block.So? How about reading your email?
http://marc.info/?l=linux-kernel&m=118260305012165&w=2
It wasn't in the notes you sent me from OLS, and I didn't compare against the earlier one because I thought the OLS notes were complete.
Quoted 4 lines
Yes, in this order (if you want to use it, but
/sys/blockwill still be there):/sys/subsytem/block/devices/*
/sys/class/block/*
/sys/block/*/*
"if you want to use it" said to me that sys/class/block/* was optional, so I didn't add it to the document I was writing.
Quoted 2 lines
You seem to miss the the very basic skills to collect the needed information to do the job of documenting something.
I've gotten a lot of contradictory information, a lot of gratuitous changes from previous versions, a lot of notice of as of yet unmerged plans, and a lot of useless information (mostly in the form of "don't"s) while researching this topic. I'm trying to find a useful subset.
I asked you what I needed when we met in person, and you didn't put /sys/class/block/* in the list.
Sysfs is almost unique in that examining the implementation tells me NOTHING about how to use it. This is a defect in sysfs that I'm attempting to rectify by writing documentation about what you can rely on when trying to use it for hotplug and firmware loading. This is a specific, limited use that I'm familiar with the requirements for.
Is there anything in /sys/class/block that _isn't_ in /sys/block? Does "if you want to use it, but /sys/block will still be there" NOT mean, as I assumed at the time, that I could safely ignore it? (My impression from the meeting at OLS was that adding /sys/block to /sys/class/block had been just an idea rejected in favor of adding it to /sys/subsystem/block. I note that neither my Ubuntu 7.04 laptop nor the 2.6.22 system I built has either a /sys/class/block or a /sys/subsystem/block, so anything written attempting to use that won't work on any currently deployed Linux system. You can't use it today, and will never be able to use it on any kernel version deployed today.)
Quoted 5 lines
Quoted 3 lines
To all of this, I would like to humbly ask:
PICK ONE! JUST #*%(&#%& PICK ONE! AAAAAAAAHHHHHHH!!!!!!!!!
Man, you totally miss the point.
I want to document a stable API, including the subset of sysfs that will remain stable. The "point" appears to be that there isn't one because sysfs is "special", and udev should be in the kernel source tarball.
I'm trying to write down here the minimal information needed to find the "dev" nodes to populate /dev. There's no functional reason I'm aware of for them to keep moving around.
Quoted 5 lines
Quoted 5 lines
Quoted 5 lines
Quoted 4 lines
Entries for char devices are found at the following locations:
/sys/bus/*/devices/*/dev
/sys/class/*/*/dev
Quoted 8 lines
Quoted 5 lines
Quoted 1 line
Uh, that is actually the generic location?
It's what Kay Sievers and Greg KH told me at OLS when I tracked them down to ask. I've also experimentally verified it working on Ubuntu 7.04. That was cut and pasted from Kay's email, and it works today.
That is still true, but it still does not tell you the type of node to create, as you seem to insist on.
I don't insist on it, mknod insists on it. You cannot mknod a dev node without specifying block or char.
You're saying that sysfs should provide major and minor numbers without anywhere specifying "char" or "block", meaning the major and minor numbers cannot be _used_. I am insisting on getting the third piece of information without which "major" and "minor" are useless.
I asked very specifically about this at OLS, several times. What you're telling me now seems to contradict what you told me then.
What I documented works in today's kernel. You've talked about adding new mechanisms that won't work in today's kernel, which I'm not worrying about as long as the mechanisms that work with today's kernel continue to work. Now you say you're going to break today's kernel by adding block devices to /sys/class, which I got the impression was NOT going to happen at OLS (that it was going to move to sys/subsystem but that sys/block symlink would still track it). I specifically asked "what paths do I need to look at to find char devices" and "what paths do I need to look at to find block devices", and the paths in the documentation are the ones I got when I asked.
If block is going to move to sys/class, I can put in a warning about this pending breakage in the documentation, and modify my example code to filter it out.
Quoted 11 lines
Quoted 9 lines
Quoted 3 lines
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/).Nope. If you recurse down under
/sys/classfollowing symlinks, you go into an endless loop bouncing off of/sys/devicesand getting pointed back. If you don't follow symlinks, it works fine up until about 2.6.20 at which point things that were previously directories BECAME symlinks because the directories got moved, and it all broke.That's total nonsense.
Which part, the "following symlinks produced an endless loop" or the "directories turned into symlinks so not following them broke?"
Let's see...
According to my blog, Frank Sorensen first sent me a C port of my /dev populating script on December 12, 2005. The current kernel at the time was 2.6.14, so grab that, build user Mode Linux... Huh, it won't build with gcc 4.1.2. Or 3.4. Ok, defconfig? Nope, that wants a stack check symbol? Let's see... Ah, google says add -fno-stack-protector to CFLAGS. Right... Fire it up under qemu, "mount -t sysfs /sys /sys", and:
In 2.6.14, /sys/block/hda/device points
to ../../devices/pci0000:00/0000:00:01.1/ide0/0.0
/sys/block/hda/device/block points to ../../../../../block/hda
So in 2.6.14 you could
go /sys/block/hda/device/block/device/block/device/block... endlessly, which is the reason I wrote mdev not to follow symlinks but to instead only look at actual subdirectories. (It uses the same code to traverse down beneath /sys/block and /sys/class to look for "dev" entries.) This works fine up through the 2.6.20 in ubuntu 7.04, where everything
in /sys/class/tty/* is still a subdirectory. But in 2.6.22, /sys/class/tty/* is all symlinks. Hence the code that was working before changed, due to something that worked fine for a couple years but broke because it wasn't considered part of a stable API.
Which part of this is "total nonsense"?
Quoted 6 lines
Quoted 6 lines
Which is why I want it documented where to look for these suckers. Just give me ONE STABLE WAY TO FIND THIS INFORMATION, PLEASE.
This document is trying to document just enough information to make hotplug work using sysfs (which includes firmware loading if necessary).
Quoted 7 lines
Quoted 4 lines
Quoted 1 line
(And how about referring to
Documentation/sysfs-rules.txt?)Because there isn't one in 2.6.22, and I've been writing this file on and off for a month as I tracked down various bits of information?
I invested a lot of time explaining stuff to you in email and personally, but really, that seems just like a total waste of time.
I wrote up a document. Started writing it before OLS, incorporated the information I got from you while at OLS, and took a while tracking down some old code doing netlink so I could include enough for people to puzzle out how that works.
I would have bounced earlier unfinished drafts off of you, but you were spam-blocking my email. (Might still be, I don't know. This is why I wanted to talk to you in person at OLS.)
Quoted 1 line
I will not reply to any of your mails
And I _can't_ reply to yours off-list because of your out of control spam filter.
Quoted 2 lines
until you have proven to have read
the udevtrigger code,
I read the udev code when it was first posted. I read it again 20 versions later, and read it again 20 versions after that. I couldn't COMPILE the darn thing for its first ~40 releases, the code got ripped out and re-written several times, I watched as it grew and then threw out libsysfs.
So essentially you're saying "well read it again, we've finally got it right now"?
Quoted 2 lines
and got a clue how to do stuff reliably, and get
the basic knowledge needed to document it.
Because talking to you and having you email me the notes from this conversation did not provide the basic knowledge needed to document hotplug and firmware loading. Nor did asking for feedback on the document I wrote up. Thanks ever so much.
I point out that udev changes from version to version, so that running an old version of udev against a new kernel has been known to break. Udev was more or less completely rewritten three times while I was still paying attention to it. Reading the udev code and seeing what it's doing struck me as about as likely to reveal a stable API as reading the kernel source, or experimenting with sysfs from userspace. (Both of which I've _done_ at various points, and it keeps changing.)
Are you saying that the current version of udev will work with all future kernels, and thus if I can figure out what udev is doing today, I can just document that as the stable API?
Quoted 1 line
Kay
Rob
Signature · 2 lines
"One of my most productive days was throwing away 1000 lines of code." - Ken Thompson.
Quoted 1 line · Rob Landley
Is there anything in
/sys/class/blockthat _isn't_ in/sys/block?
No.
Quoted 2 lines
Does "if you want to use it, but
/sys/blockwill still be there" NOT mean, as I assumed at the time, that I could safely ignore it?
Ignore what? /sys/block? If you see /sys/class/block, then yes, you can ignore it as they are just symlinks back to each other.
Quoted 3 lines
(My impression from the meeting at OLS was that adding
/sys/blockto/sys/class/blockhad been just an idea rejected in favor of adding it to/sys/subsystem/block.
No, the /sys/class/block is in -mm and has been for some time.
Quoted 5 lines
I note that neither my Ubuntu 7.04 laptop nor the 2.6.22 system I built has either a
/sys/class/blockor a/sys/subsystem/block, so anything written attempting to use that won't work on any currently deployed Linux system. You can't use it today, and will never be able to use it on any kernel version deployed today.)
Not true at all, it works just fine here on my machines, and on all distros released in the past year or so as tested out by a lot of users.
The only reason it isn't in Linus's tree just yet, is that some very old mkinitrd programs don't seem to like it (we are talking Fedora Core 3 based distros, not Fedora itself.) People are trying to work out what the proper fix is for userspace there when they get the time.
So, expect the change to show up in 2.6.24.
Quoted 9 lines
Quoted 5 lines
Quoted 3 lines
To all of this, I would like to humbly ask:
PICK ONE! JUST #*%(&#%& PICK ONE! AAAAAAAAHHHHHHH!!!!!!!!!
Man, you totally miss the point.
I want to document a stable API, including the subset of sysfs that will remain stable. The "point" appears to be that there isn't one because sysfs is "special", and udev should be in the kernel source tarball.
What? Since when does udev have to be in the kernel source tarball? Who ever said that?
The issue here is that if you follow the rules as specified by the file, Documentation/sysfs-rules.txt and Documentation/ABI/*/sysfs-* you should be just fine. To ignore them, as you have done in your examples, will cause problems.
Quoted 3 lines
I'm trying to write down here the minimal information needed to find the "dev" nodes to populate /dev. There's no functional reason I'm aware of for them to keep moving around.
The issue is that the devices themselves keep moving around in the sysfs tree all the time as systems are dynamic and change.
Again, look at the udevtrigger program for a simple way to achieve this /dev population that you so desire.
But also realize that sysfs is much bigger than just trying to get the information to create a /dev tree.
Quoted 17 lines
Quoted 5 lines
Quoted 5 lines
Quoted 5 lines
Quoted 4 lines
Entries for char devices are found at the following locations:
/sys/bus/*/devices/*/dev
/sys/class/*/*/devQuoted 8 lines
Quoted 5 lines
Quoted 1 line
Uh, that is actually the generic location?
It's what Kay Sievers and Greg KH told me at OLS when I tracked them down to ask. I've also experimentally verified it working on Ubuntu 7.04. That was cut and pasted from Kay's email, and it works today.
That is still true, but it still does not tell you the type of node to create, as you seem to insist on.
I don't insist on it, mknod insists on it. You cannot mknod a dev node without specifying block or char.
Quoted 7 lines
You're saying that sysfs should provide major and minor numbers without anywhere specifying "char" or "block", meaning the major and minor numbers cannot be _used_. I am insisting on getting the third piece of information without which "major" and "minor" are useless.
I asked very specifically about this at OLS, several times. What you're telling me now seems to contradict what you told me then.
Here's the rule:
If the SUBSYSTEM is "block", it's a block device. Otherwise it's a char device.
But also realize that the majority of events you will get have nothing to do with device nodes. I think you are forgetting this fact.
Quoted 3 lines
If block is going to move to sys/class, I can put in a warning about this pending breakage in the documentation, and modify my example code to filter it out.
It's not a "breakage", we are preserving a symlink. The point is that you should not rely on the fact that /sys/block will be there in the future, as the documentation I pointed to above describes.
Quoted 27 lines
Quoted 11 lines
Quoted 9 lines
Quoted 3 lines
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/).Nope. If you recurse down under
/sys/classfollowing symlinks, you go into an endless loop bouncing off of/sys/devicesand getting pointed back. If you don't follow symlinks, it works fine up until about 2.6.20 at which point things that were previously directories BECAME symlinks because the directories got moved, and it all broke.That's total nonsense.
Which part, the "following symlinks produced an endless loop" or the "directories turned into symlinks so not following them broke?"
Let's see...
According to my blog, Frank Sorensen first sent me a C port of my /dev populating script on December 12, 2005. The current kernel at the time was 2.6.14, so grab that, build user Mode Linux... Huh, it won't build with gcc 4.1.2. Or 3.4. Ok, defconfig? Nope, that wants a stack check symbol? Let's see... Ah, google says add -fno-stack-protector to CFLAGS. Right... Fire it up under qemu, "mount -t sysfs /sys /sys", and:
In 2.6.14,
/sys/block/hda/devicepoints
to ../../devices/pci0000:00/0000:00:01.1/ide0/0.0
Quoted 6 lines
/sys/block/hda/device/blockpoints to ../../../../../block/hdaSo in 2.6.14 you could
go/sys/block/hda/device/block/device/block/device/block... endlessly, which is the reason I wrote mdev not to follow symlinks but to instead only look at actual subdirectories.
That was the problem right there. Why would you ever want to traverse symlinks blindly without realizing what you were walking? You can't just run 'find' on sysfs and expect to not get caught in endless loops, as the goal of the different parts of sysfs is to be able to start in one place, and figure out all of the needed information from there.
For example, if you have a device, you can get the subsystem it belongs to, the driver bound to it, and other stuff. If you start with a driver, you can get the devices it binds. Can you see the circle already?
So, you need to watch what you are trying to find, and if you do that, you never will get caught in circles. We never had that problem in udev at all, as we just work with what was passed to us, not blindly try to walk the whole sysfs tree.
Please use the proper context in order to get the information you need. And at all times, a directory can turn into a symlink in order to keep the same information possible.
Quoted 9 lines
(It uses the same code to traverse down
beneath/sys/blockand/sys/classto look for "dev" entries.) This works fine up through the 2.6.20 in ubuntu 7.04, where everything
in/sys/class/tty/*is still a subdirectory. But in 2.6.22,/sys/class/tty/*is all symlinks. Hence the code that was working before changed, due to something that worked fine for a couple years but broke because it wasn't considered part of a stable API.Which part of this is "total nonsense"?
Your code :)
Quoted 7 lines
Quoted 2 lines
until you have proven to have read
the udevtrigger code,I read the udev code when it was first posted. I read it again 20 versions later, and read it again 20 versions after that. I couldn't COMPILE the darn thing for its first ~40 releases, the code got ripped out and re-written several times, I watched as it grew and then threw out libsysfs.
You could not build it? Why not? Did you send me a patch for this problem that was major enough to keep you from using the project?
Quoted 2 lines
So essentially you're saying "well read it again, we've finally got it right now"?
Not at all, we are saying to look at how to achive what you are trying to achieve by reading a very small and well documented .c file (530 lines with comments) that explains how to easily and quickly achieve what you are trying to duplicate.
Heck, I did the same thing in a bash script for the Gentoo startup code a while back that still works, but has ordering issues that the .c file fixes up. Hence it was dropped for the replacement that we are pointing you at.
Quoted 10 lines
Quoted 2 lines
and got a clue how to do stuff reliably, and get
the basic knowledge needed to document it.Because talking to you and having you email me the notes from this conversation did not provide the basic knowledge needed to document hotplug and firmware loading. Nor did asking for feedback on the document I wrote up. Thanks ever so much.
I point out that udev changes from version to version, so that running an old version of udev against a new kernel has been known to break.
Hence the Documenation/CHANGES file documents the version that is needed. Right now it shows a version that is over a year and a half old. I do know that you can get away with running versions that are even older than that if you want to, but it's not really recommended.
Quoted 5 lines
Udev was more or less completely rewritten three times while I was still paying attention to it. Reading the udev code and seeing what it's doing struck me as about as likely to reveal a stable API as reading the kernel source, or experimenting with sysfs from userspace. (Both of which I've _done_ at various points, and it keeps changing.)
The development cycle of udev has nothing to do with sysfs here. Other than the fact that we learned how to interact with a kernel interface that directly exposes the internals of the kernel itself, something that no one had done before. In learning how to handle such major changes, udev has changed in order to support zillions of devices, small memory footprints, and lightening fast speed, all changes that required big udev internal changes, but had _nothing_ to do with the kernel and/or sysfs.
Quoted 3 lines
Are you saying that the current version of udev will work with all future kernels, and thus if I can figure out what udev is doing today, I can just document that as the stable API?
If you want to figure out how to create a dynamic /dev filesystem that can handle persistance device names, dynamic rules created by users, zillions of devices on small and big systems, small footprint, and very quick speed, then yes, read the udev source code.
What is the goal of this document here? You start out trying to explain the hotplug interface, and then get side tracked into talking about creating a dynamic /dev/ filesystem in userspace and then ramble on into how sysfs is layed out. These are three separate things
While the act of creating such a /dev filesystem does have something to do with the hotplug/uevent interface of the kernel, it isn't reliant on it. And the layout of sysfs also doesn't really have much affect on the creation of such a /dev filesystem, as udev proves (it works just fine without sysfs even being mounted.)
If you want to just document the hotplug/uevent interface then do that.
If you want to document sysfs and it's structure, do that too, after reading the existing documentation and understanding that.
thanks,
greg k-h
Quoted 8 lines · Greg KH
Quoted 8 lines
I don't insist on it, mknod insists on it. You cannot mknod a dev node without specifying block or char.
You're saying that sysfs should provide major and minor numbers without anywhere specifying "char" or "block", meaning the major and minor numbers cannot be _used_. I am insisting on getting the third piece of information without which "major" and "minor" are useless.
Quoted 6 lines
Quoted 2 lines
I asked very specifically about this at OLS, several times. What you're telling me now seems to contradict what you told me then.
Here's the rule:
If the SUBSYSTEM is "block", it's a block device. Otherwise it's a char device.
That's actually quite confusing to the casual reader, since:
Quoted 2 lines
But also realize that the majority of events you will get have nothing to do with device nodes. I think you are forgetting this fact.
So the rule should be:
If the SUBSYSTEM is "block" (implying major/minor are provided), it's a block device.
If the SUBSYSTEM is not "block", and major/minor are provided, it's a char device.
If major/minor are not provided, the event/device is not relevant to device node creation.
Quoted 23 lines · Cornelia Huck
Quoted 8 lines · Greg KH
Quoted 8 lines
I don't insist on it, mknod insists on it. You cannot mknod a dev node without specifying block or char.
You're saying that sysfs should provide major and minor numbers without anywhere specifying "char" or "block", meaning the major and minor numbers cannot be _used_. I am insisting on getting the third piece of information without which "major" and "minor" are useless.
Quoted 6 lines
Quoted 2 lines
I asked very specifically about this at OLS, several times. What you're telling me now seems to contradict what you told me then.
Here's the rule:
If the SUBSYSTEM is "block", it's a block device. Otherwise it's a char device.That's actually quite confusing to the casual reader, since:
Quoted 2 lines
But also realize that the majority of events you will get have nothing to do with device nodes. I think you are forgetting this fact.
Quoted 7 lines
So the rule should be:
If the SUBSYSTEM is "block" (implying major/minor are provided), it's a block device.
If the SUBSYSTEM is not "block", and major/minor are provided, it's a char device.
If major/minor are not provided, the event/device is not relevant to device node creation.
Yes, that is much more descriptive, thanks.
greg k-h
Quoted 31 lines · Greg KH
Quoted 22 lines · Cornelia Huck
On Fri, 20 Jul 2007 00:00:01 -0700,
Quoted 8 lines · Greg KH
Quoted 8 lines
I don't insist on it, mknod insists on it. You cannot mknod a dev node without specifying block or char.
You're saying that sysfs should provide major and minor numbers without anywhere specifying "char" or "block", meaning the major and minor numbers cannot be _used_. I am insisting on getting the third piece of information without which "major" and "minor" are useless.
Quoted 6 lines
Quoted 2 lines
I asked very specifically about this at OLS, several times. What you're telling me now seems to contradict what you told me then.
Here's the rule:
If the SUBSYSTEM is "block", it's a block device. Otherwise it's a char device.That's actually quite confusing to the casual reader, since:
Quoted 2 lines
But also realize that the majority of events you will get have nothing to do with device nodes. I think you are forgetting this fact.
Quoted 7 lines
So the rule should be:
If the SUBSYSTEM is "block" (implying major/minor are provided), it's a block device.
If the SUBSYSTEM is not "block", and major/minor are provided, it's a char device.
If major/minor are not provided, the event/device is not relevant to device node creation.
Quoted 1 line
Yes, that is much more descriptive, thanks.
agreed, thanks.
I'll try to post an updated version of my hotplug documentation later tonight. (Just a _touch_ jetlagged at the moment, though. It may only be 9:47 california time, but it's 11:47 on the east cost. I think.)
Quoted 1 line
greg k-h
Rob
Signature · 2 lines
"One of my most productive days was throwing away 1000 lines of code." - Ken Thompson.
Quoted 10 lines · Greg KH
Quoted 1 line · Rob Landley
Is there anything in
/sys/class/blockthat _isn't_ in/sys/block?No.
Quoted 2 lines
Does "if you want to use it, but
/sys/blockwill still be there" NOT mean, as I assumed at the time, that I could safely ignore it?Ignore what?
/sys/block? If you see/sys/class/block, then yes, you can ignore it as they are just symlinks back to each other.
I read "if you want to use it" as meaning "if you want to use "/sys/class/block", I.E. it was optional.
If /sys/block is going to remain a symlink to /sys/class/block then using the path "/sys/block" should work on both existing kernels and on new kernels without modification.
What moving it will force me to do is edit out "/sys/class/block' if I find it looking for char devices under "/sys/class". Moving it forces me to add code to remove it. I don't know what the supposed benefit is...
Ah, hang on. Most likely this is an implementation detail from moving everything under /sys/subsystem and making /sys/class a symlink -> subsystem and /sys/block a symlink -> subsystem/block. So it sounds like it's not really intentional breakage, just an implementation side effect. Ok, that makes sense.
(Sorry, this hadn't occurred to me until now. I'm not the one implementing this stuff, so I haven't spent the past few months thinking through the ramifications already. This entire thread is one of about 12 things I'm working on at the moment.)
Quoted 5 lines
Quoted 3 lines
(My impression from the meeting at OLS was that adding
/sys/blockto/sys/class/blockhad been just an idea rejected in favor of adding it to/sys/subsystem/block.No, the
/sys/class/blockis in -mm and has been for some time.
A yes, "set back up an automated -mm testing thing that away when previous laptop did". I need to bump that up on my todo list...
Quoted 8 lines
Quoted 5 lines
I note that neither my Ubuntu 7.04 laptop nor the 2.6.22 system I built has either a
/sys/class/blockor a/sys/subsystem/block, so anything written attempting to use that won't work on any currently deployed Linux system. You can't use it today, and will never be able to use it on any kernel version deployed today.)Not true at all, it works just fine here on my machines, and on all distros released in the past year or so as tested out by a lot of users.
"All the distros" meaning "not Ubuntu 7.04"? I just checked again, it doesn't have either a /sys/class/block or /sys/subsystem/block. I realize they're coming...
Quoted 6 lines
The only reason it isn't in Linus's tree just yet, is that some very old mkinitrd programs don't seem to like it (we are talking Fedora Core 3 based distros, not Fedora itself.) People are trying to work out what the proper fix is for userspace there when they get the time.
So, expect the change to show up in 2.6.24.
Ok.
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
Quoted 3 lines
To all of this, I would like to humbly ask:
PICK ONE! JUST #*%(&#%& PICK ONE! AAAAAAAAHHHHHHH!!!!!!!!!
Quoted 8 lines
Quoted 5 lines
Quoted 1 line
Man, you totally miss the point.
I want to document a stable API, including the subset of sysfs that will remain stable. The "point" appears to be that there isn't one because sysfs is "special", and udev should be in the kernel source tarball.
What? Since when does udev have to be in the kernel source tarball? Who ever said that?
I got that impression from:
http://lkml.org/lkml/2006/7/30/228
http://lwn.net/Articles/193603/
Quoted 4 lines
The issue here is that if you follow the rules as specified by the file,
Documentation/sysfs-rules.txtandDocumentation/ABI/*/sysfs-*you should be just fine. To ignore them, as you have done in your examples, will cause problems.
I read the Documentation/ABI ones in the current linus -git (well, as of... tuesday?) and am unaware of any conflicts. I read sysfs-rules.txt this morning, and the only _required_ change I'm aware of is filtering out /sys/class/block if it occurs. (Is there more Documentation in Andrew Morton's tree that's not in Linus's?)
Lemme re-read my document...
Ok, /sys/bus/*/devices/*/dev is the path Kay told me to use during our discussion at OLS. It's one of the paths I cut and pasted out of the email he sent me. He typed that path, I didn't. I see that the bit in "sysfs-rules.txt" about never using the "devices" symlink contradicts that. Ok, so what _should_ I do?
Personally, I've never seen a dev link under "/sys/bus". I neither own nor have personally encountered hardware that does that, and the first I heard that there _was_ such hardware was when talking to him at OLS.
Quoted 6 lines · what path should I use? Your email
/sys/bus/*/devices/*/dev/sys/class/*/*/dev/sys/block/*/dev/sys/block/*/*/dev
/sys/subsystem/*/devices/*/dev
The fifth of which isn't in currently deployed kernels (not in kernel.org, not in most recent ubuntu release, that counts as "not currently deployed" to me), and the first four should continue to work even when that goes in, so I didn't include it in "how to find this information", but I note that it also follows "devices"...
Quoted 9 lines
Quoted 3 lines
I'm trying to write down here the minimal information needed to find the "dev" nodes to populate /dev. There's no functional reason I'm aware of for them to keep moving around.
The issue is that the devices themselves keep moving around in the sysfs tree all the time as systems are dynamic and change.
Again, look at the udevtrigger program for a simple way to achieve this /dev population that you so desire.
I'm aware of that program, and can iterate through the tree and write "add" to "uevent" instead of reading "dev". Technically the /sbin/hotplug approach would have the same potential race condition with remove happening during
scan: the potential downside is leaving a node in /dev that will give an -ENODEV if you try to open it, which is annoying but not fatal (no obvious security implications or anything), and a small enough race condition that it would seldom if ever inconvenience real users.
I can document this, though...
Quoted 2 lines
But also realize that sysfs is much bigger than just trying to get the information to create a /dev tree.
I know. At the moment I'm only trying to document the subset of sysfs needed to maintain a /dev tree via hotplug. In future this may expand to include enough information to persistently name certain types of devices, but I'd be just as happy to have that under Devices/ABI and refer to it instead.
Quoted 22 lines
Quoted 22 lines
Quoted 5 lines
Quoted 5 lines
Quoted 5 lines
Quoted 4 lines
Entries for char devices are found at the following locations:
/sys/bus/*/devices/*/dev
/sys/class/*/*/devQuoted 8 lines
Quoted 5 lines
Quoted 1 line
Uh, that is actually the generic location?
It's what Kay Sievers and Greg KH told me at OLS when I tracked them down to ask. I've also experimentally verified it working on Ubuntu 7.04. That was cut and pasted from Kay's email, and it works today.
That is still true, but it still does not tell you the type of node to create, as you seem to insist on.
I don't insist on it, mknod insists on it. You cannot mknod a dev node without specifying block or char.
You're saying that sysfs should provide major and minor numbers without anywhere specifying "char" or "block", meaning the major and minor numbers cannot be _used_. I am insisting on getting the third piece of information without which "major" and "minor" are useless.
Quoted 6 lines
Quoted 2 lines
I asked very specifically about this at OLS, several times. What you're telling me now seems to contradict what you told me then.
Here's the rule:
If the SUBSYSTEM is "block", it's a block device. Otherwise it's a char device.
Ok. Cornelia Huck seemed to disagree, but I see that's been resolved in another message.
Quoted 2 lines
But also realize that the majority of events you will get have nothing to do with device nodes. I think you are forgetting this fact.
Actually, I'm filtering them out, but I should make a note of it in the documentation. (I'd happily document other events you might want to respond to that come into the hotplug mechanism, but I don't know what they are and am trying to start with the basics and flesh it out later. Persistent device naming is a can of worms I'll have to open eventually. Ubuntu 7.04 put uuids on every _partition_ in my laptop, and spins up my external usb hard drive trying to mount root. When connected a machine with an IDE hard drive, that's now going through the scsi layer. Sigh...)
Quoted 7 lines
Quoted 3 lines
If block is going to move to sys/class, I can put in a warning about this pending breakage in the documentation, and modify my example code to filter it out.
It's not a "breakage", we are preserving a symlink. The point is that you should not rely on the fact that
/sys/blockwill be there in the future, as the documentation I pointed to above describes.
It doesn't say that /sys/block are deprecated or will be removed. The closest it says is:
Quoted 2 lines
If
/sys/subsystemexists,/sys/bus,/sys/classand/sys/blockcan be ignored.
Which isn't the same as "must be ignored" or "may be removed". I asked about this explicitly at OLS ("can I just keep using /sys/block and /sys/class") and was told that there were no plans to remove them.
Existing systems require using the older names, and I'm unaware of any information the new names provide that the old ones don't.
Quoted 29 lines
Quoted 29 lines
Quoted 11 lines
Quoted 9 lines
Quoted 3 lines
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/).Nope. If you recurse down under
/sys/classfollowing symlinks, you go into an endless loop bouncing off of/sys/devicesand getting pointed back. If you don't follow symlinks, it works fine up until about 2.6.20 at which point things that were previously directories BECAME symlinks because the directories got moved, and it all broke.That's total nonsense.
Which part, the "following symlinks produced an endless loop" or the "directories turned into symlinks so not following them broke?"
Let's see...
According to my blog, Frank Sorensen first sent me a C port of my /dev populating script on December 12, 2005. The current kernel at the time was 2.6.14, so grab that, build user Mode Linux... Huh, it won't build with gcc 4.1.2. Or 3.4. Ok, defconfig? Nope, that wants a stack check symbol? Let's see... Ah, google says add -fno-stack-protector to CFLAGS.
Right... Fire it up under qemu, "mount -t sysfs /sys /sys", and:In 2.6.14,
/sys/block/hda/devicepoints
to ../../devices/pci0000:00/0000:00:01.1/ide0/0.0
/sys/block/hda/device/blockpoints to ../../../../../block/hda
Quoted 7 lines
Quoted 4 lines
So in 2.6.14 you could
go/sys/block/hda/device/block/device/block/device/block... endlessly, which is the reason I wrote mdev not to follow symlinks but to instead only look at actual subdirectories.That was the problem right there. Why would you ever want to traverse symlinks blindly without realizing what you were walking?
Because I didn't want to encode an unknown structure of sysfs into the program? Partitions were at the same level as hard drives one release (when I first came up with a working probing script for my Firmware Linux project, which according to my blog was October 27, 2005 and was using something like Linux 2.6.10), and moved into subdirectories the next, and I had no way of knowing if or when a third layer was going to be added to some future device I didn't know about.
Keep in mind I've been following this, on and off, for a while now:
http://lkml.org/lkml/2003/12/9/1
http://lkml.org/lkml/2003/12/10/16
And what I did was in response to the endless loop was _stop_ traversing symlinks at all, and only followed subdirectories. Which worked fine until subdirectories got moved and replaced by symlinks, which is when I started asking "so what paths can I follow that will reliably be there in both current and future releases"? Which is what I'm trying to document now.
Quoted 4 lines
You can't
just run 'find' on sysfs and expect to not get caught in endless loops, as the goal of the different parts of sysfs is to be able to start in one place, and figure out all of the needed information from there.
I'm trying to document what those paths are.
People keep wanting to tell me about future plans that aren't merged yet. A year ago the future plans were directories becoming symlinks, now the plans are /sys/subsystem, I'm sure in a year there will be new future plans. I'd really like not to have to change existing code to still work with them, hence an attempt to document the API I _SHOULD_ use so that I don't have to.
If I discard what's there now and document the current future plans that aren't merged yet, how do I know that they won't themselves be ripped out a year after that?
Quoted 2 lines
For example, if you have a device, you can get the subsystem it belongs to, the driver bound to it, and other stuff.
Can you get the default name of the device currently encoded as the last element of the path that "DEVPATH" points to (ala /class/mem/zero), but which I won't necessarily get if DEVPATH starts to point to /device/12345/:00 as some people keep saying DEVPATH should point to?
It's not encoded as one of the hotplug variables, other than extractable from DEVPATH in a way that may or may not continue to work...
Quoted 8 lines
If you start with a
driver, you can get the devices it binds. Can you see the circle already?So, you need to watch what you are trying to find, and if you do that, you never will get caught in circles. We never had that problem in udev at all, as we just work with what was passed to us, not blindly try to walk the whole sysfs tree.
You wrote both the sysfs code and the udev code. You wrote both sides of the export, changed both sides of the export fairly freely, and you know what you intended to do and what was merely an implementation artifact.
Quoted 3 lines
Please use the proper context in order to get the information you need. And at all times, a directory can turn into a symlink in order to keep the same information possible.
I am aware of that, therefore I need to look at a known set of paths, which is what I'm trying to document now.
Quoted 11 lines
Quoted 9 lines
(It uses the same code to traverse down
beneath/sys/blockand/sys/classto look for "dev" entries.) This works fine up through the 2.6.20 in ubuntu 7.04, where everything in/sys/class/tty/*is still a subdirectory. But in 2.6.22,/sys/class/tty/*is all symlinks. Hence the code that was working before changed, due to something that worked fine for a couple years but broke because it wasn't considered part of a stable API.Which part of this is "total nonsense"?
Your code :)
*shrug* There was a better way to do it back in 2005 without reading your mind?
Quoted 10 lines
Quoted 8 lines
Quoted 2 lines
until you have proven to have read
the udevtrigger code,I read the udev code when it was first posted. I read it again 20 versions later, and read it again 20 versions after that. I couldn't COMPILE the darn thing for its first ~40 releases, the code got ripped out and re-written several times, I watched as it grew and then threw out libsysfs.
You could not build it? Why not?
I don't clearly remember the details from two years ago, but after glancing at my blog http://landley.net/notes-2005.html#27-10-2005 I vaguely recall that it had large numbers of undocumented environmental dependencies and I got sick of playing whack-a-mole installing packages, plus it had no documentation whatsoever and required a complicated configuration file to the point it was actually _easier_ to write a shell script to parse sysfs directly. (Trying that got results in about 15 minutes. Staring at udev for half a day did not.)
Plus I remember downloading different early versions of udev and finding things hugely rewritten between each update to the point that trying to pick it apart until it stabilized was a waste of time.
I also remember thinking that libsysfs sounded like a horrible idea (having your own copy of a shared library in the source tree defeats the purpose of having a shared library). It was something that bothered me about the design from day one, libsysfs was in theory an external library but udev included its own copy, which made as much sense to me as including its own copy of glibc. Here's the problem back in 2003:
http://www.ussg.iu.edu/hypermail/linux/kernel/0311.2/0716.html
Here's you replying to me on that topic in 2005:
http://www.ussg.iu.edu/hypermail/linux/kernel/0512.1/0617.html
Quoted 2 lines
Did you send me a patch for this
problem that was major enough to keep you from using the project?
That problem was only one reason I didn't use the project. I objected to most of the design, at some length, in this post back in 2005:
http://lkml.org/lkml/2005/10/30/189
Quoted 7 lines
Quoted 2 lines
So essentially you're saying "well read it again, we've finally got it right now"?
Not at all, we are saying to look at how to achive what you are trying to achieve by reading a very small and well documented .c file (530 lines with comments) that explains how to easily and quickly achieve what you are trying to duplicate.
Ok. I note that most of the stuff I was objecting to in 2005 wouldn't _fit_ in 530 lines, and my first gripe in my blog post was lack of documentation and unnecessary complexity, neither of which appear to be the case now...
Quoted 4 lines
Heck, I did the same thing in a bash script for the Gentoo startup code a while back that still works, but has ordering issues that the .c file fixes up. Hence it was dropped for the replacement that we are pointing you at.
Ok.
Quoted 8 lines
Quoted 8 lines
Quoted 2 lines
and got a clue how to do stuff reliably, and get
the basic knowledge needed to document it.Because talking to you and having you email me the notes from this conversation did not provide the basic knowledge needed to document hotplug and firmware loading. Nor did asking for feedback on the document I wrote up. Thanks ever so much.
Quoted 7 lines
Quoted 2 lines
I point out that udev changes from version to version, so that running an old version of udev against a new kernel has been known to break.
Hence the Documenation/CHANGES file documents the version that is needed. Right now it shows a version that is over a year and a half old. I do know that you can get away with running versions that are even older than that if you want to, but it's not really recommended.
Udev appears to have changed, for the better. I'm still uncomfortable with "the implementation is the specification".
Quoted 7 lines
Quoted 5 lines
Udev was more or less completely rewritten three times while I was still paying attention to it. Reading the udev code and seeing what it's doing struck me as about as likely to reveal a stable API as reading the kernel source, or experimenting with sysfs from userspace. (Both of which I've _done_ at various points, and it keeps changing.)
The development cycle of udev has nothing to do with sysfs here.
I'm trying to figure out how to decouple them, yes. :)
Quoted 8 lines
Other
than the fact that we learned how to interact with a kernel interface that directly exposes the internals of the kernel itself, something that no one had done before. In learning how to handle such major changes, udev has changed in order to support zillions of devices, small memory footprints, and lightening fast speed, all changes that required big udev internal changes, but had _nothing_ to do with the kernel and/or sysfs.
Arriving at simple can take a lot of work. You don't have to tell me that. :)
Quoted 8 lines
Quoted 3 lines
Are you saying that the current version of udev will work with all future kernels, and thus if I can figure out what udev is doing today, I can just document that as the stable API?
If you want to figure out how to create a dynamic /dev filesystem that can handle persistance device names, dynamic rules created by users, zillions of devices on small and big systems, small footprint, and very quick speed, then yes, read the udev source code.
I did all that but the persistent device names in mdev, without ever referring to udev (after bad experiences with it in 2005), although I no longer maintain any part of busybox.
Quoted 4 lines
What is the goal of this document here? You start out trying to explain the hotplug interface, and then get side tracked into talking about creating a dynamic
/dev/filesystem in userspace and then ramble on into how sysfs is layed out. These are three separate things
Various people asked me for documentation on hotplug and firmware loading, and what I know how to do with hotplug (because I had to work out how in 2005, and I'd like to nail down the approved way of doing it) is create /dev nodes.
Quoted 5 lines
While the act of creating such a /dev filesystem does have something to do with the hotplug/uevent interface of the kernel, it isn't reliant on it. And the layout of sysfs also doesn't really have much affect on the creation of such a /dev filesystem, as udev proves (it works just fine without sysfs even being mounted.)
Via netlink events? I vaguely recall a thread about deferring all the "add" events until after a netlink daemon was up, but I thought you needed sysfs for that.
Quoted 5 lines
If you want to just document the hotplug/uevent interface then do that.
If you want to document sysfs and it's structure, do that too, after reading the existing documentation and understanding that.
I've read the existing documentation that I've seen. Unfortunately I'm too jetlagged at the moment to finish collating it, and I need to go look at this cleaned-up no-longer-scary udev when I'm awake.
Quoted 3 lines
thanks,
greg k-h
Rob
Signature · 2 lines
"One of my most productive days was throwing away 1000 lines of code." - Ken Thompson.
Quoted 11 lines · Rob Landley
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/blockmakes 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.
thanks,
greg k-h
Quoted 9 lines · Greg KH
Quoted 8 lines · Rob Landley
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.
Quoted 7 lines
Quoted 3 lines
There's a kernel config option to make symlinks from the old location.
/sys/blockmakes 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?
Quoted 3 lines
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
Signature · 2 lines
"One of my most productive days was throwing away 1000 lines of code." - Ken Thompson.
Quoted 5 lines · Rob Landley
Nope. If you recurse down under
/sys/classfollowing symlinks, you go into an endless loop bouncing off of/sys/devicesand getting pointed back. If you don't follow symlinks, it works fine up until about 2.6.20 at which point things that were previously directories BECAME symlinks because the directories got moved, and it all broke.
I have no idea what you're doing.
Quoted 2 lines
Which is why I want it documented where to look for these suckers. Just give me ONE STABLE WAY TO FIND THIS INFORMATION, PLEASE.
See Documentation/sysfs-rules.txt.
Quoted 7 lines
This document is trying to document just enough information to make hotplug work using sysfs (which includes firmware loading if necessary).
Quoted 1 line
(And how about referring to
Documentation/sysfs-rules.txt?)Because there isn't one in 2.6.22, and I've been writing this file on and off for a month as I tracked down various bits of information?
That was a _suggestion_.
Quoted 4 lines
I know. I'm just trying to show people how to do it. Notice that this script doesn't DO anything, it just dumps the variables (and proves
that/sys/hotpluggot called). You're worried about the scalability of a debugging script.
If you use bash scripts as examples, people will write bash scripts.
Quoted 6 lines
(Rummage) Seems to be "add, remove, change, online, offline, move"?
I can list 'em. Now I'm vaguely curious what generates online and offline events (MII transciever state transitions on a network card, or does this have to do with power saving modes?) And I have no idea what the difference between "change" and "move" is....
"change" - something about the device has changed "move" - the device is in a different position in the tree now
You may want to grep for the usage...
Quoted 17 lines
Quoted 8 lines
Quoted 5 lines
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.
If you are doing mknod, you need three pieces of information:
1) Major, 2) Minor, 3) Block or Char device. That's pretty much it. If you're trying to populate /dev you need that info.Quoted 4 lines
Quoted 3 lines
SUBSYSTEM
If this is "block", it's a block device. Anything else is a char
device.
Quoted 7 lines
Quoted 2 lines
No. For devices, SUBSYSTEM may be the class (like '
scsi_device') or the bus (like 'pci').Do you make a /dev node for either one?
I'm trying to, at minimum, document what you pass to mknod. I consider it important to know.
The problem is that your information is wrong. Imagine someone reading this document, thinking "cool, I'll create a char node if SUBSYSTEM!=block" and subsequently getting completely confused about all those SUBSYSTEM==pci events.
Quoted 9 lines
Quoted 6 lines
Quoted 4 lines
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.
I've had it suggest drivers for devices that didn't have any loaded, and I had it _not_ specify drivers for devices that were loaded. (I checked.)
The code disagrees with you. If a driver matches and probing succeeds, it will be specified, otherwise not. Maybe you were checking the wrong devices?
Quoted 8 lines
Ah yes. I replied to that when it was first posted. It's still "here's a list of things NOT to do" rather then telling you what you CAN do. I'm trying to document what you can do.
Useful documentation is not "Doing THIS is forbidden. Doing THIS is forbidden. Doing THIS is forbidden. What are you allowed to do? Guess! Oh, and anything I didn't explicitly mention could change at any time. Have fun."
It _does_ specify what you may rely on. Don't rely on anything else.
Quoted 2 lines
Sysfs CAN export a stable API. It may only be a subset of what it's exporting, but it can still do so.
And that is exactly what sysfs-rules.txt is doing. I don't understand your problem.
If you think that getting this information from sysfs-rules.txt could be made easier, do a patch against it.
Quoted 10 lines · Cornelia Huck
On Wed, 18 Jul 2007 13:39:53 -0400,
Quoted 5 lines · Rob Landley
Nope. If you recurse down under
/sys/classfollowing symlinks, you go into an endless loop bouncing off of/sys/devicesand getting pointed back. If you don't follow symlinks, it works fine up until about 2.6.20 at which point things that were previously directories BECAME symlinks because the directories got moved, and it all broke.I have no idea what you're doing.
See the email to kay sievers. In 2.6.14 following symlinks hit an endless /sys/block/hda/device/block/device/block/device/block... This has changed since, like much of sysfs, but in the absence of either a spec or a stable API there's no guarantee it won't reoccur.
Quoted 4 lines
Quoted 2 lines
Which is why I want it documented where to look for these suckers. Just give me ONE STABLE WAY TO FIND THIS INFORMATION, PLEASE.
See
Documentation/sysfs-rules.txt.
Ok:
Paragraph 1: "It's not stable."
Paragraph 2: "It's not stable."
Paragraph 3: If you really really need to access it directly... Paragraph 4: DO NOT DO $XXX.
Paragraph 5: Expect it to be mounted at /sys
Paragraph 6: DO NOT DO $XXX. (Specficially, the way you were distinguishing between block and char devices? Don't do that. No, we won't tell you what to replace it with, keep reading.)
So far, not exactly gripping reading.
Paragraph 7: What a devpath is. Ok, is it just me or does it say that applications shouldn't use the symlinks in sysfs? Why are they there, then?
Paragraph 8: The kernel has a name for the device.
Paragraph 9: Subsystem is a string. What it means, we leave for you to guess. Paragraph 10: Driver is the name of a driver. (Does this mean a driver is currently loaded and handling the device, or that the kernel is suggesting a driver based on something like PCI ID, through the kind of mechanism that used to be used to request module loading? Experimentally, it looks like the first, which makes sense but isn't specified. Does something like /sys/class/mem/zero or have a driver? Experimentally, no, it hasn't got a device link.)
Paragraph 11: Atributes, and yet more DO NOT DO $XXX. It took me three reads of that to figure out they probably meant "Attributes belong to a device, don't confuse the attributes of another device with attributes of this device." (Following _which_ device symlink?)
Ok, back up. /sys/devices does not contain all the information necessary to populate /dev, because it hasn't got things like
ramdisks, /dev/zero, /dev/console which are THERE in sysfs, which may or may not be supported by the kernel (the kernel might have ramdisk support, might not). These things could also, in future, have their major and minor numbers dynamically (even randomly) assigned. That's been discussed on this list.
I'm not trying to document /sys/devices. I'm trying to document hotplug, populating /dev, and things like firmware loading that fall out of that. This requires use of sysfs, and I'm only trying to document as much of sysfs as you need to do that. I'm not documenting stuff
like /sys/devices/system/cpu.
The consensus so far is "the udev implementation is the spec", except I watched the udev implementation change rather a lot before I stopped tracking it, and saw a number of people complain on this list about things breaking when they upgraded the kernel but not udev.
Back to reading the document:
Quoted 1 line
- Properties of parent devices never belong into a child device.
Belong into?
Quoted 2 lines
Always look at the parent devices themselves for determining device context properties.
For determining?
What was the original language of this document?
Quoted 2 lines
If the device 'eth0' or 'sda' does not have a
"driver"-link, then this device does not have a driver.
Again, whether they mean "the kernel was not built with a driver that can handle this device" or "no driver is currently loaded and handling this device". It _sounds_ like "this device is not supported by Linux", which probably isn't what they meant.
Quoted 1 line
Never copy any property of the parent-device into a child-device.
I note that the only mention made so far of parent-child relationships in devices is in terms of "don'ts". I assume they're talking about how a partition can be the child of a block device, and a network controller card can be the child of a pci bus device?
Ah, I see. The next paragraph is on hierarchy, yet doesn't actually explain anything, other than to imply that the device hierarchy being fully represented there is a dream to be achieved sometime in the future but not necessarily the truth with today's kernels, because stuff is still being _moved_ into /sys/devices.
Quoted 3 lines
- Classification by subsystem
There are currently three places for classification of devices:
/sys/block,/sys/classand/sys/bus.
So if somebody wants to write code that runs on a current kernel, they have no alternative but to look in these three places. If future kernels want to be compatible with current kernels, they must retain these three places as symlinks or some such. Therefore, these three places form an API, and that's what I'm trying to document.
Quoted 3 lines
It is planned that these will
not contain any device-directories themselves, but only flat lists of symlinks pointing to the unified/sys/devicestree.
So presumably /sys/class/mem/zero and friends will show up under /sys/devices at some point, but that path should still find the thing via symlinks. So moving it is an implementation detail irrelevant to documenting an api through with /dev can be populated by a userspace application.
Quoted 3 lines
Assuming /sys/class/<subsystem> and /sys/bus/<subsystem>, or
/sys/blockand/sys/class/blockare not interchangeable, is a bug in the application.
So the fact Kay didn't mention /sys/class/block when we talked at OLS is a simple oversight. You know, the type of feedback I was asking for was "This is wrong, you should change it to X", rather than "this is wrong, you're stupid". I already _know_ I don't understand every nook and cranny of the Linux kernel, and that this is unlikely to change, thanks. If you were wondering why writing documentation is like pulling teeth, and that there isn't enough of it, now you know.
Anyway, it seems like the paragraph I quoted can be rephrased "The contents of /sys/class/* and /sys/bus/* are interchangeable, and the contents of /sys/block and /sys/class/block are interchangeable." However, this implies that /sys/class/block and /sys/block are interchangeable because /sys/class/block is part of /sys/class/*...
Quoted 4 lines
- Block
The converted block-subsystem at/sys/class/block, or/sys/subsystem/blockwill contain the links for disks and partitions at the same level, never in a hierarchy.
A) The converted block subsystem isn't in 2.6.22 or any earlier kernel, thus software has to be written to use the current /sys/block path to be compatible with any kernel actually deployed anywhere today. And if you've got the old mechanism working, what's the advantage of the new one?
B) This is the first mention (by implication only) that the current /sys/block might have a hierarchy under it. The point of this document is obviously not to document how it works _today_. The point of mine _is_.
Quoted 2 lines
- "device"-link and <subsystem>:<kernel name>-links Never depend on the "device"-link.
This paragraph is a big "DO NOT DO $XXX" repeated six times, and I note that this link was the reason I made mdev not follow symlinks in the first place.
Quoted 2 lines
Never depend on the class-specific links back to the
/sys/classdirectory.
DO NOT DO $XXX.
Quoted 2 lines
Never depend on a specific parent device position in the devpath, or the chain of parent devices.
DO NOT DO $XXX.
Although I am curious about this paragraph. Not that I'm really trying to document this bit, but "You must always request the parent device you are looking for by its subsystem value." does not explain HOW to request a specific device by its subsystem value. According to the earlier bullet point about "subsystem", it's a simple string "(block, tty, pci, ...)" that seems to indicate a category of devices rather than a specific device...
And that is the end of the document.
Now, where in it did it explain how to determine whether a device is a block device or a char device when attempting to use the major and minor numbers extracted from sysfs to do a mknod?
Quoted 8 lines
Quoted 7 lines
This document is trying to document just enough information to make hotplug work using sysfs (which includes firmware loading if necessary).
Quoted 1 line
(And how about referring to
Documentation/sysfs-rules.txt?)Because there isn't one in 2.6.22, and I've been writing this file on and off for a month as I tracked down various bits of information?
Quoted 8 lines
That was a _suggestion_.
Quoted 4 lines
I know. I'm just trying to show people how to do it. Notice that this script doesn't DO anything, it just dumps the variables (and proves that
/sys/hotpluggot called). You're worried about the scalability of a debugging script.If you use bash scripts as examples, people will write bash scripts.
And they'll find out, as I did, that it scales horribly. (Scanning /dev with a shell script took about 15 seconds last time I tried it, which was 2 laptops ago...)
I can document scalability issues, though. (That and sequencing are why the netlink method exists in the first place...)
I was writing up a "history of hotplug" document that got trashed when my laptop died last month, but when I get around to rewriting it I plan to mention how /sys/hotplug was originally a big shell script and why they stopped doing that:
http://lwn.net/2001/0830/a/diet-hotplug.php3
Quoted 11 lines
Quoted 6 lines
(Rummage) Seems to be "add, remove, change, online, offline, move"?
I can list 'em. Now I'm vaguely curious what generates online and offline events (MII transciever state transitions on a network card, or does this have to do with power saving modes?) And I have no idea what the difference between "change" and "move" is....
"change" - something about the device has changed "move" - the device is in a different position in the tree now
You may want to grep for the usage...
I did, thanks.
Quoted 5 lines
Quoted 5 lines
Quoted 2 lines
No. For devices, SUBSYSTEM may be the class (like '
scsi_device') or the bus (like 'pci').Do you make a /dev node for either one?
Quoted 7 lines
Quoted 2 lines
I'm trying to, at minimum, document what you pass to mknod. I consider it important to know.
The problem is that your information is wrong. Imagine someone reading this document, thinking "cool, I'll create a char node if SUBSYSTEM!=block" and subsequently getting completely confused about all those SUBSYSTEM==pci events.
They get major and minor numbers for SUBSYSTEM==pci?
Is there something wrong other than the need to filter out /sys/class/block if that starts contaminating the pool of char devices (which it isn't in current kernels)?
Quoted 7 lines
Quoted 7 lines
Quoted 6 lines
Quoted 4 lines
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.
Quoted 7 lines
Quoted 3 lines
I've had it suggest drivers for devices that didn't have any loaded, and I had it _not_ specify drivers for devices that were loaded. (I checked.)
The code disagrees with you. If a driver matches and probing succeeds, it will be specified, otherwise not. Maybe you were checking the wrong devices?
Could be. Or I could have been looking at an old kernel.
Quoted 10 lines
Quoted 8 lines
Ah yes. I replied to that when it was first posted. It's still "here's a list of things NOT to do" rather then telling you what you CAN do. I'm trying to document what you can do.
Useful documentation is not "Doing THIS is forbidden. Doing THIS is forbidden. Doing THIS is forbidden. What are you allowed to do? Guess! Oh, and anything I didn't explicitly mention could change at any time. Have fun."
It _does_ specify what you may rely on. Don't rely on anything else.
Ok, how do I find a list of:
A) all char devices in the system.
B) all block devices currently in the system
C) whether a device that just got hotplugged (and I just got a hotplug event for) is a char or block device so I can call mknod? (I know how to tell when there's no device node for it, there's no "dev" entry or no MAJOR=/MINOR= variables. But when I do have those, how do I tell if they refer to a block or a char device?
Are you saying there's no reliable way to do that, or are you saying the document explains how to do that?
Quoted 4 lines
Quoted 2 lines
Sysfs CAN export a stable API. It may only be a subset of what it's exporting, but it can still do so.
And that is exactly what sysfs-rules.txt is doing.
What does going on about buggy apps have to do with listing what you're allowed to do? Listing things not to do isn't the same as listing what you're allowed to do, unless attempting to arrive at an API document by process of elimination.
Quoted 1 line
I don't understand your problem.
I've noticed. I suspect I phrased my goals unclearly.
Quoted 2 lines
If you think that getting this information from sysfs-rules.txt could be made easier, do a patch against it.
I'm trying to document hotplug, which includes scanning to initially populate /dev, and firmware loading. Documenting a portion of sysfs is a side effect of documenting hotplug.
Rob
Signature · 2 lines
"One of my most productive days was throwing away 1000 lines of code." - Ken Thompson.
Quoted 5 lines · Rob Landley
Ok, back up.
/sys/devicesdoes not contain all the information necessary to populate /dev, because it hasn't got things like
ramdisks,/dev/zero,/dev/consolewhich are THERE in sysfs, which may or may not be supported by the kernel (the kernel might have ramdisk support, might not).
Welcome to 2007:
$ ls /sys/devices/virtual/mem/ full kmem kmsg mem null port random urandom zero $ ls /sys/devices/virtual/tty/ console tty12 tty19 tty25 tty31 tty38 tty44 tty50 tty57 tty63 ptmx tty13 tty2 tty26 tty32 tty39 tty45 tty51 tty58 tty7 tty tty14 tty20 tty27 tty33 tty4 tty46 tty52 tty59 tty8 tty0 tty15 tty21 tty28 tty34 tty40 tty47 tty53 tty6 tty9 tty1 tty16 tty22 tty29 tty35 tty41 tty48 tty54 tty60 tty10 tty17 tty23 tty3 tty36 tty42 tty49 tty55 tty61 tty11 tty18 tty24 tty30 tty37 tty43 tty5 tty56 tty62
I suggest you take a close look at the kernel before making statements like the above :)
Quoted 2 lines
These things could also, in future, have their major and minor numbers dynamically (even randomly) assigned. That's been discussed on this list.
I tried that once, it will require some core api kernel changes and a lot of infrastrucure work to get that to work properly. Not that it will never happen in the future, but it's just not a trivial change at the moment...
thanks,
greg k-h
Quoted 20 lines · Greg KH
Quoted 5 lines · Rob Landley
Ok, back up.
/sys/devicesdoes not contain all the information necessary to populate /dev, because it hasn't got things like
ramdisks,/dev/zero,/dev/consolewhich are THERE in sysfs, which may or may not be supported by the kernel (the kernel might have ramdisk support, might not).Welcome to 2007:
$ ls /sys/devices/virtual/mem/ full kmem kmsg mem null port random urandom zero $ ls /sys/devices/virtual/tty/ console tty12 tty19 tty25 tty31 tty38 tty44 tty50 tty57 tty63 ptmx tty13 tty2 tty26 tty32 tty39 tty45 tty51 tty58 tty7 tty tty14 tty20 tty27 tty33 tty4 tty46 tty52 tty59 tty8 tty0 tty15 tty21 tty28 tty34 tty40 tty47 tty53 tty6 tty9 tty1 tty16 tty22 tty29 tty35 tty41 tty48 tty54 tty60 tty10 tty17 tty23 tty3 tty36 tty42 tty49 tty55 tty61 tty11 tty18 tty24 tty30 tty37 tty43 tty5 tty56 tty62
Quoted 2 lines
I suggest you take a close look at the kernel before making statements like the above :)
I did:
landley@dell:/sys/devices$ ls /sys/devices/virtual ls: /sys/devices/virtual: No such file or directory landley@dell:/sys/devices$ cat /proc/version Linux version 2.6.20-16-generic (root@terranova) (gcc version 4.1.2 (Ubuntu 4.1.2-0ubuntu4)) #2 SMP Thu Jun 7 20:19:32 UTC 2007
I.E. Ubuntu 7.04, stock. The most recent release, using a 2.6.20 kernel.
I see that what you're talking about is in 2.6.22. Back when I started writing my document in May, I forgot to check 2.6.22.
Quoted 8 lines
Quoted 3 lines
These things could also, in future, have their major and minor numbers dynamically (even randomly) assigned. That's been discussed on this list.
I tried that once, it will require some core api kernel changes and a lot of infrastrucure work to get that to work properly. Not that it will never happen in the future, but it's just not a trivial change at the moment...
Understood.
Quoted 3 lines
thanks,
greg k-h
Rob
Signature · 2 lines
"One of my most productive days was throwing away 1000 lines of code." - Ken Thompson.
On Mon, 23 Jul 2007 19:26:54 -0400,
Rob Landley <[email protected]> wrote:
<tons of stuff>
Sorry, that's way too much for me to bother reading. I'd look at any patches against the existing documentation, though. But I'll stop looking at this thread, there's too much ranting for my taste in there.
Quoted 4 lines · Rob Landley
I'm not trying to document
/sys/devices. I'm trying to document hotplug, populating /dev, and things like firmware loading that fall out of that. This requires use of sysfs, and I'm only trying to document as much of sysfs as you need to do that.
Like I stated before, you do not need to even have sysfs mounted to have a dynamic /dev.
And why do you need to document populating /dev dynamically? udev already solves this problem for you, it's not like people are going off and reinventing udev for their own enjoyment would not at least look at how it solves this problem first.
To do otherwise would be foolish :)
Firmware loading is fine to document if you wish to do so. But again, why? We already have multiple userspace programs that provide this feature for them. Perhaps you want to document how to add firmware to a system in order for these different programs to pick them up?
Or perhaps you want to document how to add this kind of functionality to your kernel driver so that it can handle firmware loading by using the firmware interface that the kernel provides?
If you just want to document the hotplug/uevent api, then do just that. However I think you are overreaching with your scope here and getting mighty confused in the process.
thanks,
greg k-h
Quoted 6 lines · Rob Landley
Quoted 2 lines
Always look at the parent devices themselves for determining device context properties.
For determining?
What was the original language of this document?
Ok, that's just being mean, cut it out right now if you ever want my help again.
I'll gladly accept patches for this document that is in the kernel tree now if you want to send them. But criticizing the grammer of a document with statements like this one gets you no where and is damm rude.
I suggest you start this thread over if you want my feedback, I'm not going to respond anymore to this one.
greg k-h
Quoted 10 lines · Greg KH
Quoted 6 lines · Rob Landley
Quoted 2 lines
Always look at the parent devices themselves for determining device context properties.
For determining?
What was the original language of this document?
Ok, that's just being mean, cut it out right now if you ever want my help again.
You're right, that was uncalled for and I apologize.
I got a little on edge from some of Kay's earlier comments ala:
Quoted 2 lines
You seem to miss the the very basic skills to collect the needed information to do the job of documenting something.
Probably combined with jetlag. I'll stop posting until I get some sleep.
Rob
Signature · 2 lines
"One of my most productive days was throwing away 1000 lines of code." - Ken Thompson.
Quoted 5 lines · Rob Landley
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? :)
A lot. :)
Quoted 10 lines
Note, I still need to actually confirm that
/sbin/hotplugcan be called from initramfs by a statically linked device to load firmware before init gets spawned. It should work, and was explicitly discussed as a design goal a year or two back, but it might need a bugfix patch to actually, you know, _work_.(
P.S. I'd cc Kay Sievers on this, but he's still spam-blocking my email. Thanks to Kay for answer lots of questions about this at OLS, and to Fank Sorenson who wrote a netlink implementation of mdev back in 2005 that I dug up to figure out how that part works.)
hotplug and firmware loading with sysfs.
========================================
The 2.6.x Linux kernels export a device tree through sysfs, which is a synthetic filesystem generally mounted at "/sys". Among other things, this filesystem tells userspace what hardware is available, so userspace tools (such as udev or mdev) can dynamically populate a "/dev" directory with device nodes representing the currently available hardware.
@@ It exposes the current state of kernel devices, it's not necessarily @@ related to any hardware.
Notification when hardware is inserted or removed is provided by the hotplug mechanism. Linux provides two hotplug interfaces: /sbin/hotplug and netlink.
@@ Same here, it's about kernel device creation and not hardware "insertion".
The combination of sysfs and hotplug obsoleted the older "devfs", which was removed from the 2.6.16 kernel.
@@ Udev replaced devfs, not hotplug or sysfs.
Device nodes:
=============
Sysfs exports major and minor numbers for device nodes with which to populate /dev via mknod(2). These major and minor numbers are found in files named "dev", which contain two colon separated ascii decimal numbers followed by exactly one newline. I.E.
$ cat /sys/class/mem/zero/dev 1:5
Note that the name of the directory containing a dev entry is usually the traditional name for the device node. (The above entry is for "/dev/zero".)
Entires for block devices are found at the following locations:
/sys/block/*/dev
/sys/block/*/*/dev
Entries for char devices are found at the following locations:
/sys/bus/*/devices/*/dev
/sys/class/*/*/dev
@@ Wrong! /sys/class/block/* will be block-devices. Please read the stuff mentioned @@ in the document Greg has posted. You _must_ always determine the subsystem. @@ This rule is plain wrong.
A very simple bash script to populate /dev from /sys (without addressing ownership or permissions of the resulting /dev nodes) might look like:
#!/bin/bash
# Populate block devices
for i in /sys/block/*/dev /sys/block/*/*/dev
do
if [ -f $i ]
then
MAJOR=$(sed 's/:.*//' < $i)
MINOR=$(sed 's/.*://' < $i)
DEVNAME=$(echo $i | sed -e 's@/dev@@' -e 's@.*/@@')
mknod /dev/$DEVNAME b $MAJOR $MINOR
fi
done# Populate char devices
for i in /sys/bus/*/devices/*/dev /sys/class/*/*/dev
do
if [ -f $i ]
then
MAJOR=$(sed 's/:.*//' < $i)
MINOR=$(sed 's/.*://' < $i)
DEVNAME=$(echo $i | sed -e 's@/dev@@' -e 's@.*/@@')
mknod /dev/$DEVNAME c $MAJOR $MINOR
fi
done@@ That will fail badly. And again, please don't confuse @@ "class" and "char", they are not the same, and never have been.
Hotplug:
========
The hotplug mechanism asynchronously notifies userspace when hardware is inserted, removed, or undergoes a similar significant state change. Linux provides two interfaces to hotplug; the kernel can spawn a usermode helper process, or it can send a message to an existing daemon listening to a netlink socket.
-- Usermode helper
The usermode helper hotplug mechanism spawns a new process to handle each hotplug event. Each such helper process belongs to the root user (UID 0) and is a child of the init task (PID 1). The kernel spawns one process per hotplug event, supplying environment variables to each new process describing that particular hotplug event. By default the kernel spawns instances of "/sbin/hotplug", but this default can be changed by writing a new path into "/proc/sys/kernel/hotplug" (assuming /proc is mounted).
@@ Are you sure it's a child of init?
A simple bash script to record variables from hotplug events might look like:
#!/bin/bash
env >> /filename
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.
@@ That negative dentries will exist, is no reason not to disable it. @@ Almost no system is using /sbin/hotplug anymore, so I don't see the @@ point of this sentence. If you don't need to, why run all the code @@ and let the kernel clone a process that is know to fail? @@ Suggesting that, just doesn't make sense.
-- Netlink
A daemon listening to the netlink socket receives a packet of data for each hotplug event, containing the same information a usermode helper would receive in environment variables.
The netlink packet contains a set of null terminated text lines. Each line but the first contains a KEYWORD=VALUE pair defining a hotplug event variable. The first line of the netlink packet combines the $ACTION and $DEVPATH values, separated by an @ (at sign).
Here's a C program to print hotplug nelink events to stdout:
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/poll.h>
#include <sys/socket.h>
#include <sys/types.h>
#include <unistd.h>
#include <linux/types.h>
#include <linux/netlink.h>
void die(char *s)
{
write(2,s,strlen(s));
exit(1);
}int main(int argc, char *argv[])
{
struct sockaddr_nl nls;
struct pollfd pfd;
char buf[512];
// Open hotplug event netlink socket
memset(&nls,0,sizeof(struct sockaddr_nl));
nls.nl_family = AF_NETLINK;
nls.nl_pid = getpid();
nls.nl_groups = -1;@@ You are not supposed to listen to anything else than group 1!
pfd.events = POLLIN;
pfd.fd = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_KOBJECT_UEVENT);
if (pfd.fd==-1)
die("Not root\n");
// Listen to netlink socket
if (bind(pfd.fd, (void *)&nls, sizeof(struct sockaddr_nl)))
die("Bind failed\n");
while (-1!=poll(&pfd, 1, -1)) {
int i, len = recv(pfd.fd, buf, sizeof(buf), MSG_DONTWAIT);
if (len == -1) //die("recv\n");
// Print the data to stdout.
i = 0;
while (i<len) {
printf("%s\n", buf+i);
i += strlen(buf+i)+1;
}
}
die("poll\n");
// Dear gcc: shut up.
return 0;
}Hotplug event variables:
========================
Every hotplug event should provide at least the following variables:
ACTION
The current hotplug action: "add" to add the device... [QUESTION: Full list of actions?]
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.
@@ Devpathes are not defined what to start with, it's wrong to document @@ it that way. If you don't have the event env or start from @@ /sys/{class,bus,block,subsystem}), devices have a "subsystem" link, @@ which is the only valid way to retrieve the "subsystem" from sysfs.
SUBSYSTEM
If this is "block", it's a block device. Anything else is a char device.
The following variables are also provided for some devices:
MAJOR and MINOR
If these are present, a device node can be created in /dev for this device. Some devices (such as network cards) don't generate a /dev node.
[QUESTION: Any way to get the default name?]
@@ The directory name is the default name.
DRIVER
If present, a suggested driver (module) for handling this device. No relation to whether or not a driver is currently handling the device.
@@ Wrong, it's the currently bound driver, no "suggestion" at all. @@ And don't confuse modules and drivers they are not always the same @@ strings. Some modules have multiple drivers.
INTERFACE and IFINDEX
When SUBSYSTEM=net, these variables indicate the name of the interface and a unique integer for the interface. (Note that "INTERFACE=eth0" could be paired with "IFINDEX=2" because eth0 isn't guaranteed to come before lo and the count doesn't start at 0.)
@@ What could be paired?
FIRMWARE
The system is requesting firmware for the device. See "Firmware loading" below.
Injecting events into hotplug via "uevent":
===========================================
Events can be injected into the hotplug mechanism through sysfs via the "uevent" files. Each directory in sysfs containing a "dev" file should also contain a "uevent" file.
@@ The name of the action should be written to "uevent". @@ Currently only "add" is supported.
Note that in newer kernel versions, "uevent" is readable. Reading from uevent provides the set of "extra" variables associated with this event.
Firmware loading
================
If the hotplug variable FIRMWARE is set, the kernel is requesting firmware for a device (identified by $DEVPATH). To provide the firmware to the kernel, do the following:
echo 1 > /sys/$DEVPATH/loading
cat /path/to/$FIRMWARE > /sys/$DEVPATH/data
echo 0 > /sys/$DEVPATH/loading
Note that "echo -1 > /sys/$DEVPATH/loading" will cancel the firmware load and return an error to the kernel, and /sys/class/firmware/timeout contains a timeout (in seconds) for firmware loads.
See Documentation/firmware_class for more information.
Loading firmware for statically linked devices
==============================================
An advantage of the usermode helper hotplug mechanism is that if initramfs contains an executable /sbin/hotplug, it can be called even before the kernel runs init. This allows /sbin/hotplug to supply firmware (out of initramfs) to statically linked device drivers. (The netlink mechanism requires a daemon to listen to a socket, and such a daemon cannot be spawned before init runs.)
@@ There is no difference between /sbin/hotplug and netlink, this @@ advantage simply doesn't exist. Most systems run udevd in initramfs. @@
@@ The only advantage of /sbin/hotplug is that you run easily OOM, because @@ of too many event running at the same time. :)
For licensing reasons, binary-only firmware should not be linked into the kernel image, but instead placed in an externally supplied initramfs which can be passed to the Linux kernel through the old initrd mechanism. See Documentation/filesystems/ramfs-rootfs-initramfs.txt for details.
@@ Firmware licensing issues definitely don't belong here.
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
@@ You still seems to misunderstand what this all is about. @@ It's not that we "believe" something, it's that sysfs is @@ a construct where the location of information can move around @@ at runtime.
@@ It's a dynamic tree of devices, and not values at a defined @@ location. That makes it totally different from anything else. @@ The next second, a device can be somewhere else and that @@ is nothing you could compare to any other API, so we need @@ different rules here. It's not about "believing in something". @@ Again, please read the document Greg posted.
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.
@@ Only well defined ways of retrieving information from sysfs are @@ expected to produce predictable results. It's a dump of the kernel @@ state and you can't read reliably it without following some rules.
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.
@@ It's not debugging, but you have to reach this information @@ in a specific way. There is not much information we don't need. @@ But we can't just expect it to look the same, even on the same @@ system, a second later sysfs can look differently, devices can get @@ renamed or move around dynamically.
I'm very unhappy with this text. I think you need to rework most this document to be useful. You really can't ignore the rules to access the information in sysfs. You try to point things down to a static behavior, but that isn't what sysfs is about, or what it provides.
Please try to understand the intention of the document Greg posted, it may be wrong in the wording, but it still contains a lot of things you will need to describe to document sysfs.
Maybe I misunderstand you, and you only want to describe how to reliably initialize /dev from sysfs, but then please change the title of the document and describe what the udev or HAL code is doing at coldplug time, instead of calling it "Documentation for sysfs". And again, I already told you that a lot of times, read the udevtrigger code, how to "get all devices" properly, your example scripts are wrong.
Thanks,
Kay