Day76 - gpiolib and GPIO Descriptor¶

Objective¶

Understand how Linux GPIO consumers access GPIO controllers through gpiolib, GPIO descriptors, and Device Tree GPIO bindings.

The goal is to understand how:

Device Tree
    ↓
gpio_desc
    ↓
gpiolib
    ↓
gpio_chip
    ↓
GPIO Controller
    ↓
MMIO Registers

works internally.

Lab1 - Raspberry Pi GPIO Subsystem Investigation¶

Goal¶

Inspect the GPIO subsystem on Raspberry Pi 5.

Inspect GPIO Controllers¶

sudo cat /sys/kernel/debug/gpio

Example:

gpiochip0: GPIOs 569-622, parent: platform/1f000d0000.gpio, pinctrl-rp1:
 gpio-569 (ID_SDA)
 gpio-570 (ID_SCL)
 ...
 gpio-601 (ETH_RST_N |phy-reset) out hi ACTIVE LOW
 ...

Observations¶

The system contains multiple GPIO controllers:

gpiochip11
gpiochip12
gpiochip10
gpiochip13
gpiochip0

Each GPIO controller owns a range of GPIO lines.

Example:

gpiochip0

base = 569
ngpio = 54

GPIO569 ~ GPIO622

Consumer Ownership¶

Example:

gpio-601 (ETH_RST_N |phy-reset)

Meaning:

GPIO Line  = ETH_RST_N
Consumer   = phy-reset

A GPIO line can be owned by a GPIO consumer.

Active-Low Example¶

Example:

gpio-601 (ETH_RST_N |phy-reset) out hi ACTIVE LOW

Interpretation:

Direction  = Output
Logical    = High
Active Low = True

Physical   = Low

Lab2 - GPIO Descriptor Simulation¶

Goal¶

Implement a simplified GPIO descriptor layer.

Architecture¶

Consumer
    ↓
gpio_desc
    ↓
gpio_chip
    ↓
GPIO Controller

GPIO Descriptor¶

Implemented:

struct gpio_desc {
    struct gpio_chip *chip;

    unsigned int offset;

    bool requested;
    bool active_low;

    const char *consumer;
};

Descriptor Table¶

Implemented:

static struct gpio_desc desc_table[GPIO_MAX_LINES];

Purpose:

One descriptor
    ↓
One GPIO line

Descriptor APIs¶

Implemented:

demo_gpiod_get()
demo_gpiod_put()
demo_gpiod_set_value()
demo_gpiod_get_value()

Ownership Tracking¶

Only one consumer may request a GPIO line.

Example:

consumer A
    ↓
GPIO5

Another request:

consumer B
    ↓
GPIO5

Result:

Request rejected

Active-Low Translation¶

Implemented:

physical_value =
    desc->active_low ?
    !logical_value :
    logical_value;

Flow:

logical value
        ↓
active-low translation
        ↓
physical value
        ↓
gpio_chip->set()

Verification¶

Active High:

logical 1
    ↓
physical 1

Register:

OUT = 0x00000020

Active Low:

logical 1
    ↓
physical 0

Register:

OUT = 0x00000020

Active Low:

logical 0
    ↓
physical 1

Register:

OUT = 0x000000a0

Lab3 - Device Tree GPIO Binding Simulation¶

Goal¶

Simulate how Device Tree GPIO properties become GPIO descriptors.

Device Tree Example¶

reset-gpios = <&gpio 7 GPIO_ACTIVE_LOW>;
led-gpios   = <&gpio 5 GPIO_ACTIVE_HIGH>;

Pseudo Device Tree Model¶

Implemented:

struct gpio_property {
    const char *name;

    struct gpio_chip *chip;

    unsigned int offset;

    bool active_low;
};

Example:

{
    .name = "reset-gpios",
    .chip = &chip,
    .offset = 7,
    .active_low = true,
}

GPIO DT Specification¶

Implemented:

struct gpio_dt_spec {
    struct gpio_chip *chip;

    unsigned int offset;

    bool active_low;
};

Lookup Flow¶

Implemented:

demo_of_get_gpio()

Flow:

Property Name
        ↓
gpio_property table
        ↓
gpio_dt_spec

Descriptor Acquisition¶

Implemented:

demo_devm_gpiod_get()

Flow:

gpio_dt_spec
        ↓
gpio_desc

Complete Flow¶

reset-gpios
        ↓
demo_of_get_gpio()
        ↓
gpio_dt_spec
        ↓
demo_devm_gpiod_get()
        ↓
gpio_desc
        ↓
demo_gpiod_set_value()
        ↓
gpio_chip->set()
        ↓
GPIO Controller

Results¶

Successfully demonstrated:

GPIO descriptor ownership
Active-low translation
GPIO consumer abstraction
Device Tree GPIO lookup
GPIO descriptor acquisition
GPIO controller access through gpio_chip

Key Concepts¶

gpio_chip¶

Represents:

GPIO Controller

Provides:

get()
set()
direction_input()
direction_output()

gpio_desc¶

Represents:

One GPIO Line

Stores:

GPIO Controller
Offset
Consumer
Active Low
Ownership

gpiolib¶

Provides:

GPIO descriptor management
GPIO ownership tracking
GPIO lookup
GPIO consumer APIs

Conclusion¶

Modern Linux GPIO drivers should operate through GPIO descriptors.

GPIO consumers should not access GPIO controller hardware directly.

gpiolib provides the abstraction layer between GPIO consumers and GPIO controller drivers.

Consumer
    ↓
gpio_desc
    ↓
gpiolib
    ↓
gpio_chip
    ↓
GPIO Controller