当前文档版本为 v0.8.0，您可以访问当前页面的 开发中 版本以获取最近可能的更新。

Driver: Pinmux

1 功能概述

pinmux sample演示了Zephyr PINMUX Driver在PAN1080 SoC上的使用方法，主要包括：

  • 开启/关闭SoC内部上拉/下拉电阻通路开关

  • 切换某个IO引脚的多功能引脚MFP (Multi-Function Pin) 功能配置

硬件上，PAN1080 PINMUX与GPIO是密切相关的，其框图如下所示：

image

GPIO/PINMUX模块框图

其中与PINMUX相关的有：

  • PUEN对应PINMUX的上拉电阻通路开关

  • PDEN对应PINMUX的下拉电阻通路开关

  • DINOFF对应PINMUX的数字输入通路开关

  • SYSTEM IOMUX对应PINMUX的多功能引脚MFP功能配置

2 环境准备

  • PAN1080 EVB 一块

  • USB-TypeC 线一条（用于供电和查看串口打印 Log）

  • 硬件接线：

    • 使用 USB 线，将 PC USB 与 EVB USB-TypeC（USB->UART）相连

    • 根据 EVB 核心板芯片的封装不同，使用杜邦线将 EVB 底板上的:

      • TX0 与 P00 相连， RX0 与 P01 相连（若 EVB 板芯片为 QFN32 或 LQFP64 封装）

      • TX0 与 P30 相连， RX0 与 P31 相连（若 EVB 板芯片为 QFN48 封装）

  • PC 软件: 串口调试助手（UartAssist）或终端工具（SecureCRT），波特率921600

3 编译和烧录

例程位置：zephyr\samples_panchip\drivers\pinmux

使用 ZAL 工具可以对其进行编译、烧录、打开 VS Code 调试等操作。关于 ZAL 工具的详细介绍请参考：Zephyr APP Launcher 工具介绍。

4 演示说明

本例程包含2个示例，其中：

  • pinmux_pullup_pulldown_io_level()使用PINMUX API将一个GPIO的内部上拉电阻和下拉电阻分别使能，并通过GPIO Input功能检测线上的电平变化来确认上拉、下拉电阻是否使能成功；其涉及如下2个PINMUX API：

    • pinmux_pin_pullup()

    • pinmux_pin_pulldown()

  • switch_uart_console_pinmux()使用PINMUX API将当前串口输出引脚从P06切换至P24；其涉及如下2个PINMUX API：

    • pinmux_pin_get()

    • pinmux_pin_set()

4.1 示例1：使能SoC内部上拉与下拉电阻

  1. 确认GPIO P57引脚为悬空状态

  2. 当程序执行pinmux_pullup_pulldown_io_level()函数时，会每隔500ms切换一次GPIO P57引脚的内部上下拉电阻，每次切换后均立刻使用GPIO检测IO线上的电平，然后向串口打印当前检测结果：

    Start to pull up and pull down GPIO P57..
Pull up,   detected IO level: 1
Pull down, detected IO level: 0
Pull up,   detected IO level: 1
Pull down, detected IO level: 0
Pull up,   detected IO level: 1
Pull down, detected IO level: 0
Pull up,   detected IO level: 1
Pull down, detected IO level: 0
Pull up,   detected IO level: 1
Pull down, detected IO level: 0
Stopped.

4.2 示例2：切换SoC多功能引脚MFP功能

4.2.1 对于 pan108xxa1_evb / pan108xxb1_evb / pan108xxb5_evb 等 EVB 板

  1. 当程序执行switch_uart_console_pinmux()函数时，其首先会先获取P00和P30引脚的当前的MFP (Multi-Function Pin) 配置：

    Before switch pinmux:
 - Pin function of P00 is: 0x00000001
 - Pin function of P30 is: 0x00000000

    此处打印的是引脚MFP配置的数字数字标识，其代表的含义可以从以下头文件中找到对应的含义：

    • include\drivers\pinmux\pinmux_pan1080.h

    例如，当前P00MFP配置的数字标识为0x00000001，我们查阅pinmux_pan1080.h中的P00引脚相关的MFP定义，在17行可看到其代表的含义是UART0_TX功能：

    #define PAN1080_PIN_FUNC_P00_UART0_TX            0x00000001UL

    同理可查得当前P30的MFP配置（数字标识0x00000000）对应的MFP功能为GPIO：

    #define PAN1080_PIN_FUNC_P30_GPIO                0x00000000UL

  2. 随后打印切换pinmux引脚的提示：

    switching pinmux..

  3. 此时在20s内将EVB板上接在P00引脚上的杜邦线拔掉，将其再接到P30引脚上，即可看到串口继续打印如下消息：

    After switch pinmux (loop_cnt = 6):
