리눅스 Device Tree GPIO 기준 정리

본문 중간의 쿠팡 추천 상품 구매시 쿠팡 파트너스에서 일정액의 수수료를 제공받습니다.

Device Tree에서 GPIO는 장치가 어떤 GPIO controller의 몇 번째 라인을 어떤 극성으로 쓰는지 적는 방식입니다. reset-gpios = <&gpio0 12 GPIO_ACTIVE_LOW> 같은 값은 단순한 핀 번호가 아니라 phandle, gpio specifier, flag가 함께 해석되는 구조입니다.

2026년 8월 18일 기준 Devicetree Specification과 Linux 커널 GPIO binding 문서를 보면 검토 기준은 다섯 가지입니다. GPIO를 쓰는 장치 속성 이름, GPIO controller 노드의 필수 속성, #gpio-cells가 정하는 specifier 길이, active-low 같은 flag의 의미, 그리고 pin controller와 GPIO line의 대응 관계입니다.

Device Tree GPIO는 무엇을 연결하나

GPIO를 사용하는 장치 노드는 보통 reset-gpios, enable-gpios, wakeup-gpios처럼 용도를 드러내는 속성을 둡니다. Linux 커널의 공통 GPIO consumer schema는 enable, reset, powerdown, wakeup 계열 GPIO 이름을 문서화하고, 반전 신호에는 적절한 GPIO flag를 쓰라고 설명합니다.

값 안에는 GPIO controller를 가리키는 phandle과 controller binding이 정한 specifier가 들어갑니다. 그래서 DTS를 볼 때는 장치 노드의 속성만 보지 말고, 참조된 controller 노드까지 따라가야 합니다.

sensor@10 {
    compatible = "vendor,sensor";
    reg = <0x10>;
    reset-gpios = <&gpio0 12 GPIO_ACTIVE_LOW>;
};

gpio0: gpio-controller@1000 {
    compatible = "vendor,gpio";
    reg = <0x1000 0x100>;
    gpio-controller;
    #gpio-cells = <2>;
};

이 예시에서 &gpio0은 GPIO controller 노드입니다. 12 GPIO_ACTIVE_LOW는 그 controller가 정의한 #gpio-cells = <2> 기준의 specifier입니다. 첫 번째 셀이 line offset이고 두 번째 셀이 flag인 2셀 형식은 흔하지만, 최종 의미는 해당 controller binding을 기준으로 확인해야 합니다.

GPIO controller 노드에서 봐야 할 것

Linux 커널 GPIO binding은 GPIO controller 노드가 빈 boolean 속성인 gpio-controller와 정수 속성인 #gpio-cells를 가져야 한다고 설명합니다. #gpio-cells는 GPIO specifier 하나를 인코딩하는 데 필요한 셀 수를 정합니다.

항목	위치	확인 기준
gpio-controller	GPIO controller node	해당 노드가 GPIO controller임을 나타내는 boolean 속성입니다.
#gpio-cells	GPIO controller node	consumer 쪽 GPIO specifier 하나의 셀 개수를 정합니다.
ngpios	GPIO controller node	하드웨어 슬롯보다 실제 사용 가능한 GPIO 수가 적을 때 사용 범위를 알려줍니다.
gpio-reserved-ranges	GPIO controller node	사용하면 안 되는 line offset 범위를 표시합니다.
gpio-line-names	GPIO controller node	line offset 0부터 의미 있는 보드 수준 이름을 붙입니다.

ngpios는 레지스터 폭과 실제 보드에서 사용할 수 있는 라인 수가 다를 때 중요합니다. 예를 들어 드라이버가 32비트 레지스터를 다룰 수 있어도 보드에서 18개 라인만 연결되어 있다면, ngpios = <18>처럼 실제 사용 범위를 표시할 수 있습니다.

GPIO_ACTIVE_LOW는 왜 중요한가

GPIO flag는 전기적 신호와 소프트웨어의 논리 의미를 맞추는 역할을 합니다. reset 핀이 RESETN처럼 low일 때 동작하는 회로라면, DTS에서는 대개 GPIO_ACTIVE_LOW를 써서 드라이버가 논리적 assert와 실제 low 신호를 혼동하지 않게 합니다.

Linux 커널 GPIO binding은 대부분의 controller가 마지막 셀에 generic flag bitfield를 두며, 가능하면 include/dt-bindings/gpio/gpio.h의 매크로를 사용하라고 설명합니다. 이 문서의 표준 bitfield 설명에서 bit 0은 active high와 active low를 구분합니다.

다만 속성 이름만으로 극성을 단정하면 안 됩니다. reset-gpios가 반드시 active-low라는 뜻은 아니고, resetn이라는 회로 이름이 있어도 실제 board schematic과 binding이 우선입니다. DTS 검토에서는 신호 이름, 회로 극성, flag가 서로 일관되는지 확인해야 합니다.

 

 

gpio-line-names는 무엇을 적어야 하나

gpio-line-names는 GPIO line offset 0부터 순서대로 이름을 붙입니다. 커널 문서는 특정 on-board device로 연결된 라인에는 패키지 핀 이름보다 시스템에서 의미 있는 producer name을 쓰는 편이 낫다고 설명합니다. 예를 들어 MMC-CD, ethernet reset처럼 쓰임을 드러내는 이름이 더 유용합니다.

