FDT_PINCTRL(4)

💅 fdt_pinctrl — FDT I/O pin multiplexing support 💅

okay so first things first, bestie: this is the fdt_pinctrl page from the Kernel Interfaces Manual — yes, it's a kernel-interface girlie, she lives in section 4, and today we're gonna make pin multiplexing make sense. 🎀

---

✨ SYNOPSIS ✨

device fdt_pinctrl

that's literally it. one line. iconic. no cap. 💅

---

🌸 DESCRIPTION 🌸

okay so pin multiplexing — let's talk about it, because it's genuinely so cool. it's a technology used to re-purpose a single physical connection (and depending on the chip packaging, that thing might be a pin, a ball, or a pad) by routing its signal to any one of several different SoC internal devices. one physical connector, multiple possible jobs. main character energy fr fr. ✨

like, based on the actual device design, a single SoC chip pin might perform any of these roles: SPI clock, I2C data, GPIO pin, or PWM signal. one pin, four possible lives. choose your fighter. 🦋

function selection is performed by the pinmux controller — a SoC hardware block which is usually controlled by a set of registers. and here's the thing, no two are alike: pinmux controller capabilities and register format depend on the actual hardware implementation. iykyk. 💀

on fdt(4) based systems, the pinmux controller is represented by a node in the device tree. it may have any number of child nodes representing pin configuration groups. and the properties of such nodes are hardware-specific and handled by individual pinctrl drivers. so like, every driver does its own thing. respect. 🫶

🧚 Example 1 🧚

pinmux controller device tree node — look at her go:

pinctrl@7e220000 {
    compatible = "vndr,soc1715-pinctrl";
    reg = <0x7e220000 0x100>

    spi0_pins: spi0 {
        vndr,pins = <11 12>
        vndr,functions = <ALT0 ALT5>
    }

    i2c0_pins: i2c0 {
        ...
    }
}

now back to the lore, because it gets better. client devices are hardware devices that require certain pin configurations to function properly. and depending on the state the device is in (active, idle) it might require different pin configurations. she contains multitudes. 💖

each configuration is described by setting the pinctrl-N property to the list of phandles pointing to specific child nodes of the pinmux controller node. and N is an integer value starting with 0 and incremented by 1 for every new set of pin configurations. very orderly. very demure. 🎀

heads up bestie: pinctrl-0 is a default configuration that is applied in the fdt_pinctrl_configure_tree(9) call.

in addition to referring to pin configurations by index, they can be referred to by name if the pinctrl-names property is set. the value of pinctrl-names is a list of strings with names for each pinctrl-N property. and client devices can request specific configuration using fdt_pinctrl_configure(9) and fdt_pinctrl_configure_by_name(9). slay. 💅

🦋 Example 2 🦋

backlight@7f000000 {
    compatible = "vndr,vndr-bl"
    reg = <0x7f000000 0x20>
    ...
    pinctrl-name = "active", "idle"
    pinctrl-0 = <&backlight_active_pins>
    pinctrl-1 = <&backlight_idle_pins>
}

and finally, the assignment, because this is the part you actually need to remember: the pinctrl driver should implement the FDT_PINCTRL_CONFIGURE method, register itself as a pin configuration handler by calling fdt_pinctrl_register function, and call fdt_pinctrl_configure_tree(9) to configure pins for all enabled devices (devices where the "status" property is not set to "disabled"). that's the whole to-do list. go off. 🔥

---

🔍 SEE ALSO 🔍

• fdt_pinctrl(9)

---

👑 HISTORY 👑

The fdt_pinctrl driver first appeared in FreeBSD 10.2. a legend was born. ⭐

---

💜 AUTHORS 💜

The fdt_pinctrl device driver was developed by Ian Lepore <ian@FreeBSD.org>. This manual page was written by Oleksandr Tymoshenko <gonzo@FreeBSD.org>. we stan both of them, fr fr. 🫶

---

and that's the whole page, bestie — go configure some pins 💅✨

sign-off tea ☕: this edition comes to you from Debian, dated March 3, 2018 — yes that's the source/version and date at the bottom of the page, and no we're not copy-pasting it, we're appreciating it. mwah. 🍓