Linux configfs GPIO simulator | Linux 6.18.37

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

Configfs device와 bank

gpio-sim.rst:1-81

platform device, GPIO bank, line, hog의 configfs group과 attribute를 구성하고 `live`로 수명주기를 제어합니다.

Device Tree와 sysfs

gpio-sim.rst:82-137

`gpio-simulator` compatible의 DT 예와 각 가상 line의 `pull`, `value` attribute를 정리합니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기

1 .. SPDX-License-Identifier: GPL-2.0-or-later

3 Configfs GPIO Simulator

4 =======================

6 The configfs GPIO Simulator (gpio-sim) provides a way to create simulated GPIO

7 chips for testing purposes. The lines exposed by these chips can be accessed

8 using the standard GPIO character device interface as well as manipulated

9 using sysfs attributes.

11 Creating simulated chips

12 ------------------------

14 The gpio-sim module registers a configfs subsystem called ``'gpio-sim'``. For

15 details of the configfs filesystem, please refer to the configfs documentation.

17 The user can create a hierarchy of configfs groups and items as well as modify

18 values of exposed attributes. Once the chip is instantiated, this hierarchy

19 will be translated to appropriate device properties. The general structure is:

21 **Group:** ``/config/gpio-sim``

23 This is the top directory of the gpio-sim configfs tree.

25 **Group:** ``/config/gpio-sim/gpio-device``

27 **Attribute:** ``/config/gpio-sim/gpio-device/dev_name``

29 **Attribute:** ``/config/gpio-sim/gpio-device/live``

31 This is a directory representing a GPIO platform device. The ``'dev_name'``

32 attribute is read-only and allows the user-space to read the platform device

33 name (e.g. ``'gpio-sim.0'``). The ``'live'`` attribute allows to trigger the

34 actual creation of the device once it's fully configured. The accepted values

35 are: ``'1'`` to enable the simulated device and ``'0'`` to disable and tear

36 it down.

38 **Group:** ``/config/gpio-sim/gpio-device/gpio-bankX``

40 **Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/chip_name``

42 **Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/num_lines``

44 This group represents a bank of GPIOs under the top platform device. The

45 ``'chip_name'`` attribute is read-only and allows the user-space to read the

46 device name of the bank device. The ``'num_lines'`` attribute allows to specify

47 the number of lines exposed by this bank.

49 **Group:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY``

51 **Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/name``

53 **Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/valid``

55 This group represents a single line at the offset Y. The ``valid`` attribute

56 indicates whether the line can be used as GPIO. The ``name`` attribute allows

57 to set the line name as represented by the 'gpio-line-names' property.

59 **Item:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog``

61 **Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog/name``

63 **Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog/direction``

65 This item makes the gpio-sim module hog the associated line. The ``'name'``

66 attribute specifies the in-kernel consumer name to use. The ``'direction'``

67 attribute specifies the hog direction and must be one of: ``'input'``,

68 ``'output-high'`` and ``'output-low'``.

70 Inside each bank directory, there's a set of attributes that can be used to

71 configure the new chip. Additionally the user can ``mkdir()`` subdirectories

72 inside the chip's directory that allow to pass additional configuration for

73 specific lines. The name of those subdirectories must take the form of:

74 ``'line<offset>'`` (e.g. ``'line0'``, ``'line20'``, etc.) as the name will be

75 used by the module to assign the config to the specific line at given offset.

77 Once the configuration is complete, the ``'live'`` attribute must be set to 1 in

78 order to instantiate the chip. It can be set back to 0 to destroy the simulated

79 chip. The module will synchronously wait for the new simulated device to be

80 successfully probed and if this doesn't happen, writing to ``'live'`` will

81 result in an error.

83 Simulated GPIO chips can also be defined in device-tree. The compatible string

84 must be: ``"gpio-simulator"``. Supported properties are:

86 ``"gpio-sim,label"`` - chip label

88 Other standard GPIO properties (like ``"gpio-line-names"``, ``"ngpios"`` or

89 ``"gpio-hog"``) are also supported. Please refer to the GPIO documentation for

90 details.

92 An example device-tree code defining a GPIO simulator:

94 .. code-block :: none

96 gpio-sim {

97 compatible = "gpio-simulator";

99 bank0 {

100 gpio-controller;

101 #gpio-cells = <2>;

102 ngpios = <16>;

103 gpio-sim,label = "dt-bank0";

104 gpio-line-names = "", "sim-foo", "", "sim-bar";

105 };

106

107 bank1 {

108 gpio-controller;

109 #gpio-cells = <2>;

110 ngpios = <8>;

111 gpio-sim,label = "dt-bank1";

112

113 line3 {

114 gpio-hog;

115 gpios = <3 0>;

116 output-high;

117 line-name = "sim-hog-from-dt";

118 };

119 };

120 };

121

122 Manipulating simulated lines

123 ----------------------------

124

125 Each simulated GPIO chip creates a separate sysfs group under its device

126 directory for each exposed line

