Linux(31)-pinctrl系统

前言

一、为什么需要 Pinctrl 子系统？

引脚复用冲突

芯片的引脚资源有限，一个引脚往往对应多种功能。如果多个驱动直接操作寄存器配置功能，很容易出现"多个驱动抢占同一引脚"的冲突，且没有任何机制来检测和阻止这种冲突。

例如，一个引脚可能同时支持以下功能：

• 普通 GPIO（通用输入输出）
• I2C 的 SDA/SCL
• SPI 的 MOSI/MISO
• UART 的 TX/RX
• PWM 信号输出 具体复用哪个功能，通过配置芯片内部的复用寄存器（MUX Register） 来选择。

假设芯片上 GPIO2_PB4 这个引脚可以同时复用为普通 GPIO 或 I2C1 的 SDA 信号。在没有 Pinctrl 子系统的时代，两个驱动各自直接操作寄存器：

/* ========== 驱动A：某个LED控制驱动 ========== */
staticintmy_led_probe(struct platform_device *pdev)
{
/* 硬编码：直接把 GPIO2_PB4 配置为 GPIO 输出模式 */
/* 假设 IOMUX 寄存器基地址为 0x020E0000 */
/* GPIO2_PB4 对应的 MUX 寄存器偏移为 0x00DC */
void __iomem *mux_reg = ioremap(0x020E0000 + 0x00DC, 4);

/* 写入 0x5 —— ALT5 模式，即 GPIO 功能 */
    writel(0x5, mux_reg);

/* 然后把这个引脚当 GPIO 用，控制 LED 闪烁 */
/* ... */
return0;
}

/* ========== 驱动B：I2C1 总线驱动 ========== */
staticintmy_i2c_probe(struct platform_device *pdev)
{
/* 硬编码：把同一个 GPIO2_PB4 配置为 I2C1_SDA 功能 */
void __iomem *mux_reg = ioremap(0x020E0000 + 0x00DC, 4);

/* 写入 0x0 —— ALT0 模式，即 I2C1_SDA 功能 */
    writel(0x0, mux_reg);

/* 然后初始化 I2C 控制器，开始通信 */
/* ... */
return0;
}

问题所在：两个驱动都直接操作了同一个寄存器地址，后加载的驱动会静默覆盖先加载驱动的配置，且没有任何报错或警告。如果 I2C 驱动后加载，LED 驱动就会莫名其妙地失效——因为它的引脚已经被悄悄切换成了 I2C 功能。没有任何机制能检测到这种冲突。

配置繁琐且易出错

引脚配置不仅要选择"功能"，还要设置电气属性：上拉/下拉电阻、驱动能力（drive strength）、电平标准（LVCMOS3.3V/1.8V）、转换速率（slew rate）等。这些都需要操作复杂的寄存器，不同芯片的寄存器地址还不一样，移植性极差。

驱动与硬件严重耦合

驱动代码中充斥着寄存器地址和位操作，换一颗芯片就要重写大量代码，违反了 Linux 内核"硬件与软件分离"的设计哲学。

例如：配置一个引脚的完整电气属性，需要同时操作多个寄存器、计算多个位域：

/*
 * 目标：将 GPIO2_PB4 配置为 I2C1_SDA，要求：
 *   - 复用功能：ALT0（I2C1_SDA）
 *   - 开漏输出
 *   - 47KΩ 上拉电阻
 *   - 驱动能力：4mA
 *   - 转换速率：100MHz
 *   - 电平标准：3.3V LVCMOS
 */
staticvoidconfigure_i2c_sda_pin(void)
{
void __iomem *base = ioremap(0x020E0000, 0x1000);

/* ---- 第一步：配置 MUX 寄存器（选择功能） ---- */
/*
     * 寄存器偏移 0x00DC，位域定义：
     *   [31:20] 保留
     *   [19:16] SION（软件输入使能）
     *   [15:4]  保留
     *   [3:0]   MUX_MODE（复用模式选择）
     *
     * ALT0 = 0x0 → I2C1_SDA
     */
    writel(0x00000000, base + 0x00DC);

/* ---- 第二步：配置 PAD 寄存器（电气属性） ---- */
/*
     * 寄存器偏移 0x0328，位域定义：
     *   [31:18] 保留
     *   [17]    HYS（施密特触发器）：1=使能
     *   [16]    PUS[1]（上拉/下拉选择）
     *   [15:14] PUS[0] + PUE（上拉/下拉使能）
     *   [13:12] PKE（保持器使能）
     *   [11:7]  ODE（开漏）+ DSE（驱动强度）
     *   [6:3]   SPEED（转换速率）
     *   [2:0]   保留
     *
     * 计算目标值：
     *   HYS=1     → bit17 = 1
     *   47K上拉   → PUS=10, PUE=1 → bits[16:14] = 110
     *   PKE=1     → bits[13:12] = 01
     *   ODE=1     → bit11 = 1（开漏）
     *   DSE=010   → bits[5:3] = 010（4mA）
     *   SPEED=10  → bits[6:3] = 10（100MHz）
     *
     * 拼出来：0x4001B8B0
     *
     * 请问：你能一眼看出 0x4001B8B0 每个位代表什么吗？
     */
    writel(0x4001B8B0, base + 0x0328);

/* ---- 第三步：如果该引脚是输入，还要配置输入选择寄存器 ---- */
/*
     * 寄存器偏移 0x0618
     * 用于选择信号从哪个物理引脚进入内部逻辑
     */
    writel(0x1, base + 0x0618);

    iounmap(base);
}

