Zephyr Pinctrl -- 2设备树节点属性和值

本文说明如何查找pinctrl设备树的配置属性和值。

在Zephyr Pinctrl – 1基础配置使用一文中说明了如何通过pinctrl设备树对soc片上设备进行引脚复用和配置，本文继续说明这些复用和配置项的来源，也就是我们从哪里去找到这些节点和值。

节点和值的查找方法

Zephyr文档

Zephyr的所有设备树绑定的节点都在https://docs.zephyrproject.org/3.3.0/build/dts/api/bindings.html中可以找到
以nxp的rt1062为例：

1. 通过ctrl+f在该网页内查找nxp,找到soc的vendor商
2. 在NXP Semiconductors (nxp)下面的列表中找到rt的pinctrl链接”nxp,mcux-rt-pinctrl”
3. 在Description章节中可以看到概述性的介绍并示例如何使用
4. 在Properties章节就可以看到有那些属性和可配置的值，对于属性通常只关注Grandchild node properties小节

绑定文件

Zephyr设备属性和值可以全部在绑定文件中找到，路径为zephyr/dts/bindings/pinctrl
以nxp的rt1062为例
对应的文件为nxp,mcux-rt-pinctrl.yaml
最开始部分是对该系列芯片pinctrl的描述，概述性的介绍如何使用

description: |
  The node has the 'pinctrl' node label set in MCUX RT SoC's devicetree. These
  nodes can be autogenerated using the MCUXpresso config tools combined with
  the rt_dts_gen.py script in NXP's HAL. The mux, mode, input, daisy, and cfg
  fields in a group select the pins to be configured, and the remaining
  devicetree properties set configuration values for those pins
  for example, here is an group configuring LPUART1 pins:
...

接下来是compatible, 设备树引用时会指定该compatible

compatible: "nxp,mcux-rt-pinctrl"

在child-binding:中对pinctrl支持的属性进行描述

child-binding:
  description: MCUX RT pin controller pin group
  child-binding:
    description: |
      MCUX RT pin controller pin configuration node.
# 指定可以使用pincfg-node.yaml中的那些属性
    include:
      - name: pincfg-node.yaml
        property-allowlist:
          - input-schmitt-enable
          - drive-open-drain
          - input-enable
          - bias-disable
          - bias-pull-down
          - bias-pull-up
# properties中描述了该soc特定的属性，可以
    properties:

# 引脚复用属性，每个soc都会有，但值不一样，后面会详细说明
      pinmux:
        required: true
        type: phandles
        description: |
          Pin mux selections for this group. See the soc level iomuxc DTSI file
          for a defined list of these options.
# 覆盖pincfg-node.yaml中定义的属性，但值是该soc特有的，例如drive-strength
      drive-strength:
        required: true
        type: string
        enum:
          - "disabled"
          - "r0"
          - "r0-2"
          - "r0-3"
          - "r0-4"
          - "r0-5"
          - "r0-6"
          - "r0-7"
# 该soc特有的属性，其它soc不具备，例如`nxp,speed`
      nxp,speed:
        type: string
        enum:
          - "50-mhz"
          - "100-mhz"
          - "150-mhz"
          - "200-mhz"
        description: |
          Sets pin speed. Corresponds to SPEED field in IOMUXC peripheral
          00 SPEED_0_low_50MHz_ — low(50MHz)
          01 SPEED_1_medium_100MHz_ — medium(100MHz)
          10 SPEED_2_medium_150MHz_ — medium(150MHz)
          11 SPEED_3_max_200MHz_ — max(200MHz)

引脚复用

引脚复用使用pinmux属性描述，不同的soc会使用不同的值，这里以rt1062和esp32c3为例进行说明

rt1062 pinmux

在nxp,mcux-rt-pinctrl.yaml中定义如下

pinmux:
  required: true
  type: phandles
  description: |
    Pin mux selections for this group. See the soc level iomuxc DTSI file
    for a defined list of these option

pinmux的type为phandles，要参考soc level的iomuxc dtsi文件，对于rt1062的dtsi放置在外部hal模块中，路径为modules/hal/nxp/nxp_imx/rt/, 不同soc型号需要选择不同的文件，例如这里选择mimxrt1062dvl6a-pinctrl.dtsi, 打开后就可以看到rt1062dv16a pimux的备选值, 摘取如下：

/omit-if-no-ref/ iomuxc_gpio_ad_b1_01_lpi2c1_sda: IOMUXC_GPIO_AD_B1_01_LPI2C1_SDA {
	pinmux = <0x401f8100 3 0x401f84d0 1 0x401f82f0>;
};
/omit-if-no-ref/ iomuxc_gpio_ad_b1_01_lpuart2_rts_b: IOMUXC_GPIO_AD_B1_01_LPUART2_RTS_B {
	pinmux = <0x401f8100 2 0x0 0 0x401f82f0>;
};

在配置rt1062 pinmux的时候就会看到如下内容对其进行引用

pinmux = <&iomuxc_gpio_ad_b1_01_lpi2c1_sda>,
				<&iomuxc_gpio_ad_b1_00_lpi2c1_scl>;

esp32c3 pinmux

在espressif,esp32-pinctrl.yaml中定义如下

properties:
  pinmux:
    required: true
    type: array
    description: |
      Each array element represents pin muxing information of an individual
      pin. The array elements are pre-declared macros taken from Espressif's
      HAL.

