linux 中的 pinctrl 子系统前置知识Linux 设备模型、设备树Device Tree、GPIO 基本概念1. 为什么需要 pinctrl1.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 早期引脚配置存在几个典型问题各平台代码重复每个 mach-* 目录都有自己的一套引脚配置代码接口不统一无法复用。配置时机混乱引脚配置写在板级文件board file里与驱动代码割裂驱动作者无法声明自己需要什么引脚状态。静态配置导致功耗浪费所有引脚在开机时一次性配置好即使外设休眠了引脚仍保持活动状态无法配合 runtime PM 省电。GPIO 与复用功能冲突引脚被复用为 I2C 后又被其他驱动当 GPIO 请求造成总线异常且难以定位。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 子系统管理的能力分为两块功能块英文职责典型配置项引脚复用Pinmux选择引脚连接到外设还是 GPIOfunction i2c0 / gpio / spi1 …引脚配置Pinconf配置引脚的电气特性bias-pull-up、drive-strength、slew-rate …有些 SoC 这两块在同一组寄存器里有些则分开pinctrl 框架允许驱动只实现其中一块但大多数驱动两块都实现。2.2 四个基本组织单位pinctrl 驱动把成千上万的引脚组织成四个层次的概念Pin引脚最小单位每个 pin 有全局唯一编号如pin 0 ~ pin 287。Group引脚组实现某个功能的一组 pin 的集合。例如 I2C0 需要 SDA SCL 两个引脚驱动里就定义一个 group如i2c0_xfer包含这两个 pin。功能是挂在 group 上而不是单个 pin 上——这是与裸机思维最大的不同。Function功能一个可选的复用功能如i2c0、gpio、spi1。一个 function 可以对应多个 group例如 I2C0 可以从两组不同引脚引出就有i2c0_xfer和i2c0m1_xfer两个 group 供板级选择。Map / State映射/状态设备树里一个 pinctrl 节点描述的某客户端设备在某个状态下使用哪些 group 什么电气配置。在客户端视角这叫state如default、sleep、idle。记忆模型上图要点客户端设备以state名义引用若干Group每个 Group 对应一个Function并包含若干Pin每个 Pin 再附带pinconf电气配置。3. 整体架构3.1 分层视图上图把 pinctrl 子系统从上到下分为四层Client各类外设驱动只感知default/sleep/idle等 state。pinctrl core统一维护 device / map / state通过pinctrl_ops、pinmux_ops、pinconf_ops向驱动层派发。SoC pinctrl driver各平台具体实现用pinctrl_desc描述全部引脚并操作寄存器。HardwareSoC 引脚控制器寄存器。此外pinctrl 还与GPIO 子系统、Runtime PM存在横向关联。3.2 源码位置路径内容drivers/pinctrl/core.cpinctrl 核心注册、map 解析、state 管理drivers/pinctrl/pinmux.cfunction/group 管理复用冲突检查drivers/pinctrl/pinconf.cpinconf 配置分发与 debugfsdrivers/pinctrl/devicetree.c设备树pinctrl-x属性解析include/linux/pinctrl/核心头文件consumer.h、machine.h、pinmux.h、pinconf.h 等drivers/pinctrl/pinctrl-*.c各 SoC 的 pinctrl 驱动Documentation/devicetree/bindings/pinctrl/各平台 pinctrl bindings 文档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 */structpinctrl_desc{constchar*name;conststructpinctrl_pin_desc*pins;/* 本 SoC 全部 pin 的表 */unsignedintnpins;conststructpinctrl_ops*pctlops;/* 组/功能枚举 */conststructpinmux_ops*pmxops;/* 复用选择 */conststructpinconf_ops*confops;/* 电气配置 */structmodule*owner;/* ... */};注册入口structpinctrl_dev*devm_pinctrl_register(structdevice*dev,structpinctrl_desc*pctldesc,void*driver_data);4.2 三组操作函数集操作集职责关键回调struct pinctrl_ops枚举 group/function处理 DT 节点get_groups_count、get_group_name、get_group_pins、dt_node_to_map、dt_free_mapstruct pinmux_ops复用选择与 GPIO 互通get_functions_count、set_mux核心、gpio_request_enable、strictstruct pinconf_ops电气配置读写pin_config_get、pin_config_set、pin_config_group_set、is_generic其中set_mux是 pinctrl 驱动真正的干活函数给定 function group写复用寄存器把引脚切到对应功能。4.3 客户端侧抽象状态structpinctrl;/* 一个客户端设备的 pinctrl 句柄 */structpinctrl_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: gpiofdd60000 { 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-casei2c0-xferlabel 采用snake_casei2c0_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.cpinctrl-names第 N 个名字 ↔pinctrl-N属性一一对应名字default是特殊的设备模型在驱动probe之前会自动 select 它pinctrl-N里可以挂多个 phandle多个配置片段合并成一个 state。5.4 常见 state 命名约定state 名语义内核自动处理default正常工作是probe 前自动 selectsleep休眠低功耗否驱动手动切换配合 runtime/system PMidle空闲否较少用initprobe 期间使用之后释放半自动pinctrl_bind_pins 处理5.5 各平台风格差异平台配置风格例子Rockchip一个属性打包bank pin func cfg-refrockchip,pinsSTM32分离pinmux 声明 mux bias电气属性单独写pinmux、bias-pull-up、drive-push-pulli.MX (fsl)紧凑数组mux_reg conf_reg input_reg mux_val input_val pad_valfsl,pins通用 pinctrl-single寄存器偏移 值的原始数组pinctrl-single,pins虽然风格不同但概念模型完全一致都是把一组 pin 设置成某 function 某电气配置。6. 客户端驱动如何使用 pinctrl6.1 最简单的情况什么都不用写绝大多数驱动只需在 DTS 里写好pinctrl-names default; pinctrl-0 xxx;—— 设备模型drivers/base/pinctrl.c的pinctrl_bind_pins()在 probe 前自动完成 get select。这就是 i2c/spi/serial 驱动里看不到 pinctrl 代码的原因。6.2 需要动态切换的驱动#includelinux/pinctrl/consumer.hstructmy_dev{structpinctrl*pctl;structpinctrl_state*st_active;structpinctrl_state*st_sleep;};staticintmy_probe(structplatform_device*pdev){structmy_dev*m/* ... */;m-pctldevm_pinctrl_get(pdev-dev);/* 获取句柄 */if(IS_ERR(m-pctl))returnPTR_ERR(m-pctl);m-st_activepinctrl_lookup_state(m-pctl,default);m-st_sleeppinctrl_lookup_state(m-pctl,sleep);/* ... */}staticintmy_suspend(structdevice*dev){structmy_dev*mdev_get_drvdata(dev);pinctrl_select_state(m-pctl,m-st_sleep);/* 引脚进入低功耗 */return0;}staticintmy_resume(structdevice*dev){structmy_dev*mdev_get_drvdata(dev);pinctrl_select_state(m-pctl,m-st_active);return0;}6.3 客户端 API 一览API用途devm_pinctrl_get()获取设备的 pinctrl 句柄资源托管推荐pinctrl_lookup_state()按名字查找 statepinctrl_select_state()应用一个 state做 mux confdevm_pinctrl_get_select_default()一步到位get select “default”pinctrl_pm_select_default_state()/_sleep_state()/_idle_state()PM 语义封装没有对应 state 时不报错pinctrl_gpio_request()/pinctrl_gpio_free()把某个 GPIO 对应的 pin 切到 gpio 功能7. 编写一个 SoC 的 pinctrl 驱动框架视角新平台移植时的最小骨架staticconststructpinctrl_pin_descfoo_pins[]{PINCTRL_PIN(0,P0),PINCTRL_PIN(1,P1),/* ... 全部 pin */};staticintfoo_get_groups_count(structpinctrl_dev*pctldev){...}staticconstchar*foo_get_group_name(structpinctrl_dev*pctldev,unsignedsel){...}staticintfoo_get_group_pins(structpinctrl_dev*pctldev,unsignedsel,constunsigned**pins,unsigned*npins){...}staticintfoo_dt_node_to_map(structpinctrl_dev*pctldev,structdevice_node*np,structpinctrl_map**map,unsigned*num_maps){...}staticconststructpinctrl_opsfoo_pctrl_ops{.get_groups_countfoo_get_groups_count,.get_group_namefoo_get_group_name,.get_group_pinsfoo_get_group_pins,.dt_node_to_mapfoo_dt_node_to_map,.dt_free_mappinctrl_utils_free_map,};staticintfoo_set_mux(structpinctrl_dev*pctldev,unsignedfunc,unsignedgroup){/* 查表找到 group 的 pins 目标 function 编号写复用寄存器 */return0;}staticconststructpinmux_opsfoo_pmxops{.get_functions_count...,.get_function_name...,.get_function_groups...,.set_muxfoo_set_mux,.gpio_request_enable...,.stricttrue,/* 禁止对已复用 pin 再申请 GPIO */};staticconststructpinconf_opsfoo_confops{.is_generictrue,/* 使用通用配置参数 */.pin_config_getfoo_pinconf_get,.pin_config_setfoo_pinconf_set,.pin_config_group_setfoo_pinconf_group_set,};staticstructpinctrl_descfoo_desc{.namefoo-pinctrl,.pinsfoo_pins,.npinsARRAY_SIZE(foo_pins),.pctlopsfoo_pctrl_ops,.pmxopsfoo_pmxops,.confopsfoo_confops,.ownerTHIS_MODULE,};staticintfoo_pinctrl_probe(structplatform_device*pdev){/* 映射寄存器、初始化私有数据然后 */returnPTR_ERR_OR_ZERO(devm_pinctrl_register(pdev-dev,foo_desc,priv));}要点dt_node_to_map是最花功夫的回调把板级 DTS 的引脚片段翻译成内核 map。很多平台用pinconf_generic_dt_node_to_map_group()辅助或干脆用pinctrl-single这类通用驱动免除自写。.strict true强烈推荐启用复用保护pin 已被 mux 为外设功能时拒绝 GPIO 申请能提前暴露大量板级配置错误。GPIO 互通pinctrl 驱动常和 GPIO 驱动是一对一个 bank 一个 gpio_chip通过gpio-ranges把两个子系统连起来。7.1 pinctrl-single不想写驱动的替代方案对于引脚配置就是往某偏移寄存器写值的简单控制器可直接用通用驱动pinctrl-singlepinmux { 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-pinspins输出的典型形态pin 32 (gpio1-0): device 3ff20000.i2c function i2c0 group i2c0-xfer pin 33 (gpio1-1): GPIO gpio1一行就能看到引脚被谁占用、复用成什么功能、属于哪个 group——排查引脚没反应类问题第一刀就砍这里。8.2 动态调试echofile drivers/pinctrl/* p/sys/kernel/debug/dynamic_debug/control8.3 常见故障速查表现象大概率原因排查动作probe 报-EBUSY申请 pinctrl 失败同一组 pin 被两个设备同时引用看 debugfs pins 里 owner 是谁外设无响应但无报错group 选错如用了 m0 引脚组实际板子走 m1对照原理图核对 bank/pin 编号信号有但幅度/速率异常drive-strength / slew-rate 不对查 pinconf调电气属性休眠唤醒后外设死掉sleep state 切过去没切回来或 sleep 配置写错检查 PM 回调里的 select_stateGPIO 操作影响外设没开.strictGPIO 与 mux 冲突未被发现pinctrl 驱动加 strictDTS 改了不生效客户端节点没写pinctrl-0引用或 label 拼错检查编译出的 dtbfdtdump9. 与其他系统的横向对比维度裸机/RTOS 常见做法Linux pinctrl配置位置散落在各驱动 init 函数里直接写寄存器集中在设备树驱动只声明要什么状态复用冲突靠人工 review运行期才发现内核自动检查申请时即报错功耗联动手写 suspend 里重新配引脚state 抽象 PM 框架联动可移植性换板子改一堆驱动代码只改 DTS驱动零改动对 RT-Thread 等 RTOS 而言引脚配置通常是各 BSP 的pinmux.c 一个rt_pin_*GPIO 框架复用管理远弱于 Linux pinctrl——这也是 Linux 在复杂 SoC 上的结构性优势之一。10. 总结一张图记住 pinctrl整个流程可以概括为设备树里的控制器节点定义引脚配置片段客户端设备节点通过pinctrl-N 片段引用这些片段内核解析后交给pinctrl core管理再经SoC pinctrl 驱动的 ops 回调写入寄存器最终在SoC 硬件引脚上生效。三句话收束pinctrl pinmux功能复用 pinconf电气配置的统一资源管理框架对驱动开发者90% 的工作是在 DTS 里写对 group、function、电气属性和 state 引用排障时 debugfs 的pins/pinmux-pins是最直接的事实来源。附录常用配置属性速查generic pinconfDTS 属性含义bias-disable关闭上下拉bias-pull-up/bias-pull-down上拉 / 下拉bias-pull-pin-default使用引脚默认上下拉drive-push-pull/drive-open-drain/drive-open-source推挽 / 开漏 / 开源输出drive-strength mA;驱动电流强度input-enable/input-disable输入使能input-schmitt-enable施密特触发输入slew-rate n;边沿速率档位output-high/output-low输出电平绑定文档Documentation/devicetree/bindings/pinctrl/pincfg-node.yaml