跳至主要內容

Port模块用户手册

大约 8 分钟约 2263 字2025/12/26

Port模块用户手册

目录

1. 简介

本模块提供了对 Port (端口) 的抽象接口，用于对MCU的IO引脚进行初始化和运行时配置。它允许用户精确控制每个引脚的功能、电气特性和复用功能。

主要功能包括：

  • 初始化: 通过 HLI_Port_Init 函数，可以根据链接时配置表对所有需要的引脚进行批量初始化。
  • 运行时配置:
    • HLI_Port_SetMode: 在运行时安全地修改已初始化引脚的模式和状态。
    • HLI_Port_SetupPin: 在运行时直接设置引脚状态，无论其是否已初始化（慎用）。
  • 引脚参数配置: 支持配置引脚模式（输入、输出、模拟、复用功能）、输出电平、上下拉、输出类型（推挽/开漏）和速度。

1.1 支持的设备

当前软件适用于以下芯片:

  • KF32A158xxxSF

1.2 名词及缩写

缩写解释
MCU微控制器
PortMCU端口
ISR中断服务例程
GPIO通用输入输出

2. 文件结构

文件名称描述
kf32axxx_hli_port.c此文件包含Port驱动程序的通用功能
kf32axxx_hli_port.h此头文件输出Port驱动程序的宏、类型定义和函数原型
kf32axxx_hli_port_cfg.h此文件包含Port模块相关配置及宏定义
kf32axxx_hli_port_Lcfg.c此文件包含Port配置变量
kf32axxx_hli_port_Lcfg.h此文件包含Port配置变量声明
__irq_port.c此文件包含Port模块的中断服务函数

3. 数据结构

3.1 数据类型

3.1.1 宏定义

  1. 引脚配置宏 (PORT_CFG_MACRO)
    用于以紧凑的方式定义一个引脚的所有配置参数。
    PORT_CFG_MACRO(Remap, Mode, Level, PullUp, OpenDrain, Speed)

  2. 引脚重映射定义

    宏定义名称解释
    GPIO_REMAP_AF0PAGE1重映射AF0
    GPIO_REMAP_AF1PAGE1重映射AF1
    ......
    GPIO_REMAP_AF15PAGE1重映射AF15
    GPIO_PAGE2_REMAP_AF0PAGE2重映射AF0
    GPIO_PAGE2_REMAP_AF1PAGE2重映射AF1
    ......
    GPIO_PAGE2_REMAP_AF15PAGE2重映射AF15
    GPIO_PAGE3_REMAP_AF0PAGE3重映射AF0
    GPIO_PAGE3_REMAP_AF1PAGE3重映射AF1
    ......
    GPIO_PAGE3_REMAP_AF15PAGE3重映射AF15

  3. 引脚索引序号

    宏定义名称解释
    GPIO_PIN_0GPIO引脚0
    GPIO_PIN_1GPIO引脚1
    ......
    GPIO_PIN_15GPIO引脚15

  4. 端口索引序号

    宏定义名称解释
    GPIO_PORT_AGPIO端口A
    GPIO_PORT_BGPIO端口B
    ......
    GPIO_PORT_HGPIO端口H

  5. 引脚模式

    宏定义名称解释
    MODE_GPIO_IN输入模式
    MODE_GPIO_OUT输出模式
    MODE_REMAP重映射模式
    MODE_AN模拟模式

  6. 输出电平

    宏定义名称解释
    LEVEL_LOW输出低
    LEVEL_HIGH输出高

  7. 上下拉模式

    宏定义名称解释
    PULL_NONE无上下拉
    PULL_UP上拉
    PULL_DOWN下拉

  8. 输出模式

    宏定义名称解释
    POD_PP推挽输出
    POD_OD开漏输出

  9. 引脚速度

    宏定义名称解释
    SPEED_10MHZ低速模式10MHz
    SPEED_20MHZ高速模式20MHz

3.1.2 枚举

无。

3.1.3 类型定义

  1. 引脚号类型 (HLI_Port_PinType)
    typedef uint8_t HLI_Port_PinType;
    用于表示引脚的符号名称，如 DIO_CHANNEL_A_0。

  2. 引脚模式类型 (HLI_Port_PinModeType)
    typedef uint16_t HLI_Port_PinModeType;
    用于表示引脚的多种可配置模式。

