Userspace용 GPIO sysfs 인터페이스

폐기 경고와 이전 지침

GPIO sysfs API는 `chardev.rst`의 character device API로 대체되었으며 ABI 명세는 `Documentation/ABI/obsolete/sysfs-gpio`로 이동했습니다.

새 개발은 character device API를 사용해야 합니다. 기존 개발도 이 API가 향후 제거될 예정이므로 가능한 빨리 이전하는 것이 권장됩니다.

이전 기간에는 sysfs 인터페이스를 유지보수하지만 새 기능은 새 character device API에만 추가됩니다. 따라서 이 문서는 신규 설계 지침이 아니라 레거시 동작의 보존 설명입니다.

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.

구형 sysfs ABI의 목적과 사용 한계

`gpiolib` 구현 프레임워크를 사용하는 platform은 선택적으로 GPIO sysfs userspace 인터페이스를 구성할 수 있습니다. 상태 요약만 표시하는 debugfs와 달리, sysfs는 GPIO 방향과 값을 제어하며 debugging 지원이 없는 production system에도 존재할 수 있습니다.

정확한 hardware 문서가 있다면 userspace는 특정 전역 GPIO 번호의 용도를 알고 export한 뒤 방향과 출력 값을 조작할 수 있습니다. 예를 들어 firmware update 동안 flash write-protect line을 잠시 해제하고 작업 뒤 다시 활성화하는 절차가 가능합니다.

Kernel이 알 수 없는 board configuration을 GPIO 입력으로 읽거나 아주 단순한 userspace GPIO driver를 만드는 용도로도 쓰였습니다. 그러나 올바른 kernel driver가 존재하는 hardware를 sysfs에서 직접 제어해서는 안 됩니다.

원문은 `Documentation/driver-api/gpio/drivers-on-gpio.rst`를 읽고 kernel 기능을 userspace에서 재구현하지 말라고 강하게 경고합니다. 이 제한은 장치 소유권, 동시성, 전원 관리와 오류 복구를 kernel driver가 책임져야 하기 때문입니다.

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.

/sys/class/gpio와 export 제어

`/sys/class/gpio`에는 userspace 제어를 획득하는 control interface, export된 개별 GPIO, GPIO controller인 `gpio_chip` instance의 세 종류 항목이 있습니다. 표준 `device` symlink 같은 공통 sysfs 파일도 함께 존재합니다.

Write-only `export` 파일에 GPIO 번호를 쓰면 kernel code가 이미 요청하지 않은 GPIO를 userspace에 export합니다. 예를 들어 `echo 19 > export`는 `/sys/class/gpio/gpio19` node를 만듭니다.

Write-only `unexport` 파일은 그 동작을 되돌립니다. `echo 19 > unexport`는 `export`로 만든 `gpio19` node를 제거합니다.

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.

gpioN의 direction, value, edge, active_low

개별 signal은 `/sys/class/gpio/gpioN/` 경로에 나타납니다. `direction`은 `in` 또는 `out`을 읽고 쓸 수 있습니다. `out`은 초기 값을 low로 설정하며, glitch를 피하려면 `low` 또는 `high`를 직접 써서 출력 방향과 초기 값을 한 번에 구성합니다.

Kernel이 방향 변경을 지원하지 않거나 kernel code가 export하면서 userspace 방향 변경을 명시적으로 허용하지 않았다면 `direction` 파일은 존재하지 않습니다.

`value`는 inactive 0 또는 active 1을 읽습니다. 출력 GPIO에서는 쓸 수도 있고 0이 아닌 값은 active로 처리됩니다. Interrupt 입력과 `edge`가 구성된 경우 `value` 파일을 `poll(2)`할 수 있습니다.

`poll(2)`에서는 `POLLPRI | POLLERR`를 요청하고 `select(2)`에서는 descriptor를 `exceptfds`에 둡니다. 알림 뒤에는 `pread(2)`로 offset 0을 읽거나, `lseek(2)`로 처음으로 이동한 뒤 읽거나, 파일을 닫고 다시 열어 새 값을 읽습니다.

`edge`는 `none`, `rising`, `falling`, `both` 중 하나이며 어떤 signal edge가 `value`의 `poll(2)`을 깨울지 정합니다. Interrupt 생성 입력으로 구성할 수 있는 pin에서만 이 파일이 존재합니다.

`active_low`는 0 또는 1입니다. 0이 아닌 값을 쓰면 읽기와 쓰기 모두에서 `value`의 논리 극성을 뒤집습니다. 이미 설정된 edge와 이후 설정할 rising/falling의 `poll(2)` 동작도 이 논리 극성을 따릅니다.

