GPIO Descriptor Consumer Interface

GPIO consumer 지침

문서 제목은 `GPIO Descriptor Consumer Interface`이며 GPIO framework의 consumer interface를 설명합니다.

표준 GPIO call 없이는 동작할 수 없는 driver의 Kconfig entry는 `GPIOLIB`에 depend하거나 이를 select해야 합니다. Driver가 GPIO를 얻고 사용하는 function은 source path `include/linux/gpio/consumer.h`를 include하면 사용할 수 있습니다.

#include <linux/gpio/consumer.h>

`GPIOLIB`이 disable된 경우 header의 모든 function에는 static inline stub가 있고 호출 시 warning을 냅니다. Stub는 두 경우를 지원합니다.

첫째, `COMPILE_TEST` 같은 단순 compile coverage에서는 실제 system을 실행하지 않으므로 현재 platform이 `GPIOLIB`을 enable·select하지 않아도 상관없습니다.

둘째, compile-time configuration에 따라 일부 system에서는 GPIO를 쓰지 않고 다른 system에서는 사용하는 진정한 optional `GPIOLIB` 지원입니다. 이 경우 consumer는 disabled configuration에서 stub를 호출하지 않도록 해야 하며, 그렇지 않으면 console warning이 발생합니다.

진정한 optional `GPIOLIB` 사용과 `[devm_]gpiod_get_optional()` 호출을 결합하면 이상한 error message가 생기므로 피해야 합니다. Optional GPIOLIB에서는 일반 getter와 명시적 error handling을 사용합니다.

Descriptor interface function은 `gpiod_` prefix를, legacy interface는 `gpio_` prefix를 사용합니다. Kernel의 다른 function은 이 prefix를 쓰지 않아야 합니다. 새 code는 legacy function 대신 `<linux/gpio/consumer.h>`와 descriptor만 사용해야 합니다.

GPIO descriptor 획득과 초기 flag

Descriptor interface에서 GPIO는 위조할 수 없는 opaque handler로 식별하며 `gpiod_get()` 계열을 통해 얻어야 합니다. `gpiod_get()`은 GPIO를 사용할 device와 요청한 GPIO의 function을 받습니다.

struct gpio_desc *gpiod_get(struct device *dev, const char *con_id,
                            enum gpiod_flags flags)

여러 GPIO가 하나의 function을 구현한다면 추가 index를 받는 `gpiod_get_index()`를 사용합니다.

struct gpio_desc *gpiod_get_index(struct device *dev,
                                  const char *con_id, unsigned int idx,
                                  enum gpiod_flags flags)

Device Tree에서 `con_id` parameter가 mapping되는 자세한 방식은 `Documentation/driver-api/gpio/board.rst`를 참조합니다.

`flags`는 GPIO direction과 초기 logical value를 선택적으로 지정합니다.

• `GPIOD_ASIS` 또는 0: 초기화하지 않으며 나중에 전용 function으로 direction 설정
• `GPIOD_IN`: input으로 초기화
• `GPIOD_OUT_LOW`: logical 0 output으로 초기화
• `GPIOD_OUT_HIGH`: logical 1 output으로 초기화
• `GPIOD_OUT_LOW_OPEN_DRAIN`: logical 0 output과 open-drain electrical mode 강제
• `GPIOD_OUT_HIGH_OPEN_DRAIN`: logical 1 output과 open-drain electrical mode 강제

초기값은 logical value이며 실제 line level은 active-high 또는 active-low 설정에 따라 달라집니다.

마지막 두 flag는 I2C처럼 open drain이 필수인 경우에 사용합니다. Mapping에서 open drain으로 구성하지 않았더라도 mode를 강제하고 board configuration을 고쳐야 한다는 warning을 출력합니다.

Optional GPIO와 return semantics

`gpiod_get()`과 `gpiod_get_index()`는 valid descriptor 또는 `IS_ERR()`로 검사할 error code를 반환하며 `NULL`은 반환하지 않습니다.

Device/function/index 조합에 GPIO가 전혀 할당되지 않았을 때만 `-ENOENT`를 반환합니다. GPIO가 할당됐지만 획득 중 실패한 경우에는 다른 error code를 사용하므로 optional parameter의 부재와 실제 error를 구분할 수 있습니다.

Optional GPIO에는 `gpiod_get_optional()`과 `gpiod_get_index_optional()`을 사용할 수 있으며 mapping이 없으면 `-ENOENT` 대신 `NULL`을 반환합니다.

struct gpio_desc *gpiod_get_optional(struct device *dev,
                                     const char *con_id,
                                     enum gpiod_flags flags)

struct gpio_desc *gpiod_get_index_optional(struct device *dev,
                                           const char *con_id,
                                           unsigned int index,
                                           enum gpiod_flags flags)

