一、前置准备

pinctrl 调试信息通过 debugfs 文件系统暴露，默认挂载在 /sys/kernel/debug/pinctrl/。

确认 debugfs 已挂载：

mount | grep debugfs
## 若无输出，手动挂载：
mount -t debugfs none /sys/kernel/debug

泰山派 RK3566 的 pinctrl 调试根目录：

ls /sys/kernel/debug/pinctrl/
## 典型输出：
## pinctrl-devices  pinctrl-handles  pinctrl-maps  pinctrl-ranges  pinctrl-state  rk3566-pinctrl

---

二、全局映射信息（/sys/kernel/debug/pinctrl/）

2.1 pinctrl-devices

查看命令：

cat /sys/kernel/debug/pinctrl/pinctrl-devices

作用： 列出内核中所有已注册的 pinctrl 设备（控制器）。

参数解释：

字段	含义
device	pinctrl 控制器名称，如 rk3566-pinctrl
state	控制器当前全局状态，通常为 default
status	是否成功初始化并注册，ok 表示正常

泰山派典型输出示例：

device                   state    status
------------------------------------------------
rk3566-pinctrl           default  ok

---

2.2 pinctrl-handles

查看命令：

cat /sys/kernel/debug/pinctrl/pinctrl-handles

作用： 列出当前正在使用 pinctrl 的所有设备句柄，即哪些驱动已经申请并占用了 pinmux 资源。

参数解释：

字段	含义
handle	内核句柄地址（调试标识）
devname	申请 pinctrl 的设备名，如 ff470000.serial（UART5）、ff500000.i2c（I2C）
state	设备当前所处的 pinctrl 状态名，常见：default（正常工作）、sleep（休眠）
pinmux	当前激活的 function + group 组合，如 uart5_xfer

泰山派典型输出示例：

handle  devname                state    pinmux
------------------------------------------------
0x...   ff470000.serial        default  uart5_xfer
0x...   ff500000.i2c           default  i2c3_xfer

排查冲突技巧：如果你的 GPIO 控制失败，先查这里——如果目标引脚已被某个 devname 以 uart5/i2c3 等 function 占用，说明设备树中该引脚的复用功能未释放。

---

2.3 pinctrl-maps

查看命令：

cat /sys/kernel/debug/pinctrl/pinctrl-maps

作用： 列出设备树中定义的所有 device → pinctrl 映射关系。这是静态配置，反映 .dts 中的 pinctrl-0 声明。

参数解释：

字段	含义
device	消费者设备名（与设备树 compatible 对应）
state	映射的状态名（如 default、sleep）
function	复用功能名（如 gpio、uart5、pwm8）
group	引脚组名（如 uart5m1_xfer、pwm8m0_pins）

泰山派典型输出示例：

device                   state    function    group
--------------------------------------------------------
serial@ff470000          default  uart5       uart5m1_xfer
pwm@fe6f0010             default  pwm8        pwm8m0_pins

注意：pinctrl-maps 是设备树声明的映射，pinctrl-handles 是内核实际生效的映射。两者不一致通常意味着驱动 probe 失败或引脚冲突。

---

三、芯片级引脚详情（/sys/kernel/debug/pinctrl/rk3566-pinctrl/）

RK3566 的 pinctrl 控制器目录名为 rk3566-pinctrl，进入该目录查看具体引脚状态。

cd /sys/kernel/debug/pinctrl/rk3566-pinctrl/
ls
## 输出：functions  pinconf-pins  pingroups  pinmux-pins  pins  pinmux-functions

---

3.1 查看所有已注册的 pins

查看命令：

cat /sys/kernel/debug/pinctrl/rk3566-pinctrl/pins

作用： 列出芯片所有物理引脚及其当前复用状态。

参数解释：

字段	含义
pin	内核分配的全局 pin 编号（从0递增）
name	引脚名称，RK3566 格式为 GPIOx_yz，如 GPIO0_A0、GPIO3_B1
gpio	若当前复用为 GPIO，显示 gpiochip 编号和偏移（如 224 表示 gpiochip 内的 offset）；-1 表示未作为 GPIO 使用
mux	当前复用功能（mux mode），0 通常为 GPIO，1~N 为外设功能（如 UART/I2C/SPI/PWM）
func	当前功能名，如 gpio、uart5、pwm8
dev	占用该引脚的设备名，空闲时显示 (null)

泰山派典型输出示例（节选）：

pin 0   (GPIO0_A0)      gpio 0    mux 0    func gpio    dev (null)
pin 33  (GPIO3_B1)      gpio 97   mux 1    func pwm8    dev ff6f0010.pwm
pin 34  (GPIO3_B2)      gpio 98   mux 0    func gpio    dev (null)