• 魔数满天飞：0x020E0000、0x00DC、0x0328、0x4001B8B0 全是硬编码的魔数，没有任何自描述性。半年后你自己都看不懂 0x4001B8B0 到底配了什么。
• 位域计算极易出错：一个上拉电阻的配置需要同时操作 PUS、PUE、PKE 三个位域共 5 个 bit，手动拼值非常容易算错。
• 移植性为零：换一个芯片（比如从 i.MX6ULL 换到 RK3576），寄存器基地址、偏移地址、位域定义全部不同，这段代码需要从头重写。
• 无冲突检测：如果另一个驱动也把 0x0328 这个地址配成了不同的值，后写的会覆盖先写的，系统不会有任何提示。

对比：有了 Pinctrl 之后同样的配置，在设备树中只需要这样写：

pinctrl_i2c1: i2c1grp {
    fsl,pins = <
        MX6UL_PAD_I2C1_SDA__I2C1_SDA  0x4001b8b0
    >;
};

• MX6UL_PAD_I2C1_SDA__I2C1_SDA 自带寄存器地址和复用模式，不需要手动计算
• 如果另一个驱动也引用了同一个引脚，Pinctrl 核心层会直接返回 -EBUSY 错误，拒绝冲突请求
• 换芯片时只需要修改设备树，驱动代码一行都不用动

概念分析

pinctrl 子系统作用

1. 引脚复用 (Pin Multiplexing / Pinmux)

• 单个物理 Pad（焊盘）内部连接着一个多路复用开关（MUX）。pinctrl 记录了芯片上每一个引脚可被复用的所有功能（Function），并在外设申请时完成内部路由配置。

2. 电气属性配置 (Pin Configuration / Pinconf)

• 除了控制逻辑切换，引脚的物理电气特性同样关键：
• Pull-up / Pull-down：上拉/下拉电阻配置，决定引脚悬空时的默认电平。
• Drive Strength：驱动能力（通常以 mA 为单位，如 2mA, 4mA, 8mA, 12mA），影响信号边沿陡峭度与抗干扰能力。
• Open-Drain / Push-Pull：开漏与推挽模式设置。
• Slew Rate / Schmitt Trigger：转换速率控制与施密特触发器（用于信号去噪与整形）。

3. 动态状态管理 (State Management) pinctrl 支持将一组引脚打包定义为不同的“状态”（State）：

• default：设备正常工作时的引脚配置。
• sleep：设备进入休眠时的配置（如切为高阻态或下拉，防止静态漏电）。
• idle：总线空闲时的配置（如 I2C/SPI 在不传输数据时的低功耗配置）。

此外还有两个重要概念：

• Pin Group（引脚组）：一组具有相似功能的引脚集合。例如 UART0 需要 TX 和 RX 两个引脚，它们可以归为一个 group。
• Function（功能）：一个逻辑功能（如 "uart0"、"i2c0"），关联一个或多个 pin group。

例如：

但实际使用中，有些设计只用 TX/RX（两线制），有些需要硬件流控（四线制）。这就产生了两种不同的引脚组合需求.

在芯片厂商的 pinctrl 驱动代码中（如 pinctrl-imx6ul.c），这些数据被定义为静态表：

/* ===== 第一层：Pin 定义 ===== */
/* 每个物理引脚的编号和名称 */
staticconststructpinctrl_pin_descimx6ul_pins[] = {
    ...
    IMX_PIN(18, "GPIO1_IO18"),   /* 编号 18 */
    IMX_PIN(19, "GPIO1_IO19"),   /* 编号 19 */
    IMX_PIN(20, "GPIO1_IO20"),   /* 编号 20 */
    IMX_PIN(21, "GPIO1_IO21"),   /* 编号 21 */
    ...
};

/* ===== 第二层：Pin Group 定义 ===== */
/* 引脚组1：基本通信（TX + RX） */
staticconstunsignedint uart1_tx_rx_pins[] = { 18, 19 };

/* 引脚组2：硬件流控（RTS + CTS） */
staticconstunsignedint uart1_rts_cts_pins[] = { 20, 21 };

