Documentation/admin-guide/sysfs-rules.rst

Source file repositories/reference/linux-study-clean/Documentation/admin-guide/sysfs-rules.rst

File Facts

System
Linux kernel
Corpus path
Documentation/admin-guide/sysfs-rules.rst
Extension
.rst
Size
9655 bytes
Lines
193
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

Rules on how to access information in sysfs
===========================================

The kernel-exported sysfs exports internal kernel implementation details
and depends on internal kernel structures and layout. It is agreed upon
by the kernel developers that the Linux kernel does not provide a stable
internal API. Therefore, there are aspects of the sysfs interface that
may not be stable across kernel releases.

To minimize the risk of breaking users of sysfs, which are in most cases
low-level userspace applications, with a new kernel release, the users
of sysfs must follow some rules to use an as-abstract-as-possible way to
access this filesystem. The current udev and HAL programs already
implement this and users are encouraged to plug, if possible, into the
abstractions these programs provide instead of accessing sysfs directly.

But if you really do want or need to access sysfs directly, please follow
the following rules and then your programs should work with future
versions of the sysfs interface.

- Do not use libsysfs
    It makes assumptions about sysfs which are not true. Its API does not
    offer any abstraction, it exposes all the kernel driver-core
    implementation details in its own API. Therefore it is not better than
    reading directories and opening the files yourself.
    Also, it is not actively maintained, in the sense of reflecting the
    current kernel development. The goal of providing a stable interface
    to sysfs has failed; it causes more problems than it solves. It
    violates many of the rules in this document.

- sysfs is always at ``/sys``
    Parsing ``/proc/mounts`` is a waste of time. Other mount points are a
    system configuration bug you should not try to solve. For test cases,
    possibly support a ``SYSFS_PATH`` environment variable to overwrite the
    application's behavior, but never try to search for sysfs. Never try
    to mount it, if you are not an early boot script.

- devices are only "devices"
    There is no such thing like class-, bus-, physical devices,
    interfaces, and such that you can rely on in userspace. Everything is
    just simply a "device". Class-, bus-, physical, ... types are just
    kernel implementation details which should not be expected by
    applications that look for devices in sysfs.

    The properties of a device are:

    - devpath (``/devices/pci0000:00/0000:00:1d.1/usb2/2-2/2-2:1.0``)

      - identical to the DEVPATH value in the event sent from the kernel
        at device creation and removal
      - the unique key to the device at that point in time
      - the kernel's path to the device directory without the leading
        ``/sys``, and always starting with a slash
      - all elements of a devpath must be real directories. Symlinks
        pointing to /sys/devices must always be resolved to their real
        target and the target path must be used to access the device.
        That way the devpath to the device matches the devpath of the
        kernel used at event time.
      - using or exposing symlink values as elements in a devpath string
        is a bug in the application

    - kernel name (``sda``, ``tty``, ``0000:00:1f.2``, ...)

      - a directory name, identical to the last element of the devpath
      - applications need to handle spaces and characters like ``!`` in
        the name

    - subsystem (``block``, ``tty``, ``pci``, ...)

      - simple string, never a path or a link

Annotation

Implementation Notes