linux 中的 pinctrl 子系统

linux 中的 pinctrl 子系统

前置知识：Linux 设备模型、设备树（Device Tree）、GPIO 基本概念

1. 为什么需要 pinctrl？

1.1 SoC 引脚复用的现实问题

现代 SoC 的引脚（pin）数量远小于内部外设数量，因此绝大多数引脚都是多功能复用的：

• 同一个物理引脚，既可以配置为 GPIO，也可以作为 I2C_SDA、SPI_CLK、UART_TX、PWM 输出等；
• 每个引脚往往还带有电气属性配置：上拉/下拉（pull-up/down）、驱动强度（drive strength）、施密特触发、斜率控制、开漏（open-drain）等。

以一颗典型的 Cortex-A 级 SoC 为例，一个引脚可能有 4~8 种功能（mux function），而复用关系散布在数十个引脚上。

1.2 没有 pinctrl 之前的混乱

在 pinctrl 子系统出现之前（ARM Linux 早期），引脚配置存在几个典型问题：

1.3 pinctrl 的定位

pinctrl 子系统就是为解决上述问题而生的一个内核框架：

• 向上（客户端驱动）：提供统一接口，让驱动以"状态（state）"的抽象方式声明引脚需求，如 default、sleep；
• 向下（SoC 驱动）：定义 pinctrl 驱动的编写框架（pinctrl_desc、三组操作函数集）；
• 横向：与设备树绑定（引脚配置写在 DTS 里）、与 GPIO 子系统互通（gpio-ranges）、与 runtime PM 配合（引脚状态随设备电源切换）。

一句话总结：pinctrl 负责"引脚复用（pinmux）+ 引脚电气配置（pinconf）"的统一管理，让引脚资源像时钟、电源一样成为可被设备树描述、被驱动申请的内核资源。

2. 核心概念体系

理解 pinctrl 的关键是把下面几个抽象层次分清：

2.1 引脚控制器的功能划分

pinctrl 子系统管理的能力分为两块：

有些 SoC 这两块在同一组寄存器里，有些则分开；pinctrl 框架允许驱动只实现其中一块（但大多数驱动两块都实现）。

2.2 四个基本组织单位

pinctrl 驱动把成千上万的引脚组织成四个层次的概念：

记忆模型：

上图要点：客户端设备以 state 名义引用若干 Group；每个 Group 对应一个 Function，并包含若干 Pin；每个 Pin 再附带 pinconf 电气配置。

3. 整体架构

3.1 分层视图

上图把 pinctrl 子系统从上到下分为四层：

此外，pinctrl 还与 GPIO 子系统、Runtime PM 存在横向关联。

3.2 源码位置

3.3 与相关子系统的关系

• 与 GPIO 子系统：GPIO 引脚本质上也是"复用功能的一种"（function = gpio）。pinctrl 驱动通过 gpio-ranges 声明哪些 pin 对应哪些 GPIO 编号，gpiolib 在 gpio_request() 时回调 pinctrl_gpio_request()，防止"引脚已被复用为 I2C 却被当 GPIO 申请"的冲突。
• 与设备模型：客户端驱动的 struct device 内部挂着 pins 指针；驱动核心在 probe 前会自动把设备切到 default 状态（自动调用，不需要驱动手写）。
• 与 runtime PM：设备进入休眠时驱动把 state 切到 sleep，引脚进入低功耗配置（如下拉、输入高阻），唤醒时切回 default。

4. 核心数据结构（内核视角）

4.1 驱动侧：描述 SoC

/* include/linux/pinctrl/pinctrl.h */
struct pinctrl_desc {
const char *name;
const struct pinctrl_pin_desc *pins; /* 本 SoC 全部 pin 的表 */
unsigned int npins;
const struct pinctrl_ops *pctlops; /* 组/功能枚举 */
const struct pinmux_ops *pmxops; /* 复用选择 */
const struct pinconf_ops *confops; /* 电气配置 */
struct module *owner;
/* … */
};

注册入口：

struct pinctrl_dev *devm_pinctrl_register(struct device *dev,
struct pinctrl_desc *pctldesc,
void *driver_data);

4.2 三组操作函数集

其中 set_mux 是 pinctrl 驱动真正的"干活"函数：给定 function + group，写复用寄存器把引脚切到对应功能。

4.3 客户端侧：抽象状态

struct pinctrl; /* 一个客户端设备的 pinctrl 句柄 */
struct pinctrl_state; /* 一个状态（如 default / sleep） */

客户端通过 devm_pinctrl_get(dev) 拿到句柄，pinctrl_lookup_state(p, "sleep") 找到状态，pinctrl_select_state(p, s) 应用。设备树里 pinctrl-names 的每个名字对应一个 pinctrl_state，每个 state 内部是一组 map（功能映射 + 配置列表）。