/* 引脚组数组：UART1 有两个 group */
staticconstchar * const uart1_groups[] = {
"uart1_tx_rx",       /* group 0：基本通信 */
"uart1_rts_cts",     /* group 1：硬件流控 */
};

/* ===== 第三层：Function 定义 ===== */
/* "uart1" 这个功能，关联上面两个 group */
staticconststructimx_pmx_funcimx6ul_pmx_funcs[] = {
    ...
    {
        .name       = "uart1",           /* 功能名 */
        .groups     = uart1_groups,      /* 关联的 group 数组 */
        .num_groups = ARRAY_SIZE(uart1_groups),  /* 共 2 个 group */
    },
    ...
};

关系映射图

Function: "uart1"
├── Group: "uart1_tx_rx"      ← 基本通信场景
│   ├── Pin 18 (GPIO1_IO18)   → TX
│   └── Pin 19 (GPIO1_IO19)   → RX
│
└── Group: "uart1_rts_cts"    ← 硬件流控场景（可选）
    ├── Pin 20 (GPIO1_IO20)   → RTS
    └── Pin 21 (GPIO1_IO21)   → CTS

设备树中如何使用

/* 场景A：只用 TX/RX，不需要硬件流控 */
pinctrl_uart1_basic: uart1-basic {
    fsl,pins = <
        MX6UL_PAD_UART1_TX_DATA__UART1_DCE_TX  0x1b0b1
        MX6UL_PAD_UART1_RX_DATA__UART1_DCE_RX  0x1b0b1
    >;
};

&uart1 {
    pinctrl-names = "default";
    pinctrl-0 = <&pinctrl_uart1_basic>;   /* 只引用基本 group */
    status = "okay";
};

/* 场景B：需要硬件流控，两个 group 都要 */
pinctrl_uart1_full: uart1-full {
    fsl,pins = <
        MX6UL_PAD_UART1_TX_DATA__UART1_DCE_TX  0x1b0b1
        MX6UL_PAD_UART1_RX_DATA__UART1_DCE_RX  0x1b0b1
        MX6UL_PAD_UART1_CTS_B__UART1_DCE_CTS   0x1b0b1
        MX6UL_PAD_UART1_RTS_B__UART1_DCE_RTS   0x1b0b1
    >;
};

&uart1 {
    pinctrl-names = "default";
    pinctrl-0 = <&pinctrl_uart1_full>;    /* 引用包含全部引脚的 group */
    status = "okay";
};

pinctrl 实现架构

Pinctrl 子系统采用经典的三层架构设计：

其底层驱动的核心数据结构以（pinctrl-rk3568.c）为例：

底层驱动关键函数

描述引脚控制器：pinctrl_desc + pinctrl_dev

// 描述一个引脚控制器的"能力说明书"
structpinctrl_desc {
constchar *name;
conststructpinctrl_pin_desc *pins;// 所有引脚的描述数组
unsignedint npins;                     // 引脚总数
conststructpinctrl_ops *pctlops;// 引脚组操作回调
conststructpinmux_ops *pmxops;// 复用操作回调
conststructpinconf_ops *confops;// 电气配置操作回调
};

// 内核运行时创建的控制器实例
structpinctrl_dev {
structlist_headnode;// 全局链表节点
structpinctrl_desc *desc;// 指向描述符
structradix_tree_rootpin_desc_tree;// 引脚描述符的基数树
structlist_headgpio_ranges;// GPIO 范围映射
structdevice *dev;
void *driver_data;
};

描述单个引脚：pinctrl_pin_desc

structpinctrl_pin_desc {
unsigned number;      // 引脚编号，全局唯一
constchar *name;     // 引脚名称（如 "GPIO2_PB4"）
void *drv_data;       // 驱动私有数据
};

描述三种操作回调：pinctrl_ops（引脚组操作）：

structpinctrl_ops {
int (*get_groups_count)(struct pinctrl_dev *pctldev);
constchar *(*get_group_name)(struct pinctrl_dev *pctldev, unsigned selector);
int (*get_group_pins)(struct pinctrl_dev *pctldev, unsigned selector, ...);
int (*dt_node_to_map)(...);   // 解析设备树节点为 pin map
void (*dt_free_map)(...);     // 释放 pin map
};

pinmux_ops（复用操作）：

structpinmux_ops {
int (*request)(struct pinctrl_dev *pctldev, unsigned offset);   // 请求引脚
int (*free)(struct pinctrl_dev *pctldev, unsigned offset);      // 释放引脚
int (*get_functions_count)(struct pinctrl_dev *pctldev);
constchar *(*get_function_name)(struct pinctrl_dev *pctldev, unsigned selector);
int (*get_function_groups)(struct pinctrl_dev *pctldev, unsigned selector, ...);
int (*set_mux)(struct pinctrl_dev *pctldev, unsigned func_selector, unsigned group_selector);
bool strict;  // 是否禁止 GPIO 和其他功能同时使用同一引脚
};

