当前文档版本为 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);
    

    注4DT_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%