5. 设备树绑定：驱动开发者最常接触的部分

5.1 服务端（pinctrl 控制器节点）

/* 控制器本身 */
pinctrl: pinctrl {
compatible = "rockchip,rk3568-pinctrl";
rockchip,grf = <&grf>;
#address-cells = <2>;
#size-cells = <2>;
ranges;

/* 各 bank 子节点，同时是 GPIO 控制器 */
gpio0: gpio@fdd60000 {
compatible = "rockchip,gpio-bank";
reg = <0x0 0xfdd60000 0x0 0x100>;
gpio-controller;
#gpio-cells = <2>;
/* … */
};
};

5.2 引脚配置子节点（板级可复用的"引脚片段"）

&pinctrl {
i2c0 {
/* 一个引脚配置片段：group + 电气属性 */
i2c0_xfer: i2c0-xfer {
rockchip,pins =
<0 RK_PB1 RK_FUNC_I2C0_SCL &pcfg_pull_up>,
<0 RK_PB0 RK_FUNC_I2C0_SDA &pcfg_pull_up>;
};
};

uart2 {
uart2m0_xfer: uart2m0-xfer {
rockchip,pins =
<0 RK_PC7 RK_FUNC_UART2_TX_M0 &pcfg_pull_up>,
<0 RK_PC6 RK_FUNC_UART2_RX_M0 &pcfg_pull_up>;
};
};

/* 通用电气配置片段 */
pcfg_pull_up: pcfg-pull-up {
bias-pull-up;
};
pcfg_pull_none: pcfg-pull-none {
bias-disable;
};
};

注意两点：

• 节点名采用 kebab-case（i2c0-xfer），label 采用 snake_case（i2c0_xfer）——这是 bindings 的通用约定；
• 电气属性可以做成公共片段（pcfg_pull_up），被多个引脚配置引用复用。

5.3 客户端引用方式

&i2c0 {
pinctrl-names = "default"; /* state 名字列表 */
pinctrl-0 = <&i2c0_xfer>; /* 名字对应的 phandle 列表 */
status = "okay";
};

&uart2 {
pinctrl-names = "default", "sleep";
pinctrl-0 = <&uart2m0_xfer>;
pinctrl-1 = <&uart2m0_sleep>; /* 休眠时的引脚配置 */
status = "okay";
};

解析规则（drivers/pinctrl/devicetree.c）：

• pinctrl-names 第 N 个名字 ↔ pinctrl-N 属性，一一对应；
• 名字 default 是特殊的：设备模型在驱动 probe 之前会自动 select 它；
• pinctrl-N 里可以挂多个 phandle（多个配置片段合并成一个 state）。

5.4 常见 state 命名约定

5.5 各平台风格差异

虽然风格不同，但概念模型完全一致：都是"把一组 pin 设置成某 function + 某电气配置"。

6. 客户端驱动如何使用 pinctrl

6.1 最简单的情况：什么都不用写

绝大多数驱动只需在 DTS 里写好 pinctrl-names = "default"; pinctrl-0 = <&xxx>; —— 设备模型（drivers/base/pinctrl.c 的 pinctrl_bind_pins()）在 probe 前自动完成 get + select。这就是 i2c/spi/serial 驱动里看不到 pinctrl 代码的原因。

6.2 需要动态切换的驱动

#include <linux/pinctrl/consumer.h>

struct my_dev {
struct pinctrl *pctl;
struct pinctrl_state *st_active;
struct pinctrl_state *st_sleep;
};

static int my_probe(struct platform_device *pdev)
{
struct my_dev *m = /* … */;

m->pctl = devm_pinctrl_get(&pdev->dev); /* 获取句柄 */
if (IS_ERR(m->pctl))
return PTR_ERR(m->pctl);

m->st_active = pinctrl_lookup_state(m->pctl, "default");
m->st_sleep = pinctrl_lookup_state(m->pctl, "sleep");
/* … */
}

static int my_suspend(struct device *dev)
{
struct my_dev *m = dev_get_drvdata(dev);
pinctrl_select_state(m->pctl, m->st_sleep); /* 引脚进入低功耗 */
return 0;
}

static int my_resume(struct device *dev)
{
struct my_dev *m = dev_get_drvdata(dev);
pinctrl_select_state(m->pctl, m->st_active);
return 0;
}

6.3 客户端 API 一览

7. 编写一个 SoC 的 pinctrl 驱动（框架视角）

新平台移植时的最小骨架：

static const struct pinctrl_pin_desc foo_pins[] = {
PINCTRL_PIN(0, "P0"), PINCTRL_PIN(1, "P1"), /* … 全部 pin */
};