pinconf_ops（电气配置操作）：

structpinconf_ops {
int (*pin_config_get)(struct pinctrl_dev *pctldev, unsigned pin, unsignedlong *config);
int (*pin_config_set)(struct pinctrl_dev *pctldev, unsigned pin, unsignedlong *configs, unsigned num_configs);
int (*pin_config_group_get)(...);
int (*pin_config_group_set)(...);
};

描述外设的引脚状态：pinctrl + pinctrl_state + pinctrl_setting

// 每个使用 pinctrl 的外设设备都有一个 pinctrl 结构体
structpinctrl {
structlist_headnode;
structdevice *dev;
structlist_headstates;// 状态链表（default、sleep 等）
structpinctrl_state *state;// 当前激活的状态
};

// 一个状态（如 "default"）
structpinctrl_state {
structlist_headnode;
constchar *name;                 // 状态名："default"、"sleep"、"idle"
structlist_headsettings;// 该状态下的所有设置项
};

// 单个设置项（复用或配置）
structpinctrl_setting {
structlist_headnode;
enum pinctrl_map_type type;       // MUX_GROUP 或 CONFIGS_PIN/GROUP
structpinctrl_dev *pctldev;// 由哪个控制器处理
union {
structpinctrl_setting_muxmux;// 复用设置
structpinctrl_setting_configsconfigs;// 电气配置
    } data;
};

Pin Map：连接设备树与硬件的桥梁

Pin map 是 pinctrl 的核心数据结构，它将设备树中的配置信息转化为内核可操作的结构：

structpinctrl_map {
constchar *dev_name;             // 使用该引脚的设备名
constchar *name;                 // 状态名（如 "default"）
enum pinctrl_map_type type;       // 类型：MUX_GROUP / CONFIGS_PIN / CONFIGS_GROUP
constchar *ctrl_dev_name;        // 引脚控制器设备名
union {
structpinctrl_map_muxmux;// { group, function }
structpinctrl_map_configsconfigs;// { group_or_pin, configs[], num_configs }
    } data;
};

实现流程

先分清三大阵营

阵营A：控制器侧（芯片厂商定义，描述"我有哪些引脚、能做什么"）
  pinctrl_desc / pinctrl_dev / pinctrl_pin_desc / 三种 ops

阵营B：消费者侧（每个外设设备各一套，描述"我需要引脚怎么配"）
  pinctrl / pinctrl_state / pinctrl_setting

阵营C：桥梁（临时产物，把设备树翻译成阵营B能用的格式）
  pinctrl_map

讲pinctrl 底层实现流程前需县了解两个probe

Linux 内核中，任何驱动的 probe 函数被调用，前提都是驱动（driver）和设备（device）匹配成功。匹配方式有多种，在嵌入式设备树系统中，最常见的就是 compatible 属性匹配：

在 pinctrl 的语境下，系统中实际存在两次独立的匹配和 probe 过程：

第一个 probe：pinctrl 控制器自身的 probe

设备树（通常在芯片级 dtsi 中）：
┌─────────────────────────────────────────┐
│  iomuxc: pinctrl@20e0000 {             │
│      compatible = "fsl,imx6ul-iomuxc"; │
│      reg = <0x020e00000x4000>;        │
│      ...                                │
│  };                                     │
└─────────────────────────────────────────┘
              │
              │  compatible 匹配
              ▼
┌─────────────────────────────────────────┐
│  pinctrl-imx6ul.c 中的 probe：          │
│                                         │
│  staticintimx6ul_pinctrl_probe(...)   │
│  {                                      │
│      // 1. ioremap 寄存器基地址          │
│      // 2. 填充 pinctrl_desc            │
│      // 3. 填充引脚表、功能表            │
│      // 4. 调用 devm_pinctrl_register() │
│      //     → 阵营A就位                 │
│  }                                      │
└─────────────────────────────────────────┘

这个 probe 的职责是把阵营A注册进内核，让 pinctrl 子系统知道"这颗芯片有哪些引脚、支持哪些复用功能"。它在系统启动早期就完成了。

第二个 probe：使用 pinctrl 的外设驱动的 probe

设备树（板级 dts 中）：
┌─────────────────────────────────────────┐
│  &i2c1 {                                │
│      compatible = "fsl,imx6ul-i2c";    │
│      pinctrl-names = "default";         │
│      pinctrl-0 = <&pinctrl_i2c1>;      │
│  };                                     │
└─────────────────────────────────────────┘
              │
              │  compatible 匹配
              ▼
