【STM32F407开发板用户手册】第16章 STM32F407必备的HAL库API（重要）

其中startup_stm32f429xx.s和system_stm32f4xx.c已经在第13章为大家讲解过，这里不再赘述。。本章教程重点为大家讲解文件stm32f4xx_hal.c、stm32f4xx_hal_cortex.c和sm32f4x_hal_rcc.c（core_cm4.h文件在后面章节为大家讲解）。

16.3 源文件stm32f4xx_hal.c（重要）

这个文件比较杂，像基准电压大小配置，EXTI配置，IO补偿配置等都在这个文件里面设置。学习这个文件注意事项：

HAL库中各个外设驱动里面的延迟实现是基于此文件提供的时间基准，而这个时间基准既可以使用滴答定时器实现也可以使用通用的定时器实现，默认情况下是用的滴答定时器。
函数HAL_Init里面会调用时间基准初始化函数HAL_InitTick，而调用函数HAL_RCC_ClockConfig也会调用时间基准初始化函数HAL_InitTick。
如果在中断服务程序里面调用延迟函数HAL_Delay要特别注意，因为这个函数的时间基准是基于滴答定时器或者其他通用定时器实现，实现方式是滴答定时器或者其他通用定时器里面做了个变量计数。如此一来，结果是显而易见的，如果其他中断服务程序调用了此函数，且中断优先级高于滴答定时器，会导致滴答定时器中断服务程序一直得不到执行，从而卡死在里面。所以滴答定时器的中断优先级一定要比它们高。

16.3.1 函数HAL_Init

函数原型：

HAL_StatusTypeDef HAL_Init(void)
{

  /* 配置Flash的指令预取，指令Cache和数据Cache */ 
#if (INSTRUCTION_CACHE_ENABLE != 0U)
  __HAL_FLASH_INSTRUCTION_CACHE_ENABLE();
#endif 

#if (DATA_CACHE_ENABLE != 0U)
  __HAL_FLASH_DATA_CACHE_ENABLE();
#endif 

#if (PREFETCH_ENABLE != 0U)
  __HAL_FLASH_PREFETCH_BUFFER_ENABLE();
#endif 

  /* 设置中断优先级分组 */
  HAL_NVIC_SetPriorityGrouping(NVIC_PRIORITYGROUP_4);

/* 使用滴答定时器做为默认时基，配置为1ms滴答，另外系统上电后默认使用的HSI时钟 */
  HAL_InitTick(TICK_INT_PRIORITY);

  /* 初始化底层硬件 */
  HAL_MspInit();

  /* 返回HAL_OK */
  return HAL_OK;
}

函数描述：

此函数用于初始化HAL库，此函数主要实现如下功能：

设置NVIC优先级分组是4。
设置滴答定时器的每1ms中断一次。
HAL库不像之前的标准库，在系统启动函数SystemInit里面做了RCC初始化，HAL库是没有做的，所以进入到main函数后，系统还在用内部高速时钟HSI，对于F4来说，HSI主频是16MHz。
函数HAL_Init里面调用的HAL_MspInit一般在文件stm32f4xx_hal_msp.c里面做具体实现，主要用于底层初始化。当前此函数也在文件stm32f4xx_hal.c里面，只是做了弱定义。

函数参数：

返回值，返回HAL_ERROR表示参数错误，HAL_OK表示发送成功，HAL_BUSY表示忙，正在使用中。

注意事项：

必须在main函数里面优先调用此函数。
用户务必保证每1ms一次滴答中断。
关于优先级分组的设置可以看第xx章节（注：后面做到这个章节时补上）。

使用举例：

此函数的使用比较简单，上电后优先调用即可。

16.3.2 函数HAL_DeInit

函数原型：

