linux-3.3/Documentation/sysfs-rules.txt

1 Rules on how to access information in the Linux kernel sysfs
9 To minimize the risk of breaking users of sysfs, which are in most cases
23   implementation details in its own API. Therefore it is not better than
25   Also, it is not actively maintained, in the sense of reflecting the
28   violates many of the rules in this document.
39   interfaces, and such that you can rely on in userspace. Everything is
42   applications that look for devices in sysfs.
46       - identical to the DEVPATH value in the event sent from the kernel
48       - the unique key to the device at that point in time
56       - using or exposing symlink values as elements in a devpath string
57         is a bug in the application
61       - applications need to handle spaces and characters like '!' in
75         driver; copying the driver value in a child device context is a
76         bug in the application
79       - the files in the device directory or files below subdirectories
82         like the "device"-link, is a bug in the application
95 - Hierarchy in a single device tree
96   There is only one valid place in sysfs where hierarchy can be examined
98   It is planned that all device directories will end up in the tree
112   The devices belonging to a subsystem will create a symlink in the
122   /sys/block and /sys/class/block are not interchangeable is a bug in
128   at the same level, never in a hierarchy. Assuming the block subsystem to
129   contain only disks and not partition devices in the same flat list is
130   a bug in the application.
134   for the old layout, where class devices are not created in
136   device directory does not end in /sys/devices/, you can use the
137   "device"-link to find the parent devices in /sys/devices/. That is the
138   single valid use of the "device"-link; it must never appear in any
140   a device in /sys/devices/ is a bug in the application.
141   Accessing /sys/class/net/eth0/device is a bug in the application.
145   that class devices are not created in /sys/devices. If a device
147   may be used to find the child devices in /sys/class. That is the single
148   valid use of these links; they must never appear in any path as an
150   real child device directories in the /sys/devices tree is a bug in
154   directories live in /sys/devices.
157   Never depend on a specific parent device position in the devpath,
163   access the chain of parents is a bug in the application.