반대로 Raspberry Pi 40-pin header처럼 범용 헤더로 나가는 라인은 보드 문서에 있는 실제 핀 번호나 헤더 이름을 쓸 수 있습니다. 커널 내부 구조에서 만든 이름이나 SoC reference manual의 pad 이름을 그대로 공개 이름처럼 쓰는 것은 권장되지 않습니다. 용도가 정해지지 않은 라인은 의미 없는 placeholder보다 빈 문자열이 더 낫습니다.

gpio-hog는 언제 쓰나

gpio-hog는 GPIO controller driver가 probe될 때 특정 GPIO를 자동으로 요청하고 방향을 설정하는 메커니즘입니다. child node에 gpio-hog와 gpios를 두고, input, output-low, output-high 중 하나로 초기 방향과 값을 표현합니다.

gpio0: gpio-controller@1000 {
    compatible = "vendor,gpio";
    reg = <0x1000 0x100>;
    gpio-controller;
    #gpio-cells = <2>;

    regulator-enable-hog {
        gpio-hog;
        gpios = <6 GPIO_ACTIVE_HIGH>;
        output-high;
        line-name = "regulator-enable";
    };
};

hog는 특정 라인이 별도 장치 드라이버가 잡기 전에 보드 초기 상태를 맞춰야 할 때 유용합니다. 반대로 특정 장치 드라이버가 reset, enable, powerdown 같은 의미로 제어해야 하는 라인이라면 consumer 속성으로 드라이버에 넘기는 편이 더 명확합니다.

pin controller와 gpio-ranges

GPIO 번호와 패키지 핀 번호는 같은 개념이 아닙니다. pin controller는 핀 mux와 핀 설정을 담당하고, GPIO controller는 GPIO line을 제공합니다. 일부 SoC에서는 GPIO line이 특정 pin controller의 pin으로 라우팅되므로 두 번호 공간의 대응 관계가 필요합니다.

Linux 커널 GPIO binding의 gpio-ranges는 pin controller local number space와 GPIO controller local number space 사이의 범위를 표현합니다. 형식은 pin controller phandle, GPIO controller offset, pin controller offset, pin 수로 구성됩니다.

gpio-ranges = <&pinctrl0 0 20 10>;

이 값은 GPIO line 0부터 9까지가 pinctrl0의 pin 20부터 29까지에 대응한다는 뜻입니다. DTS를 검토할 때는 pinctrl 설정이 해당 핀을 GPIO 기능으로 mux하는지, GPIO consumer가 참조하는 line offset이 gpio-ranges와 실제 보드 배선에 맞는지 함께 봐야 합니다.

검토할 때의 기준

• 장치 binding이 요구하는 GPIO 속성 이름이 무엇인지 먼저 확인합니다.
• 값의 첫 항목인 phandle이 올바른 GPIO controller를 가리키는지 확인합니다.
• controller 노드에 gpio-controller와 #gpio-cells가 있는지 봅니다.
• specifier 셀 개수와 의미를 controller binding 기준으로 해석합니다.
• active-low, open-drain, sleep 유지 여부 같은 flag가 실제 회로와 맞는지 확인합니다.
• ngpios와 gpio-reserved-ranges가 있으면 consumer가 예약되거나 존재하지 않는 line을 쓰지 않는지 봅니다.
• pin mux가 필요한 SoC에서는 pinctrl 설정과 gpio-ranges를 함께 확인합니다.

자주 틀리는 해석

오해	확인할 기준
<&gpio0 12 0>의 12는 보드 핀 번호다	대개 GPIO controller의 line offset입니다. 보드 헤더 핀 번호와 같다고 가정하면 안 됩니다.
#gpio-cells = <2>이면 두 번째 셀 의미는 항상 같다	흔한 flag 형식은 있지만, 최종 의미는 controller binding과 공통 GPIO flag 정의를 함께 봐야 합니다.
gpio-line-names에는 SoC pad 이름을 넣으면 된다	커널 문서는 on-board device 연결 라인에는 실제 용도를 드러내는 이름을 권장합니다.
gpio-hog는 모든 enable 핀에 쓰면 된다	장치 드라이버가 제어해야 하는 라인은 consumer GPIO로 넘기는 편이 명확합니다. hog는 보드 초기 상태 고정 용도에 가깝습니다.

FAQ

reset-gpios와 reset-gpio 중 무엇을 써야 하나

장치별 binding이 정한 이름을 따라야 합니다. 공통 GPIO consumer schema에는 reset-gpios가 문서화되어 있고, pwdn-gpios처럼 더 새 이름으로 대체된 속성도 있습니다. 새 DTS를 쓸 때는 해당 장치의 YAML binding을 우선 확인하는 것이 안전합니다.

GPIO 번호와 pinctrl pin 번호가 같아야 하나

같을 필요가 없습니다. GPIO controller의 line offset과 pin controller의 pin 번호는 서로 다른 번호 공간일 수 있습니다. 대응 관계가 필요한 하드웨어에서는 gpio-ranges로 두 번호 공간을 연결합니다.

GPIO flag를 숫자로 써도 되나

문법상 숫자 셀을 쓸 수는 있지만, Linux 커널 GPIO binding은 가능하면 GPIO_ACTIVE_HIGH, GPIO_ACTIVE_LOW 같은 매크로 사용을 권장합니다. 숫자만 있으면 회로 극성과 의도를 읽기 어렵습니다.

참고 자료

• Linux Kernel Documentation: GPIO Mappings
• Linux Kernel Devicetree Bindings: Common GPIO lines
• Devicetree Specification: Devicetree Basics