GPIO signals have paths like /sys/class/gpio/gpio42/ (for GPIO #42)
and have the following read/write attributes:

    /sys/class/gpio/gpioN/

	"direction" ...
		reads as either "in" or "out". This value may
		normally be written. Writing as "out" defaults to
		initializing the value as low. To ensure glitch free
		operation, values "low" and "high" may be written to
		configure the GPIO as an output with that initial value.

		Note that this attribute *will not exist* if the kernel
		doesn't support changing the direction of a GPIO, or
		it was exported by kernel code that didn't explicitly
		allow userspace to reconfigure this GPIO's direction.

	"value" ...
		reads as either 0 (inactive) or 1 (active). If the GPIO
		is configured as an output, this value may be written;
		any nonzero value is treated as active.

		If the pin can be configured as interrupt-generating interrupt
		and if it has been configured to generate interrupts (see the
		description of "edge"), you can poll(2) on that file and
		poll(2) will return whenever the interrupt was triggered. If
		you use poll(2), set the events POLLPRI and POLLERR. If you
		use select(2), set the file descriptor in exceptfds. After
		poll(2) returns, use pread(2) to read the value at offset
		zero. Alternatively, either lseek(2) to the beginning of the
		sysfs file and read the new value or close the file and
		re-open it to read the value.

	"edge" ...
		reads as either "none", "rising", "falling", or
		"both". Write these strings to select the signal edge(s)
		that will make poll(2) on the "value" file return.

		This file exists only if the pin can be configured as an
		interrupt generating input pin.

	"active_low" ...
		reads as either 0 (false) or 1 (true). Write
		any nonzero value to invert the value attribute both
		for reading and writing. Existing and subsequent
		poll(2) support configuration via the edge attribute
		for "rising" and "falling" edges will follow this
		setting.

gpiochipN controller 속성과 번호 찾기

GPIO controller는 `/sys/class/gpio/gpiochipN/` 경로를 사용하며 N은 이 chip이 관리하는 첫 전역 GPIO 번호입니다. 속성은 모두 read-only입니다.

`base`는 N과 같은 첫 GPIO 번호, `label`은 진단용 이름으로 유일하지 않을 수 있으며, `ngpio`는 controller가 관리하는 GPIO 개수입니다. 따라서 번호 범위는 N부터 `N + ngpio - 1`까지입니다.

GPIO 전역 번호는 daughtercard, base board, card stack 구성에 따라 안정적이지 않을 수 있습니다. 이 경우 board 문서와 schematic, `gpiochip` node 정보를 함께 사용해 원하는 signal의 올바른 번호를 찾아야 합니다.

GPIO controllers have paths like /sys/class/gpio/gpiochip42/ (for the
controller implementing GPIOs starting at #42) and have the following
read-only attributes:

    /sys/class/gpio/gpiochipN/

	"base" ...
		same as N, the first GPIO managed by this chip

	"label" ...
		provided for diagnostics (not always unique)

	"ngpio" ...
		how many GPIOs this manages (N to N + ngpio - 1)

Board documentation should in most cases cover what GPIOs are used for
what purposes. However, those numbers are not always stable; GPIOs on
a daughtercard might be different depending on the base board being used,
or other cards in the stack. In such cases, you may need to use the
gpiochip nodes (possibly in conjunction with schematics) to determine
the correct GPIO number to use for a given signal.

Kernel code의 export 관리

Kernel driver는 먼저 `gpio_request()`로 GPIO를 요청한 뒤 `gpiod_export(struct gpio_desc *desc, bool direction_may_change)`로 sysfs에 노출할 수 있습니다. `direction_may_change`로 userspace의 방향 변경 허용 여부를 제어합니다.

`gpiod_unexport(struct gpio_desc *desc)`는 export를 되돌립니다. `gpiod_export_link(struct device *dev, const char *name, struct gpio_desc *desc)`는 다른 sysfs 위치에서 export된 GPIO node로 가는 symlink를 만듭니다.

명시적 export는 중요한 system state를 userspace가 실수로 손상하지 못하도록 driver가 방향 정책을 제한하면서 debugging 실험이나 board support package의 상시 interface를 제공할 수 있게 합니다.

Export 뒤 driver는 자신의 device 아래에 설명적인 이름의 symlink를 만들어 전역 `gpioN` 번호보다 의미 있는 접근 경로를 제공할 수 있습니다.

Exporting from Kernel code
--------------------------
Kernel code can explicitly manage exports of GPIOs which have already been
requested using gpio_request()::

	/* export the GPIO to userspace */
	int gpiod_export(struct gpio_desc *desc, bool direction_may_change);

	/* reverse gpiod_export() */
	void gpiod_unexport(struct gpio_desc *desc);

	/* create a sysfs link to an exported GPIO node */
	int gpiod_export_link(struct device *dev, const char *name,
		      struct gpio_desc *desc);

After a kernel driver requests a GPIO, it may only be made available in
the sysfs interface by gpiod_export(). The driver can control whether the
signal direction may change. This helps drivers prevent userspace code
from accidentally clobbering important system state.

This explicit exporting can help with debugging (by making some kinds
of experiments easier), or can provide an always-there interface that's
suitable for documenting as part of a board support package.

After the GPIO has been exported, gpiod_export_link() allows creating
symlinks from elsewhere in sysfs to the GPIO sysfs node. Drivers can
use this to provide the interface under their own device in sysfs with
a descriptive name.