一、先建立整体认识一个芯片引脚通常不是固定用途。同一个物理引脚可能支持 GPIO、UART_TX、SPI_MOSI、I2C_SDA 或 PWM 等功能。使用一个引脚时通常要解决两个问题这个引脚应该连接到哪个硬件功能如果它作为 GPIO 使用应该输出高电平还是低电平这两个问题分别由两个子系统负责pinctrl配置引脚的功能和电气属性 GPIO控制引脚的输入输出行为可以先记住pinctrl决定引脚“做什么”GPIO决定 GPIO “怎么工作”。二、GPIO 子系统1. GPIO 是什么GPIO 是 General-Purpose Input/Output 的缩写即通用输入输出。一个 GPIO 引脚通常可以工作在两种基本模式输入读取外部电平输出向外部输出高电平或低电平。常见用途按键 → GPIO 输入 LED → GPIO 输出 芯片中断信号 → GPIO 输入并支持中断 复位信号 → GPIO 输出2. GPIO 控制器GPIO 引脚通常由 GPIO 控制器统一管理GPIO 控制器 ├── GPIO 0 ├── GPIO 1 ├── GPIO 2 ├── ... └── GPIO NGPIO 控制器驱动负责设置 GPIO 输入或输出方向设置输出电平读取输入电平配置 GPIO 中断管理 GPIO 资源。设备驱动通常不直接操作 GPIO 控制器寄存器而是使用 GPIO 子系统提供的通用接口。3. GPIO 输入和输出输入模式下驱动读取引脚当前电平高电平 → 1 低电平 → 0输出模式下驱动控制引脚电平输出 1 → 高电平 输出 0 → 低电平4. 有效电平硬件信号的有效状态不一定是高电平。例如复位引脚可能是低电平有效RESET 0设备复位 RESET 1设备正常运行设备树可以这样表示reset-gpios gpio0 10 GPIO_ACTIVE_LOW;这表示使用gpio0的第 10 个 GPIO低电平是信号的有效状态。另一个例子enable-gpios gpio0 11 GPIO_ACTIVE_HIGH;需要区分物理电平引脚实际是高还是低逻辑状态设备驱动理解的有效还是无效。GPIO 框架可以帮助驱动按照逻辑有效电平使用 GPIO减少手动取反。三、pinctrl 子系统1. pinctrl 是什么pinctrl是 Pin Control 的缩写主要负责控制芯片引脚通常包含两类功能引脚复用选择引脚连接到哪个硬件模块引脚配置设置上拉、下拉、驱动强度、输入使能等电气属性。2. 引脚复用假设某个引脚支持GPIO1 UART0_TX SPI0_MOSI PWM0如果希望它作为 UART 发送引脚使用就要将它配置为UART0_TX如果希望它作为 GPIO 使用就要配置为GPIO1。这个过程叫 Pin Multiplexing简称 Pinmux即引脚复用。如果复用配置错误即使 GPIO 编号和驱动代码都正确硬件也可能无法工作。3. 引脚电气配置除了选择功能还可能需要配置上拉下拉无上下拉驱动强度输入使能输出使能施密特触发开漏模式边沿速度。例如按键输入可能需要上拉按键未按下 → 通过上拉保持高电平 按键按下 → 被拉到低电平I2C 引脚通常需要开漏和上拉配置。4. pinctrl 不负责业务电平pinctrl可以配置引脚功能和电气属性但通常不负责设备业务中的电平控制pinctrl把引脚配置成 GPIO并设置为上拉输入 GPIO读取这个 GPIO 当前是高电平还是低电平因此配置 GPIO 上拉 → pinctrl 将引脚切换为 UART 功能 → pinctrl 读取 GPIO 输入值 → GPIO 设置 GPIO 输出电平 → GPIO四、pinctrl 和 GPIO 的区别1. 核心区别对比项pinctrlGPIO主要职责引脚复用和电气配置通用输入输出控制解决的问题引脚连接哪个功能、如何配置电气特性GPIO 输出什么、输入什么典型操作选择 UART、SPI、I2C 或 GPIO 功能设置方向、读写电平常见设备树属性pinctrl-names、pinctrl-0*-gpios常见驱动接口pinctrl_select_state()gpiod_get()、gpiod_set_value()是否直接控制业务电平通常不负责负责2. 一个完整例子假设 LED 连接到芯片的某个引脚需要完成两件事将引脚设置为 GPIO 功能并配置上下拉和驱动能力设置 GPIO 输出高电平或低电平。前者由pinctrl完成后者由 GPIO 子系统完成pinctrl 配置引脚功能 │ ▼ GPIO 子系统获得 GPIO │ ▼ 驱动设置输出电平 │ ▼ LED 亮或灭3. 编号不能简单等同芯片文档中可能同时出现物理引脚编号pinctrl pin 编号GPIO 控制器内的 GPIO 编号Linux 中的 GPIO 描述符。这些编号可能不是同一个概念不能仅根据数字相同就认为它们代表同一个对象。应以 SoC 文档、GPIO 控制器驱动和设备树绑定为准。五、设备树中的 pinctrl1. pinctrl 状态设备树通常使用pinctrl-names和pinctrl-0描述设备需要的状态pinctrl { uart0_default: uart0-default { pins PA0, PA1; function uart0; bias-pull-up; }; }; uart0 { pinctrl-names default; pinctrl-0 uart0_default; status okay; };含义是定义一个名为uart0_default的引脚配置让PA0、PA1复用为uart0并让uart0设备使用该配置。不同 SoC 的 pinctrl 绑定写法可能不同不能完全照搬示例属性。2.pinctrl-namespinctrl-names default, sleep;表示设备有两个状态default正常工作状态sleep休眠状态。对应引用pinctrl-0 uart0_default; pinctrl-1 uart0_sleep;数字表示状态索引pinctrl-0对应pinctrl-names中第 0 个状态pinctrl-1对应第 1 个状态。3. 工作和休眠状态pinctrl { spi0_default: spi0-default { pins PA4, PA5, PA6, PA7; function spi0; }; spi0_sleep: spi0-sleep { pins PA4, PA5, PA6, PA7; function gpio; bias-pull-down; }; }; spi0 { pinctrl-names default, sleep; pinctrl-0 spi0_default; pinctrl-1 spi0_sleep; status okay; };可以理解为正常工作使用spi0_default系统休眠使用spi0_sleep。休眠状态可能用于降低漏电、避免引脚悬空、防止外设误动作或释放引脚。4. 常见配置属性具体属性依赖 SoC 的设备树绑定但常见概念包括bias-pull-up; // 上拉 bias-pull-down; // 下拉 bias-disable; // 禁止上下拉 drive-strength 8; // 驱动强度 input-enable; // 使能输入 output-high; // 输出高电平 output-low; // 输出低电平有些平台使用pins和function有些平台使用groups和function必须参考具体 pinctrl 驱动的绑定文档。六、设备树中的 GPIO1. GPIO 属性命名设备树中常见 GPIO 属性格式为功能名称-gpios例如led-gpios gpio0 20 GPIO_ACTIVE_HIGH; reset-gpios gpio0 21 GPIO_ACTIVE_LOW; enable-gpios gpio0 22 GPIO_ACTIVE_HIGH;属性名称中的前缀会影响驱动获取 GPIO 时使用的名称led-gpios → led reset-gpios → reset enable-gpios → enable2. LED 示例led0: led { compatible example,gpio-led; pinctrl-names default; pinctrl-0 led0_pin; led-gpios gpio0 20 GPIO_ACTIVE_HIGH; status okay; };其中pinctrl-0配置引脚复用和电气属性led-gpios指定 GPIO 控制器和 GPIOGPIO_ACTIVE_HIGH表示逻辑有效状态对应高电平驱动负责通过 GPIO 控制 LED。3. 按键示例key0: key { compatible gpio-keys; gpios gpio0 30 GPIO_ACTIVE_LOW; label user-key; linux,code KEY_ENTER; debounce-interval 10; };这个设备使用 GPIO 读取按键状态并可以产生输入事件。具体属性是否适用要以对应驱动的设备树绑定为准。4. GPIO 控制器引用led-gpios gpio0 20 GPIO_ACTIVE_HIGH;通常包含gpio0 GPIO 控制器 20 控制器中的 GPIO 编号 GPIO_ACTIVE_HIGH 有效电平标志参数的具体数量和含义由 GPIO 控制器绑定决定。5.gpio-hoggpio-hog用于让 GPIO 控制器初始化时自动申请并设置某个 GPIO不需要单独编写设备驱动gpio0 { status okay; power-enable-hog { gpio-hog; gpios 5 GPIO_ACTIVE_HIGH; output-high; line-name power-enable; }; };它表示由 GPIO 控制器自动占用 GPIO 5设置为输出并初始输出高电平。适合用于固定电源使能、固定复位释放和板级默认控制信号。如果 GPIO 需要复杂的运行时控制通常应由对应设备驱动管理。七、驱动中使用 pinctrl1. 获取 pinctrl驱动可以获取设备对应的 pinctrlstructpinctrl*pinctrl;pinctrldevm_pinctrl_get(dev);if(IS_ERR(pinctrl))returnPTR_ERR(pinctrl);如果只需要选择默认状态也可以使用pinctrldevm_pinctrl_get_select_default(dev);if(IS_ERR(pinctrl))returnPTR_ERR(pinctrl);2. 查找并切换状态structpinctrl_state*default_state;structpinctrl_state*sleep_state;default_statepinctrl_lookup_state(pinctrl,default);sleep_statepinctrl_lookup_state(pinctrl,sleep);pinctrl_select_state(pinctrl,default_state);设备进入休眠或恢复时可以切换状态pinctrl_select_state(pinctrl,sleep_state);3. 常见初始化顺序一个设备驱动通常可以按以下顺序初始化1. 选择 pinctrl 的 default 状态 2. 获取 GPIO、时钟、复位等资源 3. 设置 GPIO 初始方向和电平 4. 初始化硬件寄存器 5. 注册设备功能具体顺序取决于硬件要求。例如若设备复位释放前必须先配置引脚就需要根据芯片手册安排顺序。八、驱动中使用 GPIO1. 推荐使用 GPIO descriptor 接口现代 Linux 驱动通常使用 GPIO descriptor 接口而不是旧式整数 GPIO 编号structgpio_desc*gpio;gpiodevm_gpiod_get(dev,enable,GPIOD_OUT_LOW);if(IS_ERR(gpio))returnPTR_ERR(gpio);这里的enable对应enable-gpios ...;2. 设置输出电平gpiod_set_value_cansleep(gpio,1);gpiod_set_value_cansleep(gpio,0);对于可能睡眠的 GPIO 访问使用gpiod_set_value_cansleep()确认访问不会睡眠时可以使用gpiod_set_value()。选择哪个接口要看 GPIO 控制器和调用上下文。3. 获取输入 GPIOstructgpio_desc*status_gpio;status_gpiodevm_gpiod_get(dev,status,GPIOD_IN);if(IS_ERR(status_gpio))returnPTR_ERR(status_gpio);读取输入值intvalue;valuegpiod_get_value_cansleep(status_gpio);if(value0)returnvalue;如果设备树声明了有效电平GPIO descriptor 接口通常会帮助驱动按逻辑值使用它。4. 设置初始状态gpiodevm_gpiod_get(dev,reset,GPIOD_OUT_HIGH);常见方向参数GPIOD_IN GPIOD_OUT_LOW GPIOD_OUT_HIGH对于复位、使能等信号初始状态很重要否则设备启动时可能出现瞬时误动作。5. GPIO 中断GPIO 也可以作为中断输入sensor-int-gpios gpio0 12 GPIO_ACTIVE_LOW; interrupt-parent gpio0; interrupts 12 IRQ_TYPE_EDGE_FALLING;驱动通常需要获取 GPIO、将 GPIO 转换为 IRQ、申请中断并编写处理函数。具体实现应优先遵循设备树绑定避免重复描述同一个中断来源。九、pinctrl 和 GPIO 的协作以 GPIO 控制的复位信号为例pinctrl { sensor_reset_pin: sensor-reset-pin { pins PA10; function gpio; bias-pull-up; }; }; sensor48 { compatible example,sensor; pinctrl-names default; pinctrl-0 sensor_reset_pin; reset-gpios gpio0 10 GPIO_ACTIVE_LOW; status okay; };驱动初始化大致经历选择 pinctrl default 状态 │ ▼ PA10 被配置为 GPIO 功能 │ ▼ 设置上拉等电气属性 │ ▼ 获取 reset GPIO │ ▼ 输出复位有效电平 │ ▼ 延时后释放复位 │ ▼ 初始化传感器两者职责分别是pinctrlPA10 使用 GPIO 功能、使用上拉、使用指定驱动强度 GPIO获取 gpio0 的 GPIO 10输出低电平进行复位再输出高电平释放复位十、常见问题与排查问题一GPIO 编号正确但引脚没有反应优先检查pinctrl 是否将引脚配置成 GPIO 功能GPIO 控制器是否启用GPIO 方向是否正确GPIO 有效电平是否正确是否有其他设备占用了该 GPIO硬件连接和电源是否正确。问题二驱动无法获取 GPIO可能原因设备树属性名与驱动获取名称不一致*-gpios拼写错误GPIO 控制器引用错误GPIO 编号超出范围GPIO 已被其他设备占用GPIO 控制器驱动没有加载设备节点没有启用。例如驱动使用devm_gpiod_get(dev,reset,GPIOD_OUT_LOW);设备树应包含类似reset-gpios ...;如果使用的是rst-gpios驱动也应获取名称rst除非另有映射。问题三引脚被配置成错误功能如果设备树将引脚配置为 UARTfunction uart0;但驱动希望将它作为 GPIO 使用GPIO 控制可能无法生效因为引脚复用功能没有切换到 GPIO。问题四上拉下拉不生效可能原因使用了错误的 pinctrl 属性SoC 不支持该配置外部电阻覆盖了内部上下拉引脚当前没有使用预期状态设备树绑定格式与内核版本不一致。问题五休眠唤醒后设备异常检查是否定义了sleep和default状态休眠状态是否改变了引脚功能唤醒时是否重新选择default状态GPIO 初始电平是否导致设备误复位外部设备是否要求特定保持电平。问题六GPIO 电平逻辑反了例如硬件低电平有效但设备树写成reset-gpios gpio0 10 GPIO_ACTIVE_HIGH;这会导致驱动理解的有效状态与硬件相反。应根据原理图和芯片手册确认使用GPIO_ACTIVE_LOW还是GPIO_ACTIVE_HIGH。十一、调试方法1. 查看 pinctrl 状态一些内核系统会提供/sys/kernel/debug/pinctrl/可以查看ls/sys/kernel/debug/pinctrlcat/sys/kernel/debug/pinctrl/*/pinmux-pinscat/sys/kernel/debug/pinctrl/*/pinconf-pins常见调试文件包括pinmux-pins pinconf-pins pins gpio-ranges这些文件可以帮助确认当前引脚复用到了哪个功能哪个设备占用了引脚引脚是否配置了上拉或下拉GPIO 与 pinctrl 的映射关系。具体文件名会因平台而变化。2. 查看 GPIO 信息部分系统可以查看cat/sys/kernel/debug/gpio可能看到 GPIO 控制器、GPIO 数量、已申请的 GPIO、输入输出方向、当前状态和使用者名称。3. 查看内核日志dmesg|grep-i-Egpio|pinctrl|pinmux重点关注probe()是否成功GPIO 是否申请失败pinctrl 状态是否查找失败引脚是否被占用控制器驱动是否初始化。4. 检查运行中的设备树ls/sys/firmware/devicetree/basels/sys/firmware/devicetree/base/soc需要注意运行中的设备树可能与源码目录中的 DTS 不同。排查时应确认 Bootloader 实际加载的是最新 DTB。十二、完整简化示例下面使用一个假想平台展示完整关系pinctrl { led0_pin: led0-pin { pins PA5; function gpio; bias-pull-down; drive-strength 4; }; }; led0: led { compatible example,gpio-led; pinctrl-names default; pinctrl-0 led0_pin; led-gpios gpio0 5 GPIO_ACTIVE_HIGH; status okay; };驱动中staticintled_probe(structplatform_device*pdev){structgpio_desc*led;leddevm_gpiod_get(pdev-dev,led,GPIOD_OUT_LOW);if(IS_ERR(led))returnPTR_ERR(led);gpiod_set_value_cansleep(led,1);return0;}对应关系pinctrl-0 led0_pin ├── 将 PA5 复用为 GPIO ├── 配置下拉 └── 配置驱动强度 led-gpios gpio0 5 GPIO_ACTIVE_HIGH ├── 使用 gpio0 的 GPIO 5 └── 高电平表示逻辑有效 devm_gpiod_get(..., led, ...) └── 获取设备树中的 led-gpios gpiod_set_value_cansleep(led, 1) └── 设置 LED 为逻辑有效状态十三、总结1. 核心区别pinctrl配置引脚 GPIO控制 GPIO更具体地说pinctrl决定引脚使用 GPIO、UART、SPI 还是其他功能pinctrl配置上拉、下拉、驱动强度等电气属性GPIO 子系统设置输入输出方向GPIO 子系统读写引脚电平GPIO 子系统可以将 GPIO 用作中断输入。2. 典型工作链路设备树定义 pinctrl 状态 │ ▼ pinctrl 配置引脚复用和电气属性 │ ▼ 设备树定义 *-gpios 资源 │ ▼ 驱动通过 GPIO descriptor 获取 GPIO │ ▼ 驱动设置方向、读取或输出电平3. 排查顺序当 GPIO 设备不能工作时可以依次排查设备节点是否存在status是否为okaypinctrl 状态是否正确引脚是否复用成 GPIOGPIO 控制器是否正常*-gpios属性名是否与驱动一致GPIO 编号和有效电平是否正确GPIO 是否被其他设备占用驱动是否成功进入probe()原理图、电源和外部上下拉是否正确。自测问题pinctrl和 GPIO 子系统分别负责什么为什么把引脚复用成 UART 后就不能直接当普通 GPIO 使用pinctrl-0和pinctrl-names之间是什么关系led-gpios为什么通常对应驱动中的ledGPIO_ACTIVE_LOW表示物理低电平还是逻辑有效状态为什么 GPIO 编号和 pinctrl pin 编号不能简单等同GPIO 获取成功但没有电平变化时应该检查哪些内容gpio-hog适合解决什么问题