Documentation/userspace-api/gpio/sysfs.rst

Source file repositories/reference/linux-study-clean/Documentation/userspace-api/gpio/sysfs.rst

File Facts

System
Linux kernel
Corpus path
Documentation/userspace-api/gpio/sysfs.rst
Extension
.rst
Size
6608 bytes
Lines
172
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

GPIO Sysfs Interface for Userspace
==================================

.. warning::
   This API is obsoleted by the chardev.rst and the ABI documentation has
   been moved to Documentation/ABI/obsolete/sysfs-gpio.

   New developments should use the chardev.rst, and existing developments are
   encouraged to migrate as soon as possible, as this API will be removed
   in the future.

   This interface will continue to be maintained for the migration period,
   but new features will only be added to the new API.

The obsolete sysfs ABI
----------------------
Platforms which use the "gpiolib" implementors framework may choose to
configure a sysfs user interface to GPIOs. This is different from the
debugfs interface, since it provides control over GPIO direction and
value instead of just showing a gpio state summary. Plus, it could be
present on production systems without debugging support.

Given appropriate hardware documentation for the system, userspace could
know for example that GPIO #23 controls the write protect line used to
protect boot loader segments in flash memory. System upgrade procedures
may need to temporarily remove that protection, first importing a GPIO,
then changing its output state, then updating the code before re-enabling
the write protection. In normal use, GPIO #23 would never be touched,
and the kernel would have no need to know about it.

Again depending on appropriate hardware documentation, on some systems
userspace GPIO can be used to determine system configuration data that
standard kernels won't know about. And for some tasks, simple userspace
GPIO drivers could be all that the system really needs.

.. note::
   Do NOT abuse sysfs to control hardware that has proper kernel drivers.
   Please read Documentation/driver-api/gpio/drivers-on-gpio.rst
   to avoid reinventing kernel wheels in userspace.

   I MEAN IT. REALLY.

Paths in Sysfs
--------------
There are three kinds of entries in /sys/class/gpio:

   -	Control interfaces used to get userspace control over GPIOs;

   -	GPIOs themselves; and

   -	GPIO controllers ("gpio_chip" instances).

That's in addition to standard files including the "device" symlink.

The control interfaces are write-only:

    /sys/class/gpio/

	"export" ...
		Userspace may ask the kernel to export control of
		a GPIO to userspace by writing its number to this file.

		Example:  "echo 19 > export" will create a "gpio19" node
		for GPIO #19, if that's not requested by kernel code.

	"unexport" ...
		Reverses the effect of exporting to userspace.

		Example:  "echo 19 > unexport" will remove a "gpio19"
		node exported using the "export" file.

Annotation

Implementation Notes