HAL_StatusTypeDef HAL_DeInit(void)
{
  /* 复位所有外设 */
  __HAL_RCC_APB1_FORCE_RESET();
  __HAL_RCC_APB1_RELEASE_RESET();

  __HAL_RCC_APB2_FORCE_RESET();
  __HAL_RCC_APB2_RELEASE_RESET();

  __HAL_RCC_AHB1_FORCE_RESET();
  __HAL_RCC_AHB1_RELEASE_RESET();

  __HAL_RCC_AHB2_FORCE_RESET();
  __HAL_RCC_AHB2_RELEASE_RESET();

  __HAL_RCC_AHB3_FORCE_RESET();
  __HAL_RCC_AHB3_RELEASE_RESET();

  /* 复位底层硬件初始化 */
  HAL_MspDeInit();

  /* 返回值 */
  return HAL_OK;
}

函数描述：

此函数用于复位HAL库和滴答时钟。

复位了APB1,2的时钟以及AHB1,2,3的时钟。
函数HAL_DeInit里面调用的HAL_MspDeInit一般在文件stm32f4xx_hal_msp.c里面做具体实现，主要用于底层初始化，跟函数HAL_Init里面调用的HAL_MspInit是一对。当前此函数也在文件stm32f4xx_hal.c里面，只是做了弱定义。

使用举例：

此函数的使用比较简单，需要调用的时候直接调用即可。

16.3.3 函数HAL_InitTick

函数原型：

__weak HAL_StatusTypeDef HAL_InitTick(uint32_t TickPriority)
{
  /* Configure the SysTick to have interrupt in 1ms time basis*/
  if (HAL_SYSTICK_Config(SystemCoreClock / (1000U / uwTickFreq)) > 0U)
  {
    return HAL_ERROR;
  }

  /* Configure the SysTick IRQ priority */
  if (TickPriority < (1UL << __NVIC_PRIO_BITS))
  {
    HAL_NVIC_SetPriority(SysTick_IRQn, TickPriority, 0U);
    uwTickPrio = TickPriority;
  }
  else
  {
    return HAL_ERROR;
  }

  /* Return function status */
  return HAL_OK;
}

函数描述：

此函数用于初始化滴答时钟，此函数相关问题如下：

此函数有个前缀__weak ，表示弱定义，用户可以重定义。
此函数用于初始化滴答时钟1ms中断一次，并且为滴答中断配置一个用户指定的优先级。
此函数由HAL_Init调用，或者任何其它地方调用函数HAL_RCC_ClockConfig配置RCC的时候也会调用HAL_InitTick。
调用基于此函数实现的HAL_Delay要特别注意，因为这个函数的时间基准是基于滴答定时器或者其他通用定时器实现，实现方式是滴答定时器或者其他通用定时器里面做了个变量计数。如此一来，结果是显而易见的，如果其他中断服务程序调用了此函数，且中断优先级高于滴答定时器，会导致滴答定时器中断服务程序一直得不到执行，从而卡死在里面。所以滴答定时器的中断优先级一定要比它们高。

函数参数：

形参TickPriority用于设置滴答定时器优先级。
返回值，返回HAL_ERROR表示参数错误，HAL_OK表示发送成功，HAL_BUSY表示忙，正在使用中。

使用举例：

此函数由HAL_Init调用，无需用户操作，除非需要重定义。

16.3.4 Systick的相关函数

调用了函数HAL_Init后，Systick相关的函数就可以使用了。这些函数如下：

函数原型：

__weak void HAL_IncTick(void)
__weak uint32_t HAL_GetTick(void)
uint32_t HAL_GetTickPrio(void)
HAL_StatusTypeDef HAL_SetTickFreq(HAL_TickFreqTypeDef Freq)
HAL_TickFreqTypeDef HAL_GetTickFreq(void)
__weak void HAL_Delay(uint32_t Delay)
__weak void HAL_SuspendTick(void)
__weak void HAL_ResumeTick(void)

函数描述：

这些函数就比较简单了，下面把这些函数实现的功能做个简单的说明：

函数HAL_IncTick在滴答定时器中断里面被调用，实现一个简单的计数功能，因为一般滴答定时器中断都是配置的1ms，所以计数全局变量uwTick每毫秒加1。
函数HAL_GetTick用于获取全局变量uwTick当前的计数。
函数HAL_GetTickPrio用于获取滴答时钟优先级。
函数HAL_SetTickFreq和HAL_GetTickFreq是一对，前者用于设置滴答中断频率，后再用于获取滴答中断频率。
函数HAL_Delay用于阻塞式延迟，默认单位是ms。
函数HAL_SuspendTick和HAL_ResumeTick是一对，前者用于挂起滴答定时器，后者用于恢复。