127 (e.g. ``/sys/devices/platform/gpio-sim.X/gpiochipY/``). The name of each group

128 is of the form: ``'sim_gpioX'`` where X is the offset of the line. Inside each

129 group there are two attributes:

130

131 ``pull`` - allows to read and set the current simulated pull setting for

132 every line, when writing the value must be one of: ``'pull-up'``,

133 ``'pull-down'``

134

135 ``value`` - allows to read the current value of the line which may be

136 different from the pull if the line is being driven from

137 user-space

138

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

Configfs GPIO Simulator 개요

1-10

Configfs GPIO Simulator인 `gpio-sim`은 시험용 가상 GPIO chip을 만듭니다. 노출된 line은 표준 GPIO character device interface로 접근하고 sysfs attribute로 조작할 수 있습니다.

Configfs에서 가상 chip 구성

11-81

`gpio-sim` 모듈은 `gpio-sim`이라는 configfs subsystem을 등록합니다. 사용자는 configfs group과 item의 계층을 만들고 공개 attribute 값을 수정할 수 있습니다. chip을 instantiate하면 이 계층이 알맞은 device property로 변환됩니다.

configfs 경로	설명
/config/gpio-sim	gpio-sim configfs tree의 최상위 디렉터리입니다.
/config/gpio-sim/gpio-device	GPIO platform device 하나를 나타내는 디렉터리입니다.
/config/gpio-sim/gpio-device/dev_name	읽기 전용. `gpio-sim.0` 같은 platform device name을 보여 줍니다.
/config/gpio-sim/gpio-device/live	구성이 끝난 device를 실제로 만들거나 제거합니다. 1은 활성화, 0은 비활성화와 제거입니다.
/config/gpio-sim/gpio-device/gpio-bankX	최상위 platform device 아래의 GPIO bank를 나타냅니다.
/config/gpio-sim/gpio-device/gpio-bankX/chip_name	읽기 전용. bank device name을 보여 줍니다.
/config/gpio-sim/gpio-device/gpio-bankX/num_lines	bank가 노출할 line 수를 지정합니다.
/config/gpio-sim/gpio-device/gpio-bankX/lineY	offset Y의 line 하나를 나타냅니다.
/config/gpio-sim/gpio-device/gpio-bankX/lineY/name	`gpio-line-names` property에 표시할 line name을 설정합니다.
/config/gpio-sim/gpio-device/gpio-bankX/lineY/valid	해당 line을 GPIO로 사용할 수 있는지 표시합니다.
/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog	gpio-sim 모듈이 해당 line을 hog하도록 하는 item입니다.
/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog/name	커널 안에서 사용할 consumer name을 지정합니다.
/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog/direction	hog 방향을 `input`, `output-high`, `output-low` 중 하나로 지정합니다.

각 bank 디렉터리에는 새 chip을 구성할 attribute가 있습니다. 특정 line의 추가 구성은 chip 디렉터리 아래에 `mkdir()`로 `line<offset>`, 예를 들어 `line0`이나 `line20` 이름의 하위 디렉터리를 만들어 전달합니다. 모듈은 이름의 offset으로 구성을 적용할 line을 고릅니다.

구성이 끝나면 `live`를 1로 설정해 chip을 만들고 0으로 되돌려 제거합니다. 모듈은 새 가상 장치 probe가 성공할 때까지 동기적으로 기다리며 실패하면 `live` 쓰기가 오류를 반환합니다.

Device Tree에서 GPIO simulator 정의

82-121

가상 GPIO chip은 device tree에서도 정의할 수 있습니다. compatible 문자열은 반드시 `gpio-simulator`여야 합니다. `gpio-sim,label`은 chip label이며 `gpio-line-names`, `ngpios`, `gpio-hog` 같은 표준 GPIO property도 지원합니다.

GPIO simulator를 정의하는 device tree 예입니다.

gpio-sim {
    compatible = "gpio-simulator";

    bank0 {
        gpio-controller;
        #gpio-cells = <2>;
        ngpios = <16>;
        gpio-sim,label = "dt-bank0";
        gpio-line-names = "", "sim-foo", "", "sim-bar";
    };

    bank1 {
        gpio-controller;
        #gpio-cells = <2>;
        ngpios = <8>;
        gpio-sim,label = "dt-bank1";

        line3 {
            gpio-hog;
            gpios = <3 0>;
            output-high;
            line-name = "sim-hog-from-dt";
        };
    };
};

가상 line 조작

122-137

각 가상 GPIO chip은 device 디렉터리, 예를 들어 `/sys/devices/platform/gpio-sim.X/gpiochipY/` 아래에 노출한 line마다 별도 sysfs group을 만듭니다. group 이름은 line offset X를 사용한 `sim_gpioX` 형식입니다.

attribute	설명
pull	각 line의 현재 가상 pull 설정을 읽고 바꿉니다. 쓸 수 있는 값은 `pull-up`과 `pull-down`입니다.
value	line의 현재 값을 읽습니다. 사용자 공간이 line을 구동하면 pull 값과 다를 수 있습니다.