排查技巧：

• dev (null)：该引脚空闲，可被 GPIO 子系统申请。
• dev ff470000.serial：该引脚已被 UART5 占用，此时即使设备树中标记为 status = "okay" 的 GPIO 节点也无法使用此引脚。

---

3.2 查看 pin groups

查看命令：

cat /sys/kernel/debug/pinctrl/rk3566-pinctrl/pingroups

作用： 列出设备树中定义的所有引脚组（group）。一个 group 是一组一起切换复用功能的引脚。

参数解释：

字段	含义
group	引脚组名称，通常以功能+位置命名，如 uart5m1_xfer、pwm8m0_pins
pins	组内包含的物理引脚列表

泰山派典型输出示例：

group: uart5m1_xfer
pin 64 (GPIO4_A0)
pin 65 (GPIO4_A1)

group: pwm8m0_pins
pin 33 (GPIO3_B1)

含义：pwm8m0_pins 表示 PWM8 功能使用 GPIO3_B1 引脚（对应泰山派 40Pin 的 Pin 33）。

---

3.3 查看 functions 及占用的 gpio groups

查看命令：

cat /sys/kernel/debug/pinctrl/rk3566-pinctrl/functions

作用： 列出所有可复用的功能（function），以及每个功能关联的引脚组。

参数解释：

字段	含义
function	复用功能名，如 gpio、uart5、i2c3、pwm8、spi3
group	该功能可用的引脚组，一个功能可能有多个 group（对应不同引脚位置）

泰山派典型输出示例：

function: uart5
group: uart5m0_xfer
group: uart5m1_xfer

function: pwm8
group: pwm8m0_pins
group: pwm8m1_pins

含义：uart5 有两个可选 group——uart5m0 和 uart5m1。设备树中通过 pinctrl-0 = <&uart5m1_xfer> 选择具体使用哪一组引脚。

---

3.4 pinconf（引脚电气配置）

查看命令：

cat /sys/kernel/debug/pinctrl/rk3566-pinctrl/pinconf-pins

作用： 查看每个引脚的电气参数配置（上下拉、驱动强度、压摆率等）。

参数解释：

参数	含义	常见值
bias-pull-up	内部上拉使能	引脚空闲时保持高电平
bias-pull-down	内部下拉使能	引脚空闲时保持低电平
bias-disable	上下拉禁用	高阻态，用于外部已有上下拉的场景
drive-strength	驱动强度	如 <8> 表示 8mA，<12> 表示 12mA，值越大驱动能力越强
input-schmitt-enable	施密特触发器使能	增强抗干扰能力，常用于按键/慢速信号
slew-rate	压摆率	控制信号跳变速度，高速信号需快压摆率

泰山派典型输出示例（节选）：

pin 33 (GPIO3_B1): drive-strength = 8, bias-pull-up
pin 34 (GPIO3_B2): drive-strength = 8, bias-disable

排查技巧：

• 如果舵机/SG90 驱动无力或信号波形畸变，检查 drive-strength 是否过小（建议 ≥ 8mA）。
• 如果按键误触发，检查是否使能了 input-schmitt-enable 和合适的上下拉。

---

四、快速排查流程图

引脚工作异常？
    │
    ▼
cat pinctrl-handles  ──►  目标引脚是否已被其他设备占用？
    │                         │
    │ 是                      │ 否
    ▼                         ▼
查看 devname                 cat pins
修改设备树释放该引脚          确认 mux/func 是否为 gpio
    │                         │
    ▼                         ▼
重新编译 dtb                 cat pinconf-pins
                             检查 drive-strength / 上下拉

---

五、总结

调试文件	查看命令	核心作用
pinctrl-devices	cat /sys/kernel/debug/pinctrl/pinctrl-devices	确认 pinctrl 控制器是否注册成功
pinctrl-handles	cat /sys/kernel/debug/pinctrl/pinctrl-handles	查看动态占用情况，定位引脚冲突
pinctrl-maps	cat /sys/kernel/debug/pinctrl/pinctrl-maps	查看设备树静态映射声明
pins	cat /sys/kernel/debug/pinctrl/rk3566-pinctrl/pins	查看所有引脚当前复用状态
pingroups	cat /sys/kernel/debug/pinctrl/rk3566-pinctrl/pingroups	查看 group 与物理引脚对应关系
functions	cat /sys/kernel/debug/pinctrl/rk3566-pinctrl/functions	查看功能与 group 的映射
pinconf-pins	cat /sys/kernel/debug/pinctrl/rk3566-pinctrl/pinconf-pins	查看电气参数（驱动强度、上下拉）