Specifying GPIO Information for Devices

Device의 gpios property

GPIO property 이름은 `[<name>-]gpios` 형식이어야 하며 `<name>`은 device에서 이 GPIO가 맡는 목적입니다. `<name>`이 없는 `gpios`도 호환성을 위해 유효하지만 새 binding에서는 허용되지 않습니다. `[<name>-]gpio` 형식도 오래된 binding에서 사용했으나 폐기되었고 호환성 목적으로만 지원하므로 새 binding에서 사용하면 안 됩니다.

GPIO property는 하나 이상의 GPIO phandle을 담을 수 있지만 예외적인 경우에만 여러 개를 담아야 합니다. Device가 서로 다른 기능의 GPIO를 여러 개 사용한다면 각각 의미 있는 이름의 별도 property로 참조합니다. 여러 GPIO가 parallel data line처럼 같은 기능을 수행할 때만 GPIO array를 허용합니다. 각 `gpios` property의 정확한 목적은 해당 device의 device tree binding에 문서화해야 합니다.

다음 예제는 device enable과 bit-banged data signal에 사용하는 GPIO pin을 설명합니다. `&gpio1`은 GPIO 하나를 두 cell로 나타냅니다. 첫 cell은 GPIO line의 local offset이고, 두 번째 cell은 active-low inversion이나 open-drain 요청 같은 consumer flag입니다. 이 2-cell 방식이 권장됩니다.

gpio1: gpio1 {
        gpio-controller;
        #gpio-cells = <2>;
};
[...]

data-gpios = <&gpio1 12 0>,
             <&gpio1 13 0>,
             <&gpio1 14 0>,
             <&gpio1 15 0>;

각 specifier cell의 정확한 의미는 controller별로 다르며 해당 controller의 device tree binding에 문서화해야 합니다. 그래도 2-cell 방식을 강하게 권장합니다. 대부분의 controller는 마지막 cell에 generic flag bitfield를 두므로 가능한 경우 `include/dt-bindings/gpio/gpio.h`의 macro를 사용합니다.

node {
        enable-gpios = <&qe_pio_e 18 GPIO_ACTIVE_HIGH>;
};

`GPIO_ACTIVE_HIGH`는 0이므로 이 예제의 gpio-specifier `18 0`은 GPIO pin 18과 `qe_pio_e` GPIO controller가 받는 flag를 encode합니다.

마지막 cell의 선택 표준 bitfield에서 bit 0은 polarity로 0이 active high, 1이 active low입니다. Bit 1은 wiring으로 0이 push-pull, 1이 single-ended입니다. Bit 2는 single-ended 종류로 0이 open-source, 1이 open-drain입니다. 원문은 각각 push-pull, single-ended triode, open collector의 Wikipedia 설명을 참조합니다.

Bit 3은 sleep/low-power mode에서 output 유지 여부로, 0이면 유지해야 하고 1이면 상태를 잃어도 됩니다. Bit 4는 pull-up resistor로 0이면 비활성, 1이면 활성입니다. Bit 5는 pull-down resistor로 0이면 비활성, 1이면 활성입니다. Bit 4와 5는 단순 on/off pull 제어 hardware에만 적용하며 더 정교한 pull 설정은 pin control binding으로 나타내야 합니다.

GPIO specifier polarity 권장 방식

GPIO specifier에는 GPIO polarity가 active-high인지 active-low인지 나타내는 flag가 있어야 합니다. 이 flag는 GPIO controller에서 device의 논리적으로 asserted된 값을 만들거나, input에서는 그 값을 나타내는 물리 level을 표현해야 합니다. 논리적 assertion의 정확한 정의는 device binding이 정합니다.

Board가 GPIO controller와 device 사이에서 signal을 반전한다면 gpio-specifier는 device pin의 signal과 반대인 controller 쪽 물리 level을 나타냅니다.

Device의 signal polarity를 설정할 수 있다면 binding은 두 방식 중 하나를 택해야 합니다. 첫 방식은 signal의 단일 static polarity를 정하고 binding을 사용하는 software가 device를 그 polarity로 설정할 것으로 기대하는 것입니다. 이 static polarity는 binding별 DT property가 결정하는 방식이 권장되며, 또는 DT binding 자체가 고정해서 정의할 수 있습니다.

Polarity를 gpio-specifier에서 유도해서는 안 됩니다. 그렇게 하면 device 안에서 설정 가능한 signal polarity와 board-level signal inversion이라는 서로 독립된 두 개념을 DT가 각각 표현할 수 없기 때문입니다.