注意事项：

函数有个前缀__weak ，表示弱定义，用户可以重定义。

使用举例：

这些函数都比较简单，这里就不举例了。需要的时候，直接调用即可。

16.3.5 低功耗状态下继续使用调试功能

如果希望在睡眠，停机和待机的低功耗模式下继续使用调试功能，调用下面的函数即可：

/* 睡眠模式下继续使用调试功能 */
void HAL_DBGMCU_EnableDBGSleepMode(void)
{
  SET_BIT(DBGMCU->CR, DBGMCU_CR_DBG_SLEEP);
}

/* 停机模式下继续使用调试功能 */
void HAL_DBGMCU_EnableDBGStopMode(void)
{
  SET_BIT(DBGMCU->CR, DBGMCU_CR_DBG_STOP);
}

/* 待机模式下继续使用调试功能 */
void HAL_DBGMCU_EnableDBGStandbyMode(void)
{
  SET_BIT(DBGMCU->CR, DBGMCU_CR_DBG_STANDBY);
}

16.4 源文件stm32f4xx_hal_rcc.c

这个文件主要是实现内部和外部时钟（HSE、HSI、LSE、LSI、PLL、CSS、MCO）以及总线时钟（SYSCLK、AHB1、AHB2、AHB3、APB1）的配置。

学习这个文件注意事项：

1、系统上电复位后，通过内部高速时钟HSI运行（主频16MHz），Flash工作在0等待周期，所有外设除了SRAM、Flash、JTAG 和 PWR，时钟都是关闭的。

AHB和APB总线无分频，所有挂载这两类总线上的外设都是以HSI频率运行。
所有的GPIO都是模拟模式，除了JTAG相关的几个引脚。

2、系统上电复位后，用户需要完成以下工作：

选择用于驱动系统时钟的时钟源。
配置系统时钟频率和Flash设置。
配置分频器。
使能外设时钟。
配置外设时钟源，部分外设的时钟可以不来自系统时钟（I2S, RTC, ADC, USB OTG FS/SDIO/RNG）。

RCC局限性：

使能了外设时钟后，不能立即操作对应的寄存器，要加延迟。不同外设延迟不同：

如果是AHB的外设，使能了时钟后，需要等待2个AHB时钟周期才可以操作这个外设的寄存器。
如果是APB的外设，使能了时钟后，需要等待2个APB时钟周期才可以操作这个外设的寄存器。

当前HAL库的解决方案是在使能了外设时钟后，再搞一个读操作，算是当做延迟用。

比如下面使能GPIOA的时钟：

#define __HAL_RCC_GPIOA_CLK_ENABLE()   do { \
                                        __IO uint32_t tmpreg = 0x00U; \
                                        SET_BIT(RCC->AHB1ENR, RCC_AHB1ENR_GPIOAEN);\
                                        /* Delay after an RCC peripheral clock enabling */ \
                                        tmpreg = READ_BIT(RCC->AHB1ENR, RCC_AHB1ENR_GPIOAEN);\
                                        UNUSED(tmpreg); \
                                        } while(0U)

关于时钟方面的知识点补充

1、正确理解PCLK1，2和HCLK对应哪些总线的时钟，下面一张图可以说明问题：

由上图可以得出：

PCLK1、PC对应的是APB总线APB1，APB2时钟。

HCLK对应的AHB总线。

2、内部和外部时钟配置：

HSI (high-speed internal)

高速内部RC振荡器，可以直接或者通过PLL倍频后做系统时钟源。缺点是精度差些，即使经过校准。

LSI (low-speed internal)

低速内部时钟，主要用于独立看门狗和RTC的时钟源。

HSE (high-speed external)

高速外部晶振，可接4 - 26z的晶振，可以直接或者通过PLL倍频后做系统时钟源，也可以做RTC的是时钟源。

LSE (low-speed external)

低速外部晶振，主要用于RTC。

CSS (Clock security system)