- Pin function of P00 is: 0x00000000
- Pin function of P30 is: 0x00000001
After switch pinmux (loop_cnt = 5):
- Pin function of P00 is: 0x00000000
- Pin function of P30 is: 0x00000001
After switch pinmux (loop_cnt = 4):
- Pin function of P00 is: 0x00000000
- Pin function of P30 is: 0x00000001
After switch pinmux (loop_cnt = 3):
- Pin function of P00 is: 0x00000000
- Pin function of P30 is: 0x00000001
After switch pinmux (loop_cnt = 2):
- Pin function of P00 is: 0x00000000
- Pin function of P30 is: 0x00000001
After switch pinmux (loop_cnt = 1):
- Pin function of P00 is: 0x00000000
- Pin function of P30 is: 0x00000001
Stopped.

    此处可根据前面介绍的方法查询得知： 当前P00的MFP配置（数字标识0x00000000）对应的MFP功能为GPIO：

    #define PAN1080_PIN_FUNC_P00_GPIO                0x00000000UL

    当前P30的MFP配置（数字标识0x00000001）对应的MFP功能为UART0_TX：

    #define PAN1080_PIN_FUNC_P30_UART0_TX            0x00000001UL

  4. 以上现象说明已经成功完成两个IO的MFP功能切换：

    • 将P00引脚由UART0 Tx功能切换为GPIO功能

    • 将P30引脚由GPIO功能切换为UART0 Tx功能

4.2.2 对于 pan108xxa3_evb EVB 板

  1. 当程序执行switch_uart_console_pinmux()函数时，其首先会先获取P30和P44引脚的当前的MFP (Multi-Function Pin) 配置：

    Before switch pinmux:
- Pin function of P30 is: 0x00000001
- Pin function of P44 is: 0x00000000

    此处打印的是引脚MFP配置的数字数字标识，其代表的含义可以从以下头文件中找到对应的含义：

    • include\drivers\pinmux\pinmux_pan1080.h

    例如，当前P30MFP配置的数字标识为0x00000001，我们查阅pinmux_pan1080.h中的P30引脚相关的MFP定义，在259行可看到其代表的含义是UART0_TX功能：

    #define PAN1080_PIN_FUNC_P30_UART0_TX            0x00000001UL

    同理可查得当前P44的MFP配置（数字标识0x00000000）对应的MFP功能为GPIO：

    #define PAN1080_PIN_FUNC_P44_GPIO                0x00000000UL

  2. 随后打印切换pinmux引脚的提示：

    switching pinmux..

  3. 此时在20s内将EVB板上接在P30引脚上的杜邦线拔掉，将其再接到P44引脚上，即可看到串口继续打印如下消息：

    After switch pinmux (loop_cnt = 5):
- Pin function of P30 is: 0x00000000
- Pin function of P44 is: 0x00000010
After switch pinmux (loop_cnt = 4):
- Pin function of P30 is: 0x00000000
- Pin function of P44 is: 0x00000010
After switch pinmux (loop_cnt = 3):
- Pin function of P30 is: 0x00000000
- Pin function of P44 is: 0x00000010
After switch pinmux (loop_cnt = 2):
- Pin function of P30 is: 0x00000000
- Pin function of P44 is: 0x00000010
After switch pinmux (loop_cnt = 1):
- Pin function of P30 is: 0x00000000
- Pin function of P44 is: 0x00000010
Stopped.

    此处可根据前面介绍的方法查询得知： 当前P30的MFP配置（数字标识0x00000000）对应的MFP功能为GPIO：

    #define PAN1080_PIN_FUNC_P30_GPIO                0x00000000UL

    当前P44的MFP配置（数字标识0x00000010）对应的MFP功能为UART0_TX：

    #define PAN1080_PIN_FUNC_P44_UART0_TX            0x00000010UL

  4. 以上现象说明已经成功完成两个IO的MFP功能切换：

    • 将P30引脚由UART0 Tx功能切换为GPIO功能

    • 将P44引脚由GPIO功能切换为UART0 Tx功能

5 开发者说明

5.1 使能PINMUX Driver

确保当前工程开启了如下config以使能Zephyr PINMUX Driver：

CONFIG_PINMUX=y

注：实际上，我们在EVB Board Configuration中已经默认开启了PINMUX功能，因此在App工程中将其使能已经是非必要操作。

5.2 API相关头文件位置

  1. zephyr\include\drivers\pinmux.h：PINMUX API接口函数声明

  2. zephyr\include\drivers\pinmux\pinmux_panchip.h：Panchip SoC通用PINMUX宏定义，包括引脚编号、上拉使能/除能、下拉使能/除能、数字输入使能/除能等

  3. zephyr\include\drivers\pinmux\pinmux_pan1080.h：PAN1080 SoC所有引脚的MFP配置定义

5.3 其他配置SoC PINMUX参数的方法

除使用本例程介绍的PINMUX Driver以外，PAN1080还支持如下的方式修改SoC PINMUX的相关配置：

  • 使用GPIO Driver API进行配置（可在运行时动态修改）

  • 使用Devicetree进行配置（仅在系统初始化时配置一次）

5.3.1 使用GPIO Driver API配置PINMUX参数