두 번째 방식은 device signal polarity의 한 option을 선택해 binding에 문서화하는 것입니다. 이 경우 gpio-specifier는 device가 그 polarity option으로 설정되었다고 가정한 controller 쪽 signal polarity를 나타냅니다. Software가 반대 polarity를 생성하거나 수신하도록 device를 program한다면 GPIO controller의 signal을 올바르게 해석하고 반전하는 책임도 software에 있습니다.

GPIO controller, line 수와 이름

모든 GPIO controller node에는 빈 `gpio-controller` property와 gpio-specifier의 cell 수를 나타내는 정수 `#gpio-cells` property가 모두 있어야 합니다.

일부 SoC는 GPIO bank 개념을 사용합니다. GPIO bank는 silicon die에 있는 hardware IP core instance이며 일반적으로 연속 I/O address range로 programmer에게 노출됩니다. 같은 IP block을 여러 번 재사용해 합성한 hardware를 반영하여 각 bank를 device tree의 개별 gpio-controller node로 노출하는 것이 일반적입니다.

선택 `ngpios`는 사용 가능한 GPIO slot 가운데 실제 사용하는 slot 수입니다. 예를 들어 register가 32 bit지만 물리 pin은 18개뿐이라면 `ngpios = <18>`로 local offset 0~17만 사용한다고 driver에 알립니다. 같은 IP가 32, 18, 12 line 설계에 재사용되는 경우를 처리합니다.

사용 가능한 GPIO가 offset 0부터 처음 N개가 아니라면 `gpio-reserved-ranges` tuple로 사용할 수 없는 GPIO의 start와 size를 지정합니다.

선택 `gpio-line-names`는 controller에서 나가는 GPIO line 이름의 string array입니다. On-board device에 연결된 line에는 package pin 이름보다 system에서 의미 있는 producer 이름을 사용합니다. `MMC-CD`, `Red LED Vdd`, `ethernet reset`은 좋은 이름이지만 특정 device에 고정 연결된 line을 `GPIO0`이라 부르는 것은 좋지 않습니다.

Raspberry Pi 40-pin header처럼 general-purpose header에 연결되어 특정 device에 고정되지 않은 line은 실제로 board 문서에 표시된 pin 번호나 header 이름을 사용할 수 있으며 가능하면 unique해야 합니다. Board가 pin 8을 그렇게 표기한다면 `pin8 [gpio14/uart0_txd]`는 괜찮지만 SoC reference manual의 이름인 `PortB_24`, SoC pad/package 이름, kernel 내부 software construct로 만든 이름은 권장하지 않습니다.

용도가 정의되지 않은 line은 placeholder 대신 빈 string `""`을 사용합니다. DTS file에 naming convention과 이름 출처를 설명하는 comment를 추가하는 것이 이상적입니다. 이름은 전달된 array의 왼쪽부터 line offset 0에서 차례로 할당되며, 이름 수가 `ngpios`보다 적은 불완전한 array는 마지막으로 제공된 유효 line index까지만 사용합니다.

gpio-controller@00000000 {
        compatible = "foo";
        reg = <0x00000000 0x1000>;
        gpio-controller;
        #gpio-cells = <2>;
        ngpios = <18>;
        gpio-reserved-ranges = <0 4>, <12 2>;
        gpio-line-names = "MMC-CD", "MMC-WP", "VDD eth", "RST eth", "LED R",
                "LED G", "LED B", "Col A", "Col B", "Col C", "Col D",
                "Row A", "Row B", "Row C", "Row D", "NMI button",
                "poweroff", "reset";
}

GPIO hog 정의

GPIO chip은 GPIO hog definition을 포함할 수 있습니다. GPIO hogging은 gpio-controller driver의 probe 과정에서 GPIO를 자동으로 request하고 configure하는 mechanism입니다. 각 hog는 GPIO controller의 child node로 나타냅니다.

필수 `gpio-hog`는 child node가 GPIO hog임을 표시합니다. `gpios`는 영향을 줄 각 GPIO의 ID와 flag 등을 저장하며 parent GPIO controller의 `#gpio-cells` 수의 정수배만큼 cell을 포함해야 합니다.

`input`, `output-low`, `output-high` 가운데 하나만 적용합니다. 여러 property가 있으면 이 순서로 검색하여 처음 match한 설정을 사용합니다. `input`은 input 방향, `output-low`는 low 값의 output, `output-high`는 high 값의 output으로 설정합니다. 선택 `line-name`은 GPIO label이며 없으면 node 이름을 사용합니다.

예제는 SoC의 두 GPIO bank를 gpio-controller node로 정의합니다. Bank A의 line 6을 `foo-bar-gpio`라는 output-low hog로 만들고 bank E는 별도 hog 없이 controller만 선언합니다.