pinmux的type为array，要参考对于espressuf定义在外部hal模块中宏，路径为modules/hal/espressif/include/dt-bindings/pinctrl/esp32-pinctrl.h, 打开后就可以看到pimux的备选值, 摘取如下：

#define SPIM2_MISO_GPIO1 \
	ESP32_PINMUX(1, ESP_HSPIQ_IN, ESP_NOSIG)

#define SPIM2_MISO_GPIO2 \
	ESP32_PINMUX(2, ESP_HSPIQ_IN, ESP_NOSIG)

#define SPIM2_MISO_GPIO3 \
	ESP32_PINMUX(3, ESP_HSPIQ_IN, ESP_NOSIG)

在配置rt1062 pinmux的时候就会看到如下内容对其进行引用

pinmux = <SPIM2_MISO_GPIO2>,
	 <SPIM2_SCLK_GPIO6>,
	 <SPIM2_CSEL_GPIO10>;

引脚配置

在zephyr/dts/bindings/pinctrl/pincfg-node.yaml中定义了一个”pincfg”节点的绑定规范。该节点用于描述单个管脚的配置。

- 这些属性并不是所有的硬件都支持
- 不同的硬件可能会支持部分或者全部属性
- 不同的硬件会根据自生的情况进行扩展，前面已经提到了这点

下面将pincfg-node.yaml抽象出来的引脚配置属性罗列如下
偏置

bias-disable	禁用偏置，为了延长电池寿命，可以禁用某些不必要的偏置电压
bias-high-#define SPIM2_MISO_GPIO1 \
	ESP32_PINMUX(1, ESP_HSPIQ_IN, ESP_NOSIG)
#define SPIM2_MISO_GPIO2 \
	ESP32_PINMUX(2, ESP_HSPIQ_IN, ESP_NOSIG)
#define SPIM2_MISO_GPIO3 \
	ESP32_PINMUX(3, ESP_HSPIQ_IN, ESP_NOSIG)impedance 高阻抗(附加禁用偏置)，在某些需要保证模拟电路精度的应用场景下使用，例如在传感器测量或音频处理中
bias-bus-hold 总线保持，相应的引脚会被设置为bus hold状态，并加入偏置电压。输入和输出间有正反馈
bias-pull-up 上拉，防止引脚处于浮动状态，从而避免电路的电位不稳定，输入控制信号、I2C总线、SPI总线
bias-pull-down 下拉 ，防止引脚处于浮动状态，从而避免电路的电位不稳定
bias-pull-pin-default 开机默认偏置状态

驱动

drive-push-pull 推挽输出，用于驱动电阻性负载或者需要驱动高电平信号的场合
drive-open-drain 开漏输出，低接地，高高阻态
drive-open-source 开源输出 低高阻态，高接电源
drive-strength 驱动能力mA
drive-strength-microamp 驱动能力uA

输入

input-enable 启用输入功能
input-disable 禁用输入功能
input-schmitt-enable 启用斯密特触发器
input-schmitt-disable 禁用斯密特触发器
input-debounce 去抖动时间us，0表示禁用

供电

power-source 供电电源选择
low-power-enable 启用低功耗
low-power-disable 禁用低功耗
sleep-hardware-state 系统进入低功耗时引脚状态

输出

output-disable 禁用输出
output-enable  启用输出
output-low 默认输出低
output-high 默认输出高

响应

slew-rate 控制引脚信号的上升和下降速率
skew-delay 控制引脚信号的延迟时间，可以调整信号时序的对齐

对于不同soc有不同的配置属性和值这里列举rt1062和esp32c3的

rt1062 pin配置属性和值

rt1062使用了pincfg-node.yaml包含的属性

• input-schmitt-enable
• drive-open-drain
• input-enable
• bias-disable
• bias-pull-down
• bias-pull-up

此外还覆盖和自定义了属性和值：

• drive-strength 驱动能力

  • “disabled” 输出驱动禁用
  • “r0” 157 Ohm impedance @3.3V, 260 Ohm impedance @1.8V
  • “r0-2” 78 Ohm @3.3V, 130 Ohm @1.8V
  • “r0-3” 53 Ohm @3.3V, 88 Ohm @1.8V
  • “r0-4” 39 Ohm @3.3V, 65 Ohm @1.8V
  • “r0-5” 32 Ohm @3.3V, 52 Ohm @1.8V
  • “r0-6” 32 Ohm @3.3V, 43 Ohm @1.8V
  • “r0-7” 26 Ohm @3.3V, 37 Ohm @1.8V

• bias-pull-up-value 上拉电阻，不设置默认47k

  • “unused” 不使用上拉
  • “47k”
  • “100k”
  • “22k”

• bias-pull-down-value 下拉电阻，只支持100k

• slew-rate 反转速率

  • “slow” 慢
  • “fast” 快

• nxp,speed 引脚速度

  • “50-mhz”
  • “100-mhz”
  • “150-mhz”
  • “200-mhz”

esp32c3 pin配置属性和值

esp32c3 pin的配置硬件特性使用下面内容，已被pincfg-node.yaml包含，因此没有自定义属性和值

• bias-disable
• bias-pull-down
• bias-pull-up
• drive-push-pull
• drive-open-drain
• input-enable
• output-enable
• output-high
• output-low

参考

https://docs.zephyrproject.org/3.3.0/hardware/pinctrl/index.html