`gpio_get*_optional()` function과 managed variant는 나머지 gpiolib API와 달리 gpiolib support가 disable된 경우에도 `NULL`을 반환합니다. Driver는 `-ENOSYS`를 따로 처리할 필요가 없지만 system integrator는 필요한 system에서 gpiolib을 enable해야 합니다.

GPIO array 획득·해제와 devm

하나의 function이 여러 GPIO를 사용하면 `gpiod_get_array()` 한 번으로 모두 얻을 수 있습니다.

struct gpio_descs *gpiod_get_array(struct device *dev,
                                   const char *con_id,
                                   enum gpiod_flags flags)

반환되는 `struct gpio_descs`에는 descriptor array와 I/O를 빠르게 할 수 있는 gpiolib private `gpio_array` pointer가 들어 있습니다.

struct gpio_descs {
        struct gpio_array *info;
        unsigned int ndescs;
        struct gpio_desc *desc[];
}

Mapping이 없을 때 `NULL`을 반환하는 array optional variant도 있습니다.

struct gpio_descs *gpiod_get_array_optional(struct device *dev,
                                            const char *con_id,
                                            enum gpiod_flags flags)

Single·indexed·optional·array getter에는 device-managed variant가 모두 정의됩니다.

struct gpio_desc *devm_gpiod_get(struct device *dev, const char *con_id,
                                 enum gpiod_flags flags)

struct gpio_desc *devm_gpiod_get_index(struct device *dev,
                                       const char *con_id,
                                       unsigned int idx,
                                       enum gpiod_flags flags)

struct gpio_desc *devm_gpiod_get_optional(struct device *dev,
                                          const char *con_id,
                                          enum gpiod_flags flags)

struct gpio_desc *devm_gpiod_get_index_optional(struct device *dev,
                                                const char *con_id,
                                                unsigned int index,
                                                enum gpiod_flags flags)

struct gpio_descs *devm_gpiod_get_array(struct device *dev,
                                        const char *con_id,
                                        enum gpiod_flags flags)

struct gpio_descs *devm_gpiod_get_array_optional(struct device *dev,
                                                 const char *con_id,
                                                 enum gpiod_flags flags)

Single descriptor는 `gpiod_put()`으로 해제합니다.

void gpiod_put(struct gpio_desc *desc)

Array는 `gpiod_put_array()`로 전체를 해제합니다.

void gpiod_put_array(struct gpio_descs *descs)

해제한 descriptor는 절대 다시 사용하면 안 됩니다. `gpiod_get_array()`로 얻은 array의 개별 descriptor를 `gpiod_put()`으로 따로 해제하는 것도 허용되지 않습니다.

Device-managed 해제 variant는 다음과 같습니다.

void devm_gpiod_put(struct device *dev, struct gpio_desc *desc)

void devm_gpiod_put_array(struct device *dev, struct gpio_descs *descs)

GPIO direction 설정

Driver가 GPIO에서 가장 먼저 해야 할 일은 direction 설정입니다. `gpiod_get*()`에 direction flag를 주지 않았다면 `gpiod_direction_*()` function을 호출합니다.

int gpiod_direction_input(struct gpio_desc *desc)
int gpiod_direction_output(struct gpio_desc *desc, int value)

성공하면 0, 실패하면 negative errno를 반환합니다. Get/set value call은 error를 반환하지 않고 misconfiguration 가능성이 있으므로 direction call의 return을 반드시 검사해야 합니다.

보통 task context에서 호출합니다. 다만 spinlock-safe GPIO라면 early board setup에서 tasking enable 전에도 사용할 수 있습니다.

Output GPIO에 전달한 value는 초기 output value가 되어 system startup 중 signal glitch를 방지합니다.

현재 direction은 다음 function으로 조회합니다.

int gpiod_get_direction(const struct gpio_desc *desc)

`gpiod_get_direction()`은 output이면 0, input이면 1, 실패하면 error code를 반환합니다. GPIO에는 default direction이 없으므로 먼저 direction을 설정하지 않고 사용하는 것은 illegal이며 undefined behavior입니다.

Spinlock-safe GPIO access

대부분의 GPIO controller는 sleep이 필요 없는 memory read/write instruction으로 접근할 수 있어 hard non-threaded IRQ handler 같은 context에서도 안전합니다.

Atomic context에서는 다음 call을 사용합니다.

int gpiod_get_value(const struct gpio_desc *desc);
void gpiod_set_value(struct gpio_desc *desc, int value);

Value는 boolean이며 0은 inactive, nonzero는 active입니다. Output pin을 읽으면 pin에서 실제로 보이는 값을 반환해야 하므로 open-drain signaling이나 output latency 때문에 지정한 output value와 다를 수 있습니다.