时钟安全系统，一旦使能后，如果HSE启动失败（不管是直接作为系统时钟源还是通过PLL输出后做系统时钟源），系统时钟将切换到HSI。如果使能了中断的话，将进入不可屏蔽中断NMI。

MCO1 (micro controller clock output)

可以在PA8引脚输出SYSCLK、PLLI2SCLK、HSE和PLLCLK。

MCO2 (micro controller clock output)

可以在PC9引脚输出LSE、HSE、HSI和PLLCLK。

PLL锁相环，时钟输入来自HSI , HSE 或者CSI

16.4.1 函数HAL_RCC_DeInit

函数原型：

__weak HAL_StatusTypeDef HAL_RCC_DeInit(void)
{
  return HAL_OK;
}

函数描述：

文件stm32f4xx_hal_rcc.c里面的此函数是空的（做了__weak弱定义，方便用户在其它文件里面重定义），ST将具体实现放在了stm32f4xx_hal_rcc_ex.c里面的此函数里面

此函数用于RCC复位函数，主要实现如下功能：

HSI 打开作为系统时钟。
HSE和PLL关闭。
AHB, APB1和APB2总线无分频。
CSS, MCO1 和 MCO2 关闭。
所有中断关闭。

注意事项：

此函数不会修改外设时钟，LSI、LSE和RTC时钟。

使用举例：

此函数的使用比较简单，需要调用的时候直接调用即可。

16.4.2 函数HAL_RCC_OscConfig

函数原型：

函数描述：

通过上面函数原型，我们可以一目了然的看出此函数的作用，配置了HSE、HSI、LSI、LSE和PLL。

函数参数：

函数的形参是RCC_OscInitTypeDef类型结构体变量，这个结构体的定义如下（主要是HSE、HSI、LSI、LSE和PLL的配置变量）：

/**
  * @brief  RCC Internal/External Oscillator (HSE, HSI, LSE and LSI) configuration structure definition
  */
typedef struct
{
  uint32_t OscillatorType;       
  uint32_t HSEState;            
  uint32_t LSEState;            
  uint32_t HSIState;           
  uint32_t HSICalibrationValue;  
  uint32_t LSIState;            
  RCC_PLLInitTypeDef PLL;        
}RCC_OscInitTypeDef;

注意事项：

LSE Bypass 切换到 LSE On 或者 LSE On切换到 LSE Bypass都不支持，用需要先关闭LSE，然后才可以切换到LSE Bypass 或者LSE On。
HSE Bypass 切换到 HSE On 或者 LSE On切换到 LSE Bypass都不支持，用需要先关闭HSE，然后才可以切换到HSE Bypass 或者HSE On。

使用举例：

    RCC_OscInitTypeDef RCC_OscInitStruct;

    /* 使能HSE，并选择HSE作为PLL时钟源 */
    RCC_OscInitStruct.OscillatorType = RCC_OSCILLATORTYPE_HSE;
    RCC_OscInitStruct.HSEState = RCC_HSE_ON;
    RCC_OscInitStruct.PLL.PLLState = RCC_PLL_ON;
    RCC_OscInitStruct.PLL.PLLSource = RCC_PLLSOURCE_HSE;
    RCC_OscInitStruct.PLL.PLLM = 8;
    RCC_OscInitStruct.PLL.PLLN = 336;
    RCC_OscInitStruct.PLL.PLLP = RCC_PLLP_DIV2;
    RCC_OscInitStruct.PLL.PLLQ = 4;
    if (HAL_RCC_OscConfig(&RCC_OscInitStruct) != HAL_OK)
    {
        Error_Handler(__FILE__, __LINE__);
    }

16.4.3 函数HAL_RCC_ClockConfig

函数原型：

函数描述：

通过上面函数原型，我们可以一目了然的看出此函数的作用，配置了HCLK、SYSCLK、PLCK1和PLCK2。

函数参数：

第1个参数是RCC_ClkInitTypeDef类型的结构体变量。
第2个参数是Flash的延迟设置。
返回值，返回HAL_ERROR表示参数错误，HAL_OK表示发送成功，HAL_BUSY表示忙，正在使用中。

注意事项：