qe_pio_a: gpio-controller@1400 {
        compatible = "fsl,qe-pario-bank-a", "fsl,qe-pario-bank";
        reg = <0x1400 0x18>;
        gpio-controller;
        #gpio-cells = <2>;

        line_b-hog {
                gpio-hog;
                gpios = <6 0>;
                output-low;
                line-name = "foo-bar-gpio";
        };
};

qe_pio_e: gpio-controller@1460 {
        compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
        reg = <0x1460 0x18>;
        gpio-controller;
        #gpio-cells = <2>;
};

GPIO와 pin controller 상호작용

GPIO controller가 제공하는 GPIO 일부 또는 전부는 pin controller를 통해 package pin으로 routing될 수 있습니다. 이렇게 하면 해당 pin을 GPIO와 다른 function 사이에서 mux할 수 있으며 silicon 설계에서 흔히 사용하는 방식입니다.

숫자 GPIO range

어느 GPIO가 어느 pin controller의 어느 pin에 대응하는지 표현할 수 있습니다. `gpio-ranges`는 pin controller local number space의 pin을 GPIO controller local number space의 line에 mapping하는 discrete range 집합입니다.

형식은 pin controller phandle, GPIO controller offset, pin controller offset, pin 수의 네 항목입니다.

The format is: <[pin controller phandle], [GPIO controller offset],
                [pin controller offset], [number of pins]>;

GPIO controller offset은 range definition을 포함하는 GPIO controller node를 기준으로 합니다. Phandle이 참조하는 pin controller node는 `pinctrl/pinctrl-bindings.txt`를 따라야 합니다. 각 offset은 0부터 N까지이고, 필요한 경우 pin 하나짜리 mapping을 여러 개 둘 수 있지만 실제로는 연속 구간을 discrete set으로 묶는 경우가 많습니다.

gpio-ranges = <&foo 0 20 10>, <&bar 10 50 20>;

이 예제에서 pin controller `foo`의 pin 20~29는 GPIO line 0~9에, `bar`의 pin 50~69는 GPIO line 10~29에 mapping됩니다.

qe_pio_e: gpio-controller@1460 {
        #gpio-cells = <2>;
        compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
        reg = <0x1460 0x18>;
        gpio-controller;
        gpio-ranges = <&pinctrl1 0 20 10>, <&pinctrl2 10 50 20>;
};

상세 예제에서도 단일 GPIO controller의 GPIO 0~9가 `pinctrl1` pin 20~29에, GPIO 10~29가 `pinctrl2` pin 50~69에 routing됩니다.

이름 있는 pin group의 GPIO range

Pin group이 가장 쉽고 편리한 mapping이라면 GPIO range에 named pin group을 사용할 수 있습니다. Named pin group을 사용할 때 `<pinctrl-base>`와 `<count>`는 모두 0이어야 합니다.

`gpio-ranges-group-names`에는 range마다 정확히 하나의 string이 있어야 합니다. 각 string은 해당 pin controller에 정의된 pin group 이름입니다. Range의 pin/GPIO line 수는 그 pin group의 pin 수이며, group 크기는 device tree가 아니라 구현에서 정의합니다.

숫자 range와 named pin group을 섞으면 `gpio-ranges-group-names`에서 숫자 pin range에 대응하는 string은 비워야 합니다.

gpio_pio_i: gpio-controller@14b0 {
        #gpio-cells = <2>;
        compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
        reg = <0x1480 0x18>;
        gpio-controller;
        gpio-ranges =                        <&pinctrl1 0 20 10>,
                                        <&pinctrl2 10 0 0>,
                                        <&pinctrl1 15 0 10>,
                                        <&pinctrl2 25 0 0>;
        gpio-ranges-group-names =        "",
                                        "foo",
                                        "",
                                        "bar";
};

원문 예제는 두 pin controller를 참조하는 세 GPIO range가 정의되었다고 설명합니다. `pinctrl1`의 GPIO range는 pin number로 정의하고 `pinctrl2`의 range는 `foo`, `bar`라는 pin group으로 정의합니다. 숫자 entry에 대응하는 group name은 빈 string입니다.

이 binding의 이전 version은 `gpio-ranges`가 참조하는 모든 pin controller node에 `#gpio-range-cells = <3>`을 요구했습니다. 이 요구 사항은 폐기되었지만 오래된 device tree에는 호환성을 위해 남아 있을 수 있고, 오래된 software와 호환되어야 하는 새 device tree에서도 여전히 필요할 수 있습니다.