Invalid GPIO는 앞선 `gpiod_direction_*()`에서 보고되어야 하므로 get/set call은 error를 반환하지 않습니다. Output read를 지원하지 않는 platform은 항상 0을 반환해야 합니다. Sleep 없이 안전하게 접근할 수 없는 GPIO에 이 call을 사용하는 것은 error입니다.

Sleep 가능한 GPIO access

일부 GPIO controller는 I2C나 SPI 같은 message bus를 사용합니다. Command 전송과 response를 기다리려면 sleep해야 하므로 IRQ handler 안에서는 접근할 수 없습니다.

이런 GPIO는 다음 function이 nonzero를 반환해 구분합니다.

int gpiod_cansleep(const struct gpio_desc *desc)

Sleep이 필요한 GPIO에는 다음 accessor를 사용합니다.

int gpiod_get_value_cansleep(const struct gpio_desc *desc)
void gpiod_set_value_cansleep(struct gpio_desc *desc, int value)

Threaded IRQ handler처럼 sleep할 수 있는 context가 필요하며 `cansleep()` suffix가 없는 spinlock-safe accessor 대신 이 function을 사용해야 합니다. Sleep 가능성과 hardIRQ 사용 불가를 제외하면 동작은 spinlock-safe call과 같습니다.

Active-low·open-drain logical semantics

Consumer가 실제 physical line level을 신경 쓰지 않도록 모든 `gpiod_set_value_xxx()`와 `gpiod_set_array_value_xxx()`는 logical value를 사용합니다. GPIO가 active low이면 전달된 value를 변환한 뒤 physical line을 구동합니다.

Open drain output은 high를 적극 구동하지 않고, open source output은 low를 적극 구동하지 않으며 대신 high-impedance 상태로 전환합니다. 이 electrical detail 역시 consumer가 처리할 필요가 없습니다. 자세한 내용은 `driver.rst`의 open-drain 설명을 참조합니다.

따라서 `gpiod_set_(array)_value_xxx()`의 `value`는 1이면 active, 0이면 inactive를 뜻합니다. 예를 들어 active-low GPIO에 active 1을 전달하면 실제 line level은 low가 됩니다.

`set_raw/get_raw` function으로 이 semantics를 override할 수 있지만 가능한 한 피해야 합니다. 특히 system-agnostic driver는 실제 physical level이 아니라 logical value에 집중해야 합니다.

Raw GPIO value access

일부 consumer는 GPIO line과 device 사이의 요소와 무관하게 device가 실제로 받을 logical state를 직접 관리해야 합니다.

다음 call은 active-low나 open-drain property를 무시하고 raw line value에 작동합니다.

int gpiod_get_raw_value(const struct gpio_desc *desc)
void gpiod_set_raw_value(struct gpio_desc *desc, int value)
int gpiod_get_raw_value_cansleep(const struct gpio_desc *desc)
void gpiod_set_raw_value_cansleep(struct gpio_desc *desc, int value)
int gpiod_direction_output_raw(struct gpio_desc *desc, int value)

GPIO의 active-low state도 다음 call로 조회하고 toggle할 수 있습니다.

int gpiod_is_active_low(const struct gpio_desc *desc)
void gpiod_toggle_active_low(struct gpio_desc *desc)

이 function은 매우 제한적으로 사용해야 합니다. 일반 driver는 physical line level이나 open-drain semantics를 직접 다룰 필요가 없어야 합니다.

여러 GPIO 동시 access

다음 function은 GPIO array의 value를 get 또는 set합니다.

int gpiod_get_array_value(unsigned int array_size,
                          struct gpio_desc **desc_array,
                          struct gpio_array *array_info,
                          unsigned long *value_bitmap);
int gpiod_get_raw_array_value(unsigned int array_size,
                              struct gpio_desc **desc_array,
                              struct gpio_array *array_info,
                              unsigned long *value_bitmap);
int gpiod_get_array_value_cansleep(unsigned int array_size,
                                   struct gpio_desc **desc_array,
                                   struct gpio_array *array_info,
                                   unsigned long *value_bitmap);
int gpiod_get_raw_array_value_cansleep(unsigned int array_size,
                                   struct gpio_desc **desc_array,
                                   struct gpio_array *array_info,
                                   unsigned long *value_bitmap);

int gpiod_set_array_value(unsigned int array_size,
                          struct gpio_desc **desc_array,
                          struct gpio_array *array_info,
                          unsigned long *value_bitmap)
int gpiod_set_raw_array_value(unsigned int array_size,
                              struct gpio_desc **desc_array,
                              struct gpio_array *array_info,
                              unsigned long *value_bitmap)
int gpiod_set_array_value_cansleep(unsigned int array_size,
                                   struct gpio_desc **desc_array,
                                   struct gpio_array *array_info,
                                   unsigned long *value_bitmap)
