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

Driver: Pinmux

1 功能概述

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

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

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

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

GPIO Block Diagram

其中与PINMUX相关的有：

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

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

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

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

2 环境准备

  • PAN1080 EVB一块

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

  • 硬件接线：

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

    • 使用杜邦线将EVB上的:

      • UART1 TX与P06相连

      • UART1 RX与P07相连

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

3 编译和烧录

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

目前可使用ZAL工具或quick build脚本进行编译和下载。

脚本位置：quick_build_samples\drivers\pinmux.bat

打开脚本后默认会编译项目，编译完成时，可输入字符进行后续下载等操作:

Input the keyword to continue:
  'b' build                         编译项目
  'r' make clean and rebuild        重新编译项目
  'f' flash download                下载
  'e' erase chip                    擦除芯片
  'o' open project by VS Code       打开 `VS Code`，可查看源码，执行编译下载等
  others exit                       退出
wait input:

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功能

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

    Before switch pinmux:
 - Pin function of P06 is: 0x00004000
 - Pin function of P24 is: 0x00000000

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

    • include\drivers\pinmux\pinmux_pan1080.h

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

    #define PAN1080_PIN_FUNC_P06_UART1_TX            0x00004000UL

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

    #define PAN1080_PIN_FUNC_P24_GPIO                0x00000000UL

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

    switching pinmux..

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

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

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

    #define PAN1080_PIN_FUNC_P06_GPIO                0x00000000UL

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

    #define PAN1080_PIN_FUNC_P24_UART1_TX            0x00000010UL

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

    • 将P06引脚由UART1 Tx功能切换为GPIO功能

    • 将P24引脚由GPIO功能切换为UART1 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引脚功能，如果需要，还可同时配置上拉、下拉或数字输入使能等功能。

例如，对于PAN1080 EVB来说，系统初始化的时候会默认将P06配置为UART1_TX功能，将P07配置为UART1_RX功能，就是通过配置Devicetree实现的。此处以pan1080a_afld_evb board为例说明如何配置：

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

    ...
&uart1 {
	current-speed = <921600>;
	pinctrl-0 = <&p0_6_uart1_tx &p0_7_uart1_rx>;
	status = "okay";
};
...

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

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

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

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

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

    • zephyr\dts\arm\panchip\pan1080\pan1080a_afld_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）参数，可以同时配置，且没有顺序限制；例如，使用如下的方式可以同时使能P07引脚的数字输入与上拉电阻功能：

    DT_PAN_PINS(p0, 7, uart1_rx, PAN1080_PIN_FUNC_P07_UART1_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中已默认开启）；