Day76 - gpiolib and GPIO Descriptor¶

Date¶

2026-06-12

Summary¶

Today I studied the Linux GPIO subsystem above the GPIO controller driver layer.

The focus was understanding how GPIO consumers interact with GPIO controllers through gpiolib, GPIO descriptors, and Device Tree GPIO bindings.

I investigated the Raspberry Pi 5 GPIO subsystem, analyzed gpiochip information from debugfs, and observed how GPIO consumers are associated with GPIO lines.

I also implemented a simplified gpiolib simulation to demonstrate GPIO descriptor ownership, active-low translation, and Device Tree GPIO lookup flow.

Topics Covered¶

gpiolib Architecture¶

Studied the role of gpiolib as the GPIO subsystem framework.

Responsibilities include:

GPIO controller registration
GPIO descriptor management
GPIO consumer management
GPIO lookup and mapping
GPIO API abstraction

Architecture:

Consumer Driver
        ↓
     gpiolib
        ↓
    gpio_desc
        ↓
    gpio_chip
        ↓
GPIO Controller
        ↓
MMIO Registers

GPIO Descriptor Model¶

Studied the purpose of GPIO descriptors.

A GPIO descriptor represents a single GPIO line and stores:

GPIO controller reference
GPIO line offset
Consumer ownership
Active-low configuration

Concept:

gpio_desc
    ↓
one GPIO line

Active-Low Translation¶

Studied logical and physical GPIO values.

Example:

GPIO_ACTIVE_LOW

logical 1
    ↓
physical 0

logical 0
    ↓
physical 1

The consumer always operates on logical values.

Translation is performed by gpiolib before invoking gpio_chip callbacks.

GPIO Consumer Ownership¶

Studied GPIO ownership tracking.

A GPIO line can be:

Available
Requested by a consumer

Only one consumer may own a GPIO descriptor at a time.

Device Tree GPIO Binding¶

Studied Device Tree GPIO properties.

Example:

reset-gpios = <&gpio 7 GPIO_ACTIVE_LOW>;

Components:

&gpio
    GPIO controller

7
    GPIO line offset

GPIO_ACTIVE_LOW
    GPIO flags

GPIO Lookup Flow¶

Studied how a GPIO property becomes a GPIO descriptor.

Flow:

reset-gpios
        ↓
Device Tree lookup
        ↓
gpio_dt_spec
        ↓
devm_gpiod_get()
        ↓
gpio_desc
        ↓
gpiolib
        ↓
gpio_chip
        ↓
GPIO Controller

Raspberry Pi Investigation¶

Investigated:

sudo cat /sys/kernel/debug/gpio

Observed:

Multiple gpiochip instances
GPIO line ownership
Consumer labels
Active-low GPIOs
GPIO controller hierarchy

Example:

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

Analysis:

direction  = output
logical    = high
active_low = true
physical   = low

Labs Completed¶

Lab1 - Raspberry Pi GPIO Subsystem Investigation¶

Investigated:

gpiochip hierarchy
GPIO consumers
GPIO ownership
Active-low GPIOs
GPIO line naming

Lab2 - GPIO Descriptor Simulation¶

Implemented:

gpio_desc
GPIO descriptor table
GPIO ownership tracking
demo_gpiod_get()
demo_gpiod_put()
demo_gpiod_set_value()
demo_gpiod_get_value()

Verified:

Consumer
    ↓
gpio_desc
    ↓
gpio_chip
    ↓
GPIO Controller

Lab3 - Device Tree GPIO Binding Simulation¶

Implemented:

gpio_dt_spec
gpio_property
demo_of_get_gpio()
demo_devm_gpiod_get()

Verified:

Device Tree Property
        ↓
gpio_dt_spec
        ↓
gpio_desc
        ↓
gpio_chip
        ↓
GPIO Controller

Key Takeaways¶

GPIO controller drivers expose GPIO operations through gpio_chip callbacks.

gpiolib manages GPIO descriptors and consumer ownership.

GPIO consumers should operate on logical GPIO values.

Active-low translation is handled by gpiolib.

Device Tree GPIO properties are translated into GPIO descriptors before use.

Modern Linux GPIO drivers should use GPIO descriptor APIs instead of GPIO numbers.

Next Steps¶

Day77:

Real gpiod APIs
devm_gpiod_get()
gpiod_set_value()
gpiod_get_value()
Platform driver GPIO consumers
reset-gpios
enable-gpios
interrupt-gpios
Device Tree GPIO resource acquisition