GPIO Driver的gpio_pin_configure()接口支持配置SoC PINMUX的上拉电阻通路、下拉电阻通路以及数字输入通路。

具体可参考 GPIO Sample 中的介绍与演示。

5.3.2 使用Devicetree配置PINMUX参数

通过修改Zephyr Devicetree (.dts文件)，可配置上拉电阻通路、下拉电阻通路、数字输入通路以及MFP引脚配置等PINMUX支持的参数。

此方式用于在系统初始化的时候配置某个外设的MFP引脚功能，如果需要，还可同时配置上拉、下拉或数字输入使能等功能。

例如，对于PAN108XXB5 EVB来说，系统初始化的时候会默认将P00配置为UART0_TX功能，将P01配置为UART0_RX功能，就是通过配置Devicetree实现的。此处以pan108xxb5_evb board 为例说明如何配置：

  1. 在zephyr\boards\arm\pan108xxb5_evb\pan108xxb5_evb.dts文件中，配置UART0模块的必要参数，并将PINMUX（即pinctrl-0属性）配置为p0_0_uart0_tx、 p0_1_uart0_rx：

    ...
&uart0 {
   current-speed = <921600>;
   pinctrl-0 = <&p0_0_uart0_tx &p0_1_uart0_rx>;
   status = "okay";
};
...

    注：关于pan108xxb5 SoC 支持的所有pinctrl-0属性引脚定义，可以从以下dts头文件中查阅：

    • zephyr\dts\arm\panchip\pan1080\pan1080xx5_pinctrl.dtsi

  2. 配置MFP引脚功能后，还需考虑是否要同时配置对应引脚的上拉、下拉或数字输入使能等功能。对于UART来说，Rx (P01) 是输入引脚，因此需要开启数字输入功能，但无需开启上拉、下拉使能，方法是在soc/pin-controller@40030000节点中，使用DT_PAN_PINS() API接口重新配置此引脚的PINMUX，传入标识（Flag）参数input-enable，以开启P01引脚的数字输入功能：

    soc {
   pin-controller@40030000 {
      /* port, pin, pinmux_name, pinmux_sel [, flag1, ... ] */
      ...
      DT_PAN_PINS(p0, 1, uart0_rx, PAN1080_PIN_FUNC_P01_UART0_RX, input-enable);
      ...
   };
};

    注1：之所以说是重新配置soc/pin-controller@40030000节点的引脚定义，原因是所有引脚均有其原始的定义（通常是不带Flag参数的）；对于pan108xxb5 SoC来说，相关定义位于前面已经提到的dts头文件中：

    • zephyr\dts\arm\panchip\pan1080\pan1080xx5_pinctrl.dtsi

    注2：pinmux dts中支持的所有标识（Flag）参数，均可从以下dts-bindings文件中查阅：

    • zephyr\dts\bindings\pinctrl\panchip,pan-pinctrl.yaml

      description: |
  Panchip SoC Pinctrl node

  The Panchip SoC pins implements following pin configuration option:

    * bias-pull-up
    * bias-pull-down
    * input-enable

  These options define devicetree flags that are converted to SoC flags at
  PAN_PIN_FLAGS().

      其中：

      • bias-pull-up表示使能上拉电阻通路；

      • bias-pull-down表示使能下拉电阻通路；

      • input-enable表示使能数字输入通路；

    注3：pinmux dts中支持的标识（Flag）参数，可以同时配置，且没有顺序限制；例如，使用如下的方式可以同时使能P01引脚的数字输入与上拉电阻功能：

    DT_PAN_PINS(p0, 1, uart0_rx, PAN1080_PIN_FUNC_P01_UART0_RX, input-enable, bias-pull-up);

    注4：DT_PAN_PINS() API接口必须与外设模块中的pinctrl-0属性一起使用才会真正生效；如果只使用此接口配置了某个引脚的上拉/下拉/数字输入使能，但没有任何外设的pinctrl-0属性中配置了此引脚功能，则当前的DT_PAN_PINS()配置不会生效。

5.4 PAN1080引脚使用注意事项

  1. 切换引脚的复用功能时，需要特别注意此引脚是否为数字输入引脚，如果是，则一定要显式开启此引脚的数字输入功能，具体可以采样上述介绍的任意一种可行的方式；

    例如：我们需要将某个IO配置为UART Rx功能，由于Rx引脚用于接收外部的数字信号，因此将IO的MFP功能切换为UART_RX后，还应将此IO的数字输入功能打开，否则UART将无法正确接收对端发来的数据。

  2. IO引脚的数字输入功能一般需遵守非必要不打开的原则，这样可以减少可能的电流漏入，有助于降低芯片整体功耗；

  3. PINMUX Driver操作的上拉电阻、下拉电阻、数字输入等功能，需要确保已经开启了GPIO模块时钟方可正常配置（SDK中已默认开启）；

6 RAM/Flash资源使用情况

Memory region         Used Size  Region Size  %age Used
FLASH:       19228 B       256 KB      7.33%
SRAM:        4168 B        64 KB      6.36%