3.2 配置项说明

  1. 静态配置
    静态配置在 kf32axxx_hli_port_cfg.h 文件中通过宏定义完成，主要用于屏蔽特定引脚，防止其被意外初始化。

    成员解释取值范围
    MASK_PORTAPORTA引脚屏蔽配置。二进制位为1对应的引脚将被屏蔽。0x0000 ~ 0xFFFF
    MASK_PORTBPORTB引脚屏蔽配置。0x0000 ~ 0xFFFF
    MASK_PORTCPORTC引脚屏蔽配置。0x0000 ~ 0xFFFF
    MASK_PORTDPORTD引脚屏蔽配置。0x0000 ~ 0xFFFF
    MASK_PORTEPORTE引脚屏蔽配置。0x0000 ~ 0xFFFF
    MASK_PORTFPORTF引脚屏蔽配置。0x0000 ~ 0xFFFF
    MASK_PORTGPORTG引脚屏蔽配置。0x0000 ~ 0xFFFF
    MASK_PORTHPORTH引脚屏蔽配置。0x0000 ~ 0xFFFF

    警告

    晶振引脚、DEBUG引脚默认被屏蔽，如遇相关引脚无正常初始化，请先修改以上宏定义的值。

  2. 引脚配置 (HLI_Port_PinConfigType)

    成员解释取值范围
    PortBase引脚所在的Port组。GPIO_PORT_A ~ GPIO_PORT_H
    PinIndex引脚在Port组内的编号。GPIO_PIN_0 ~ GPIO_PIN_15
    PinsControl使用 PORT_CFG_MACRO 宏打包的引脚所有配置参数。例如: PORT_CFG_MACRO(GPIO_REMAP_AF0, MODE_GPIO_OUT, LEVEL_HIGH, PULL_NONE, POD_PP, SPEED_10MHZ)

  3. 顶层配置 (HLI_Port_ConfigType)

    成员解释取值范围
    NumConfig要配置的引脚总数。通常使用 sizeof(Port_PinConfig) / sizeof(HLI_Port_PinConfigType) 自动计算。
    PortPinConfigPtr指向引脚配置数组的指针。指向一个 HLI_Port_PinConfigType 类型的数组。

4. 驱动函数

4.1 函数接口

4.1.1 HLI_Port_Init

NameDescription
函数名称HLI_Port_Init
语法void HLI_Port_Init(const HLI_Port_ConfigType *ConfigPtr)
同步/异步同步
重入性不可重入
形参(输入)ConfigPtr: 指向包含所有引脚配置的顶层结构体指针。
返回值无
描述根据配置结构体初始化所有指定的端口引脚。
注意事项1. 此函数应在系统启动初期调用，以确保所有引脚处于正确的初始状态。
2. 被 MASK_PORTx 宏屏蔽的引脚将不会被此函数初始化。

4.1.2 HLI_Port_SetMode

NameDescription
函数名称HLI_Port_SetMode
语法void HLI_Port_SetMode(HLI_Port_PinType Pin, uint32_t PinConfigValue)
同步/异步同步
重入性可重入
形参(输入)Pin: 要配置的引脚的符号名称，例如 DIO_CHANNEL_A_0。
形参(输入)PinConfigValue: 使用 PORT_CFG_MACRO 宏生成的引脚配置值。
返回值无
描述在运行时更改单个引脚的模式和配置。
注意事项1. 此函数会检查引脚是否在 HLI_Port_Init 中被初始化过，只有已初始化的引脚才能被成功设置。
2. 这是一个安全的操作接口，推荐在运行时修改引脚配置时使用。

4.1.3 HLI_Port_SetupPin

NameDescription
函数名称HLI_Port_SetupPin
语法void HLI_Port_SetupPin(HLI_Port_PinType Pin, uint32_t PinConfigValue)
同步/异步同步
重入性可重入
形参(输入)Pin: 要配置的引脚的符号名称，例如 DIO_CHANNEL_A_0。
形参(输入)PinConfigValue: 使用 PORT_CFG_MACRO 宏生成的引脚配置值。
返回值无
描述在运行时直接设置单个引脚的模式和配置，无论其是否已被初始化。
注意事项警告: 此函数会绕过初始化检查，直接操作硬件寄存器。在不清楚引脚当前状态时使用此函数可能导致意外的硬件行为或总线冲突，请谨慎使用。

4.2 中断回调

本模块不直接产生中断，但与 Dio 模块协同实现外部中断功能。当外部中断发生时，硬件会触发相应 Port 的中断服务例程（例如 _PA_exception），该例程通常定义在 __irq_port.c 中，并最终调用 Dio 模块中用户定义的回调函数。

5. 使用示例

注

示例中使用的参数仅用作示例演示，应用时以实际为准。

1. 基本初始化与运行时修改

此示例展示了 Port 模块最核心的用法：在系统启动时通过 HLI_Port_Init 批量初始化引脚，然后在程序运行时通过 HLI_Port_SetMode 动态修改单个引脚的配置。

6. 限制与假设

  1. 引脚屏蔽: 在 kf32axxx_hli_port_cfg.h 中通过 MASK_PORTx 宏定义的引脚（如晶振、调试引脚）在调用 HLI_Port_Init 时会被忽略，以防止意外覆盖其特殊功能。如果需要操作这些引脚，必须手动修改屏蔽宏。
  2. 依赖关系: Port 模块是许多其他外设模块（如 Dio, Adc, Spi 等）的底层基础。在使用任何需要占用物理引脚的外设之前，必须先使用 Port 模块对相应引脚进行正确的复用功能配置。
  3. 中断: Port 模块本身不处理中断逻辑，但它为 Dio 模块的外部中断功能提供了必要的硬件基础（引脚中断使能和状态标志）。中断的响应和处理由 Dio 和 Irq 模块负责。

7. 变更记录

版本时间变更记录
v1.02025-11-24新增初版文档
最近更新
贡献者: 翟宇