此函数会更新全局变量SystemCoreClock的主频值，并且会再次调用函数HAL_InitTick更新系统滴答时钟，这点要特别注意。
系统上电复位或者从停机、待机模式唤醒后，使用的是HSI作为系统时钟。以防使用HSE直接或者通过PLL输出后做系统时钟时失败（如果使能了CSS）。
目标时钟就绪后才可以从当前的时钟源往这个目标时钟源切换，如果目标时钟源没有就绪，就会等待直到时钟源就绪才可以切换。
根据设备的供电范围，必须正确设置D1CPRE[3:0]位的范围，防止超过允许的最大频率。

使用举例：

    RCC_ClkInitTypeDef RCC_ClkInitStruct;
    HAL_StatusTypeDef ret = HAL_OK;

/* 
       选择PLL的输出作为系统时钟
        HCLK = SYSCLK / 1  (AHB1Periph)
        PCLK2 = HCLK / 2   (APB2Periph)
        PCLK1 = HCLK / 4   (APB1Periph)
    */
    RCC_ClkInitStruct.ClockType = RCC_CLOCKTYPE_HCLK|RCC_CLOCKTYPE_SYSCLK
                                  |RCC_CLOCKTYPE_PCLK1|RCC_CLOCKTYPE_PCLK2;
    RCC_ClkInitStruct.SYSCLKSource = RCC_SYSCLKSOURCE_PLLCLK;
    RCC_ClkInitStruct.AHBCLKDivider = RCC_SYSCLK_DIV1;
    RCC_ClkInitStruct.APB1CLKDivider = RCC_HCLK_DIV4;
    RCC_ClkInitStruct.APB2CLKDivider = RCC_HCLK_DIV2;

    /* 此函数会更新SystemCoreClock，并重新配置HAL_InitTick */
    if (HAL_RCC_ClockConfig(&RCC_ClkInitStruct, FLASH_LATENCY_5) != HAL_OK)
    {
        Error_Handler(__FILE__, __LINE__);
    }

16.4.4 函数HAL_RCC_MCOConfig

函数原型：

void HAL_RCC_MCOConfig(uint32_t RCC_MCOx, uint32_t RCC_MCOSource, uint32_t RCC_MCODiv)
{
  GPIO_InitTypeDef GPIO_InitStruct;
  /* Check the parameters */
  assert_param(IS_RCC_MCO(RCC_MCOx));
  assert_param(IS_RCC_MCODIV(RCC_MCODiv));

  /* RCC_MCO1 */
  if(RCC_MCOx == RCC_MCO1)
  {
     /* 省略未写 */
  }
  else
  {
    /* 省略未写 */
  }
}

函数描述：

此函数的作用是配置MCO1（PA8引脚）和MCO2（PC9引脚）的时钟输出以及选择的时钟源，通过下面的截图可以很好的说明此函数的作用：

函数参数：

1、第1个形参用于选择输出的引脚，可选择RCC_MCO1（PA8引脚）或者RCC_MCO2（PC9引脚）。

2、第2个形参用于选择输出的时钟源，MCO1可选择的时钟源如下：

RCC_MCO1SOURCE_HSI
RCC_MCO1SOURCE_LSE
RCC_MCO1SOURCE_HSE
RCC_MCO1SOURCE_PLLCLK

MCO2可选择的时钟源如下：

RCC_MCO2SOURCE_SYSCLK
RCC_MCO2SOURCE_PLLI2SCLK
RCC_MCO2SOURCE_I2SCLK
RCC_MCO2SOURCE_HSE
RCC_MCO2SOURCE_PLLCLK

3、第3个参数用于设置输出分频，范围从RCC_MCODIV_1到RCC_MCODIV_4。

使用举例：

此函数的使用比较简单，需要在MCO引脚输出时钟的时候，直接调用即可。

16.4.5 RCC相关函数

函数原型：