┌─────────────────────────────────────────┐
│  really_probe() 被调用                  │
│                                         │
│  ① pinctrl_bind_pins()  ← 自动执行     │
│     解析 pinctrl-0，配置引脚             │
│     阵营C → 阵营B → 写寄存器            │
│                                         │
│  ② i2c_imx_probe()  ← 驱动的 probe     │
│     此时引脚已配好，直接使用              │
└─────────────────────────────────────────┘

这个 probe 的职责是初始化外设本身（如初始化 I2C 控制器、注册 adapter 等）。而在它被调用之前，内核已经自动通过 pinctrl_bind_pins() 完成了引脚配置。

时间线

系统启动
  │
  ├── ① pinctrl 控制器 probe（系统早期）
  │     匹配 "fsl,imx6ul-iomuxc"
  │     → 注册 pinctrl_desc / pinctrl_dev
  │     → 阵营A就位
  │
  ├── ② I2C 驱动 probe（稍后）
  │     匹配 "fsl,imx6ul-i2c"
  │     → 内核先自动调用 pinctrl_bind_pins()
  │       → 解析设备树 pinctrl-0
  │       → 生成 pinctrl_map（阵营C）
  │       → 转换为 pinctrl_state/setting（阵营B）
  │       → 调用 set_mux + pin_config_set 写寄存器
  │     → 然后才调用 I2C 驱动的 probe()
  │
  └── ③ 其他外设驱动 probe（更后）
        ... 同样的流程 ...

了解完上面的两个probe后开始分析pinctrl底层实现流程第一步。

第一步：控制器注册（系统启动早期)

芯片厂商的 pinctrl 驱动 probe 时，把阵营A的数据注册进内核

芯片厂商在代码中静态定义好：
┌─────────────────────────────────────────────────────────┐
│  pinctrl_desc（能力说明书）                                │
│  ├── name = "pinctrl-imx6ul"                            │
│  ├── pins → pinctrl_pin_desc 数组                        │
│  │     [0]  { number=0,  name="GPIO1_IO00" }            │
│  │     [1]  { number=1,  name="GPIO1_IO01" }            │
│  │     ...                                               │
│  │     [41] { number=41, name="GPIO2_PB3" } ← I2C1_SCL  │
│  │     [42] { number=42, name="GPIO2_PB4" } ← I2C1_SDA  │
│  │     ...                                               │
│  ├── npins = 142                                         │
│  ├── pctlops → pinctrl_ops（引脚组查询回调）              │
│  ├── pmxops  → pinmux_ops（复用操作回调）                 │
│  └── confops → pinconf_ops（电气配置回调）                │
└─────────────────────────────────────────────────────────┘
              │
              │  调用 devm_pinctrl_register(&desc)
              ▼
┌─────────────────────────────────────────────────────────┐
│  pinctrl_dev（运行时实例，核心层自动创建）                  │
│  ├── desc → 指向上面的 pinctrl_desc                      │
│  ├── pin_desc_tree → 把 142 个 pinctrl_pin_desc 建成索引 │
│  ├── gpio_ranges → 空（后续 GPIO 子系统来填充）           │
│  └── node → 挂入全局 pinctrl_list 链表                   │
└─────────────────────────────────────────────────────────┘

• 此时阵营A就位了，但还没有任何外设来"使用"这些引脚。pinctrl_dev 是核心层根据 pinctrl_desc 创建的运行时对象，desc 是"图纸"，dev 是"施工后的实体"。

第二步：设备树解析（外设 probe 前）

当 I2C1 设备匹配到驱动后，内核在调用 probe 之前，先解析设备树中的 pinctrl-0：

设备树中的原始数据：
  &i2c1 {
      pinctrl-names = "default";
      pinctrl-0 = <&pinctrl_i2c1>;
  };

  pinctrl_i2c1: i2c1grp {
      fsl,pins = <
0x00900x031C0x05880x20x00x4001b8b0
0x00940x03200x058C0x20x00x4001b8b0
      >;
  };
              │
              │  核心层调用阵营A中 pinctrl_ops 的 dt_node_to_map() 回调
              │  （这是芯片厂商实现的，不同芯片解析方式不同）
              ▼
┌─────────────────────────────────────────────────────────┐
│  pinctrl_map 数组（阵营C，翻译产物）                       │
│                                                         │
│  map[0]:                                                │
│    dev_name      = "21a0000.i2c"     ← 谁要用            │
│    name          = "default"         ← 什么状态下用       │
│    type          = MUX_GROUP         ← 这是复用配置       │
│    ctrl_dev_name = "pinctrl-imx6ul"  ← 找哪个控制器      │
│    data.mux = { group="i2c1", function="i2c1" }         │
│                                                         │
│  map[1]:                                                │
│    dev_name      = "21a0000.i2c"                         │
│    name          = "default"                             │
│    type          = CONFIGS_GROUP     ← 这是电气配置       │
│    ctrl_dev_name = "pinctrl-imx6ul"                      │
│    data.configs = { group="i2c1", configs={0x4001b8b0} }│
└─────────────────────────────────────────────────────────┘