int gpiod_set_raw_array_value_cansleep(unsigned int array_size,
                                       struct gpio_desc **desc_array,
                                       struct gpio_array *array_info,
                                       unsigned long *value_bitmap)

Array는 임의의 GPIO 집합일 수 있습니다. Chip driver가 지원하면 같은 bank나 chip의 GPIO를 동시에 접근해 성능을 크게 높이고, 지원하지 않으면 순차 접근합니다.

Function은 네 argument를 받습니다.

• `array_size`: array element 수
• `desc_array`: GPIO descriptor array
• `array_info`: `gpiod_get_array()`에서 얻은 optional 정보
• `value_bitmap`: get 결과를 저장하거나 set 값을 제공하는 bitmap

`gpiod_get_array()`가 반환한 descriptor group이 원하는 GPIO 집합과 같다면 `struct gpio_descs`를 그대로 사용할 수 있습니다.

struct gpio_descs *my_gpio_descs = gpiod_get_array(...);
gpiod_set_array_value(my_gpio_descs->ndescs, my_gpio_descs->desc,
                      my_gpio_descs->info, my_gpio_value_bitmap);

`gpiod_get()`과 `gpiod_get_array()`를 조합해 완전히 임의의 descriptor array도 만들 수 있습니다. 이 경우 array를 수동으로 구성하고 `array_info`는 `NULL`로 둡니다.

최적 성능을 위해 같은 chip의 GPIO는 descriptor array 안에서 연속해야 합니다. Descriptor index가 한 chip의 hardware pin number와 일치하고 array와 `array_info`가 `gpiod_get_array()` 결과와 같으면 `value_bitmap`을 chip의 `.get/set_multiple()` callback에 직접 전달하는 fast bitmap path를 사용할 수 있습니다.

`gpiod_get_array_value()` 계열은 성공 시 0, 실패 시 negative error를 반환합니다. 성공 시 GPIO value 0 또는 1을 return하는 `gpiod_get_value()`와 달리 array value는 `value_bitmap`에 저장됩니다.

GPIO를 IRQ로 mapping

GPIO line은 흔히 IRQ로 사용할 수 있습니다. 해당 GPIO의 IRQ number는 다음 call로 얻습니다.

int gpiod_to_irq(const struct gpio_desc *desc)

성공하면 IRQ number, mapping할 수 없으면 negative errno를 반환합니다. `gpiod_direction_input()`으로 input 설정하지 않은 GPIO를 사용하거나 `gpiod_to_irq()`에서 얻지 않은 IRQ number를 이 경로에서 사용하는 것은 unchecked error입니다. `gpiod_to_irq()`는 sleep할 수 없습니다.

성공한 IRQ number는 `request_irq()`와 `free_irq()`에 전달할 수 있고 board-specific initialization code가 platform device IRQ resource에 저장하기도 합니다. `IRQF_TRIGGER_FALLING` 같은 trigger option과 system wakeup 기능은 GPIO가 아니라 IRQ interface의 일부입니다.

GPIO와 ACPI

ACPI system에서 GPIO는 device의 `_CRS` configuration object에 나열된 `GpioIo()`와 `GpioInt()` resource로 기술됩니다. 이 resource에는 GPIO connection ID 또는 name이 없으므로 추가 mechanism이 필요합니다.

ACPI 5.1 이상 system은 `_DSD` configuration object로 `_CRS`의 특정 GPIO resource에 connection ID를 제공할 수 있으며 GPIO subsystem이 자동 처리합니다. `_DSD`가 없으면 device driver가 `GpioIo()`·`GpioInt()` resource와 GPIO connection ID의 mapping을 제공해야 합니다.

자세한 내용은 `Documentation/firmware-guide/acpi/gpio-properties.rst`를 참조합니다.

Legacy GPIO subsystem과 상호 운용

많은 kernel subsystem과 driver가 아직 legacy integer-based GPIO interface를 사용하지만 새 `gpiod` interface로 갱신하는 것을 강하게 권장합니다.

두 interface를 함께 써야 할 때 descriptor와 integer namespace를 다음 function으로 변환합니다.

int desc_to_gpio(const struct gpio_desc *desc)
struct gpio_desc *gpio_to_desc(unsigned gpio)

`desc_to_gpio()`가 반환한 GPIO number는 descriptor `desc`를 해제하기 전까지 `gpio_*()` function parameter로 안전하게 사용할 수 있습니다.

`gpio_to_desc()`에 전달할 GPIO number는 먼저 `gpio_request_one()` 같은 function으로 적절히 획득해야 하며, 반환 descriptor는 `gpio_free()`로 그 number를 해제할 때까지만 valid합니다.

한 API로 얻은 GPIO를 다른 API로 해제하는 것은 금지되며 unchecked error입니다.