void     HAL_RCC_EnableCSS(void);
void     HAL_RCC_DisableCSS(void);
uint32_t HAL_RCC_GetSysClockFreq(void);
uint32_t HAL_RCC_GetHCLKFreq(void);
uint32_t HAL_RCC_GetPCLK1Freq(void);
uint32_t HAL_RCC_GetPCLK2Freq(void);
void     HAL_RCC_GetOscConfig(RCC_OscInitTypeDef *RCC_OscInitStruct);
void     HAL_RCC_GetClockConfig(RCC_ClkInitTypeDef *RCC_ClkInitStruct, uint32_t *pFLatency);

剩下的这些函数都比较简单了，我们这里就不做讲解了。

16.5 源文件stm3f4xx_hal_cortex.c

这个库文件主要功能是NVIC，MPU和Systick的配置。此文件有个臃肿的地方，里面的API其实就是将ARM的CMSIS库各种API重新封装了一遍。这么做的好处是保证了HAL的API都是以字母HAL开头。

更多NVIC相关知识需要大家看第xx章节（注：后面做到这个章节时补上）。

更多SysTick相关知识需要大家看第xx章节。

更多MPU相关知识需要大家看第xx章节。

16.5.1 NVIC相关函数

函数原型：

void HAL_NVIC_SetPriorityGrouping(uint32_t PriorityGroup)
void HAL_NVIC_SetPriority(IRQn_Type IRQn, uint32_t PreemptPriority, uint32_t SubPriority)
void HAL_NVIC_EnableIRQ(IRQn_Type IRQn)
void HAL_NVIC_DisableIRQ(IRQn_Type IRQn)
void HAL_NVIC_SystemReset(void)
uint32_t HAL_NVIC_GetPriorityGrouping(void)
void HAL_NVIC_GetPriority(IRQn_Type IRQn, uint32_t PriorityGroup, uint32_t *pPreemptPriority, uint32_t *pSubPriority)
void HAL_NVIC_SetPendingIRQ(IRQn_Type IRQn)
uint32_t HAL_NVIC_GetPendingIRQ(IRQn_Type IRQn)
void HAL_NVIC_ClearPendingIRQ(IRQn_Type IRQn)
uint32_t HAL_NVIC_GetActive(IRQn_Type IRQn)

这些函数的操作就比较容易了，这里就不做讲解了，用到时调用即可。

16.5.2 SysTick相关函数

函数原型：

uint32_t HAL_SYSTICK_Config(uint32_t TicksNumb)
void HAL_SYSTICK_CLKSourceConfig(uint32_t CLKSource)
void HAL_SYSTICK_IRQHandler(void)
__weak void HAL_SYSTICK_Callback(void)

这些函数的操作就比较容易了，这里就不做讲解了，用到时调用即可。

16.5.3 函数HAL_MPU_ConfigRegion

函数原型：

void HAL_MPU_ConfigRegion(MPU_Region_InitTypeDef *MPU_Init)
{
   /* 部分省略未写 */

  /* Set the Region number */
  MPU->RNR = MPU_Init->Number;

  if ((MPU_Init->Enable) != RESET)
  {
    /* 部分省略未写 */

    MPU->RBAR = MPU_Init->BaseAddress;
    MPU->RASR = ((uint32_t)MPU_Init->DisableExec             << MPU_RASR_XN_Pos)   |
                ((uint32_t)MPU_Init->AccessPermission        << MPU_RASR_AP_Pos)   |
                ((uint32_t)MPU_Init->TypeExtField            << MPU_RASR_TEX_Pos)  |
                ((uint32_t)MPU_Init->IsShareable             << MPU_RASR_S_Pos)    |
                ((uint32_t)MPU_Init->IsCacheable             << MPU_RASR_C_Pos)    |
                ((uint32_t)MPU_Init->IsBufferable            << MPU_RASR_B_Pos)    |
                ((uint32_t)MPU_Init->SubRegionDisable        << MPU_RASR_SRD_Pos)  |
                ((uint32_t)MPU_Init->Size                    << MPU_RASR_SIZE_Pos) |
                ((uint32_t)MPU_Init->Enable                  << MPU_RASR_ENABLE_Pos);
  }
  else
  {
    MPU->RBAR = 0x00;
    MPU->RASR = 0x00;
  }
}

此函数在本教程第xx章有专门的讲解（注：后面做到这个章节时补上）。