• pinctrl_map 是临时翻译产物，它把设备树中芯片厂商自定义的 fsl,pins 格式翻译成核心层能统一处理的标准格式。翻译完成后，它的使命基本结束。

第三步：转换为运行时状态结构

核心层将 pinctrl_map 进一步转化为阵营B的链表结构：

pinctrl_map（临时，翻译完即弃）
              │
              │  核心层内部转换
              ▼
┌──────────────────────────────────────────────────────────────────┐
│  pinctrl（阵营B，I2C1 设备专属）                                  │
│  ├── dev → 指向 I2C1 设备                                        │
│  ├── state → 当前激活的状态（初始为 NULL，select 后指向 default） │
│  └── states 链表：                                               │
│      │                                                           │
│      └── pinctrl_state "default"                                 │
│          ├── name = "default"                                    │
│          └── settings 链表：                                     │
│              │                                                   │
│              ├── pinctrl_setting [0]                             │
│              │   type = MUX_GROUP                                │
│              │   pctldev → 指向阵营A的 pinctrl_dev  ◄──────── 关键连接！
│              │   data.mux = { func=3, group=7 }                  │
│              │                                                   │
│              └── pinctrl_setting [1]                             │
│                  type = CONFIGS_GROUP                            │
│                  pctldev → 指向阵营A的 pinctrl_dev  ◄──────── 关键连接！
│                  data.configs = { group=7, configs={0x4001b8b0} }│
└──────────────────────────────────────────────────────────────────┘

• pinctrl_setting 中的 pctldev 指针是整个系统的核心连接点——它把消费者侧的配置需求（阵营B）和控制器侧的执行能力（阵营A）桥接在一起。

第四步：执行配置（写寄存器）

pinctrl_select_state(p, "default")
    │
    │  遍历 default 状态下的 settings 链表
    ▼
setting[0]: type = MUX_GROUP
    │
    │  通过 pctldev 找到控制器
    │  通过 pctldev->desc->pmxops 找到回调函数
    ▼
pctldev->desc->pmxops->set_mux(pctldev, func=3, group=7)
    │
    │  控制器驱动内部：
    │  根据 group=7 查表找到该 group 包含的引脚 [41, 42]
    │  对每个引脚写 MUX 寄存器
    ▼
writel(mux_value, base + 0x0090)   ← Pin 41 (SCL) 的 MUX 寄存器
writel(mux_value, base + 0x0094)   ← Pin 42 (SDA) 的 MUX 寄存器

setting[1]: type = CONFIGS_GROUP
    │
    ▼
pctldev->desc->confops->pin_config_set(pctldev, pin, configs)
    │
    ▼
writel(0x4001b8b0, base + 0x031C)  ← Pin 41 的 PAD 寄存器
writel(0x4001b8b0, base + 0x0320)  ← Pin 42 的 PAD 寄存器

整体流程

┌─────────────────── 阵营A：控制器侧 ───────────────────┐
│                                                       │
│  pinctrl_desc ──────▶ pinctrl_dev                     │
│  (静态图纸)           (运行时实例)                      │
│       │                    │                           │
│       ├── pins[]           ├── desc → 回指 desc        │
│       │   pinctrl_pin_desc ├── pin_desc_tree           │
│       │                    └── node → 全局链表          │
│       │                                               │
│       ├── pctlops → pinctrl_ops                       │
│       │     └── dt_node_to_map()  ← 翻译设备树        │
│       │                                               │
│       ├── pmxops → pinmux_ops                         │
│       │     └── set_mux()  ← 写复用寄存器              │
│       │                                               │
│       └── confops → pinconf_ops                       │
│             └── pin_config_set()  ← 写电气寄存器       │
│                                                       │
└───────────────────────────┬───────────────────────────┘
                            │
                  pctldev 指针桥接
                            │
┌───────────────────────────▼───────────────────────────┐
│                                                       │
│  ┌─────────── 阵营C：桥梁 ──────────┐                 │
│  │  pinctrl_map（临时翻译产物）      │                 │
│  │  设备树原始数据 → 标准格式        │                 │
│  └──────────────┬───────────────────┘                 │
│                 │ 转换                                 │
│                 ▼                                      │
│  ┌─────────── 阵营B：消费者侧 ──────┐                 │
│  │  pinctrl                         │                 │
│  │  └── pinctrl_state "default"     │                 │
│  │      └── pinctrl_setting         │                 │
│  │          ├── pctldev ────────────────── 指向阵营A   │
│  │          ├── type = MUX/CONFIGS  │                 │
│  │          └── data = {func, group}│                 │
│  └──────────────────────────────────┘                 │
│                                                       │
└───────────────────────────────────────────────────────┘