static int foo_get_groups_count(struct pinctrl_dev *pctldev) { ... }
static const char *foo_get_group_name(struct pinctrl_dev *pctldev, unsigned sel) { ... }
static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned sel,
const unsigned **pins, unsigned *npins) { ... }
static int foo_dt_node_to_map(struct pinctrl_dev *pctldev,
struct device_node *np,
struct pinctrl_map **map, unsigned *num_maps) { ... }

static const struct pinctrl_ops foo_pctrl_ops = {
.get_groups_count = foo_get_groups_count,
.get_group_name = foo_get_group_name,
.get_group_pins = foo_get_group_pins,
.dt_node_to_map = foo_dt_node_to_map,
.dt_free_map = pinctrl_utils_free_map,
};

static int foo_set_mux(struct pinctrl_dev *pctldev, unsigned func, unsigned group)
{
/* 查表找到 group 的 pins + 目标 function 编号，写复用寄存器 */
return 0;
}

static const struct pinmux_ops foo_pmxops = {
.get_functions_count = ... ,
.get_function_name = ... ,
.get_function_groups = ... ,
.set_mux = foo_set_mux,
.gpio_request_enable = ... ,
.strict = true, /* 禁止对已复用 pin 再申请 GPIO */
};

static const struct pinconf_ops foo_confops = {
.is_generic = true, /* 使用通用配置参数 */
.pin_config_get = foo_pinconf_get,
.pin_config_set = foo_pinconf_set,
.pin_config_group_set = foo_pinconf_group_set,
};

static struct pinctrl_desc foo_desc = {
.name = "foo-pinctrl",
.pins = foo_pins,
.npins = ARRAY_SIZE(foo_pins),
.pctlops = &foo_pctrl_ops,
.pmxops = &foo_pmxops,
.confops = &foo_confops,
.owner = THIS_MODULE,
};

static int foo_pinctrl_probe(struct platform_device *pdev)
{
/* 映射寄存器、初始化私有数据，然后： */
return PTR_ERR_OR_ZERO(devm_pinctrl_register(&pdev->dev, &foo_desc, priv));
}

要点：

7.1 pinctrl-single：不想写驱动的替代方案

对于"引脚配置就是往某偏移寄存器写值"的简单控制器，可直接用通用驱动 pinctrl-single：

&pinmux {
pinctrl-single,pins = <
0x1a0 (PIN_INPUT_PULLUP | MUX_MODE2) /* uart0_rxd */
0x1a4 (PIN_OUTPUT | MUX_MODE2) /* uart0_txd */
>;
};

DTS 直接描述"偏移 + 值"，内核里不用新增任何 C 代码——AM335x、OMAP、部分 RISC-V SoC 都是这种模式。

8. 调试手段

8.1 debugfs（首选）

挂载 debugfs 后，/sys/kernel/debug/pinctrl/ 下每个 pinctrl 控制器一个目录：

# 列出所有 pin 及其当前 owner/mux 状态
cat /sys/kernel/debug/pinctrl/*/pins

# 查看当前活跃的 mux 映射
cat /sys/kernel/debug/pinctrl/*/pinmux-pins

# 查看每个 function ↔ group 映射
cat /sys/kernel/debug/pinctrl/*/pinmux-functions

# 查看每个 pin 的电气配置（需要 pinconf debug 支持）
cat /sys/kernel/debug/pinctrl/*/pinconf-pins

pins 输出的典型形态：

pin 32 (gpio1-0): device 3ff20000.i2c function i2c0 group i2c0-xfer
pin 33 (gpio1-1): GPIO gpio1

一行就能看到：引脚被谁占用、复用成什么功能、属于哪个 group——排查"引脚没反应"类问题第一刀就砍这里。

8.2 动态调试

echo 'file drivers/pinctrl/* +p' > /sys/kernel/debug/dynamic_debug/control

8.3 常见故障速查表

9. 与其他系统的横向对比

对 RT-Thread 等 RTOS 而言，引脚配置通常是各 BSP 的 pinmux.c + 一个 rt_pin_* GPIO 框架，复用管理远弱于 Linux pinctrl——这也是 Linux 在复杂 SoC 上的结构性优势之一。

10. 总结：一张图记住 pinctrl

整个流程可以概括为：设备树里的 控制器节点 定义引脚配置片段，客户端设备节点 通过 pinctrl-N = <&片段> 引用这些片段；内核解析后交给 pinctrl core 管理，再经 SoC pinctrl 驱动 的 ops 回调写入寄存器，最终在 SoC 硬件引脚 上生效。

三句话收束：

附录：常用配置属性速查（generic pinconf）

绑定文档：Documentation/devicetree/bindings/pinctrl/pincfg-node.yaml