阵营A（desc/dev/ops）是芯片厂商告诉内核"我有什么能力"；阵营C（map）是设备树配置被翻译成的标准中间格式；阵营B（pinctrl/state/setting）是每个外设设备最终持有的、可直接执行的配置队列。数据从 A → C → B → A 单向流动，pinctrl_setting 中的 pctldev 指针是连接消费者需求和控制器能力的唯一桥梁。

使用pinctrl 例子

下面基于 i.MX6ULL 平台，给出两个完整的 pinctrl 使用示例。

示例一：LED 灯点亮

1.设备树

/ {
/*
     * LED 设备节点
     * 使用内核自带的 gpio-leds 驱动，无需自己写驱动
     * compatible 匹配 drivers/leds/leds-gpio.c
     */
    leds {
        compatible = "gpio-leds";

/* 板子上的用户 LED，连接到 GPIO1_IO18 */
        user_led {
            label = "board:user_led";          /* sysfs 中显示的名字 */
            gpios = <&gpio1 18 GPIO_ACTIVE_HIGH>; /* GPIO1 的第 18 号引脚，高电平点亮 */
default-state = "off";             /* 默认关闭 */
            linux,default-trigger = "none";    /* 不使用自动触发 */

/*
             * 引用 pinctrl 配置节点
             * 内核会在 probe 前自动将 GPIO1_IO18 配置为 GPIO 模式
             */
            pinctrl-names = "default";
            pinctrl-0 = <&pinctrl_user_led>;
        };
    };
};

/*
 * IOMUXC 控制器节点中添加 pinctrl 配置
 * &iomuxc 是芯片级 dtsi 中已定义的 pinctrl 控制器
 */
&iomuxc {
/*
     * pinctrl_user_led：LED 引脚的复用和电气配置
     *
     * MX6UL_PAD_UART1_TX_DATA__GPIO1_IO18 是宏，展开后包含：
     *   mux_reg 偏移 = 0x0074
     *   conf_reg 偏移 = 0x0300
     *   input_reg 偏移 = 0x0000（GPIO 输出不需要输入选择）
     *   mux_mode = 5（ALT5 = GPIO 功能）
     *   input_val = 0
     *
     * 0x17059 是 PAD 电气属性配置值：
     *   HYS=1（施密特触发器，抗干扰）
     *   PUS=11（22K 上拉）
     *   PUE=1（使用上下拉模式）
     *   PKE=1（使能）
     *   SPEED=10（100MHz 中速）
     *   DSE=100（R0/4 中等驱动能力）
     *   SRE=1（快压摆）
     */
    pinctrl_user_led: user_led_grp {
        fsl,pins = <
            MX6UL_PAD_UART1_TX_DATA__GPIO1_IO18  0x17059
        >;
    };
};

2.驱动代码

/*
 * 本例使用内核自带的 gpio-leds 驱动（drivers/leds/leds-gpio.c），
 * 无需编写自定义驱动。内核通过 compatible = "gpio-leds" 自动匹配。
 *
 * 下面展示如果不用 gpio-leds 驱动，自己写一个最简 LED 驱动是什么样的。
 * 实际项目中推荐直接使用 gpio-leds，这里仅作教学演示。
 */

#include<linux/module.h>
#include<linux/platform_device.h>
#include<linux/gpio/consumer.h>    /* GPIO descriptor API */
#include<linux/of.h>
#include<linux/sysfs.h>
#include<linux/device.h>

structmy_led_data {
structgpio_desc *led_gpio;/* GPIO 描述符，由 gpiod_get 获取 */
int state;                      /* 当前 LED 状态：0=灭，1=亮 */
};

/*
 * 通过 sysfs 属性节点控制 LED
 * 用户空间执行：echo 1 > /sys/devices/.../state
 */
staticssize_tstate_show(struct device *dev,
                          struct device_attribute *attr, char *buf)
{
structmy_led_data *data = dev_get_drvdata(dev);
returnsprintf(buf, "%d\n", data->state);
}

staticssize_tstate_store(struct device *dev,
                           struct device_attribute *attr,
constchar *buf, size_t count)
{
structmy_led_data *data = dev_get_drvdata(dev);
int val;

if (kstrtoint(buf, 10, &val) < 0)
return -EINVAL;

    data->state = val ? 1 : 0;

/*
     * gpiod_set_value：设置 GPIO 电平
     * 内部会检查 pinctrl 是否已将该引脚配置为 GPIO 功能
     * 如果 pinctrl 未正确配置，这里可能无法正常工作
     */
    gpiod_set_value(data->led_gpio, data->state);

return count;
}

staticDEVICE_ATTR_RW(state);

staticintmy_led_probe(struct platform_device *pdev)
{
structmy_led_data *data;
int ret;

    data = devm_kzalloc(&pdev->dev, sizeof(*data), GFP_KERNEL);
if (!data)
return -ENOMEM;

/*
     * 获取 GPIO 描述符
     * "led" 对应设备树中 gpios = <...> 的属性名
     * GPIOD_OUT_LOW 表示初始化为输出、低电平
     *
     * 注意：在调用 probe 之前，内核已经通过 pinctrl_bind_pins()
     * 将 GPIO1_IO18 的 MUX 寄存器设置为 ALT5（GPIO 模式），
     * 所以这里可以直接请求 GPIO 使用
     */
    data->led_gpio = devm_gpiod_get(&pdev->dev, "led", GPIOD_OUT_LOW);
if (IS_ERR(data->led_gpio)) {
        dev_err(&pdev->dev, "Failed to get GPIO\n");
return PTR_ERR(data->led_gpio);
    }

/* 创建 sysfs 属性节点 */
    ret = device_create_file(&pdev->dev, &dev_attr_state);
if (ret) {
        dev_err(&pdev->dev, "Failed to create sysfs entry\n");
return ret;
    }

    platform_set_drvdata(pdev, data);
    dev_info(&pdev->dev, "My LED driver probed\n");

return0;
}

staticintmy_led_remove(struct platform_device *pdev)
{
    device_remove_file(&pdev->dev, &dev_attr_state);
return0;
}

/* 匹配表：compatible = "my,custom-led" */
staticconststructof_device_idmy_led_of_match[] = {
    { .compatible = "my,custom-led", },
    { /* sentinel */ }
};
MODULE_DEVICE_TABLE(of, my_led_of_match);

staticstructplatform_drivermy_led_driver = {
    .probe  = my_led_probe,
    .remove = my_led_remove,
    .driver = {
        .name = "my-custom-led",
        .of_match_table = my_led_of_match,
    },
};
module_platform_driver(my_led_driver);

MODULE_LICENSE("GPL");
MODULE_AUTHOR("Demo");
MODULE_DESCRIPTION("Custom LED driver using pinctrl + GPIO");

应用层代码

/*
 * led_ctrl.c
 * 用户空间控制 LED 的应用程序
 *
 * 使用内核自带 gpio-leds 驱动时，通过 sysfs 控制：
 *   echo 1 > /sys/class/leds/board:user_led/brightness   点亮
 *   echo 0 > /sys/class/leds/board:user_led/brightness   熄灭
 *
 * 使用自定义驱动时，通过自定义 sysfs 节点控制：
 *   echo 1 > /sys/devices/.../state   点亮
 *   echo 0 > /sys/devices/.../state   熄灭
 *
 * 本程序演示通过 sysfs 文件操作来控制 LED
 */

#include<stdio.h>
#include<stdlib.h>
#include<string.h>
#include<fcntl.h>
#include<unistd.h>

/* 内核自带 gpio-leds 驱动的 sysfs 路径 */
#define LED_BRIGHTNESS_PATH  "/sys/class/leds/board:user_led/brightness"

/*
 * 向 sysfs 文件写入一个字符（'0' 或 '1'）
 * 返回值：0 成功，-1 失败
 */
staticintwrite_sysfs(constchar *path, constchar *value)
{
int fd;

    fd = open(path, O_WRONLY);
if (fd < 0) {
        perror("open sysfs failed");
return-1;
    }

if (write(fd, value, strlen(value)) < 0) {
        perror("write sysfs failed");
        close(fd);
return-1;
    }

    close(fd);
return0;
}

intmain(int argc, char *argv[])
{
if (argc < 2) {
printf("用法: %s <on|off|blink>\n", argv[0]);
printf("  on    - 点亮 LED\n");
printf("  off   - 熄灭 LED\n");
printf("  blink - 让 LED 以 heartbeat 模式闪烁\n");
return-1;
    }

if (strcmp(argv[1], "on") == 0) {
/* 写入 "1" 点亮 LED */
        write_sysfs(LED_BRIGHTNESS_PATH, "1");
printf("LED 已点亮\n");

    } elseif (strcmp(argv[1], "off") == 0) {
/* 写入 "0" 熄灭 LED */
        write_sysfs(LED_BRIGHTNESS_PATH, "0");
printf("LED 已熄灭\n");

    } elseif (strcmp(argv[1], "blink") == 0) {
/*
         * 切换到 heartbeat 触发模式
         * gpio-leds 驱动会自动让 LED 按心跳节奏闪烁
         */
        write_sysfs("/sys/class/leds/board:user_led/trigger", "heartbeat");
printf("LED 已进入 heartbeat 闪烁模式\n");
    } else {
printf("未知命令: %s\n", argv[1]);
return-1;
    }

return0;
}

示例二：I2c 读取温度

设备树