【STM32H7教程】第16章 STM32H7必备的HAL库API（重要）

【STM32H7教程】第16章 STM32H7必备的HAL库API（重要）
完整教程下载地址：http://www.armbbs.cn/forum.php?mod=viewthread&tid=86980

第16章 STM32H7必备的HAL库API（重要）

本章教程为大家讲解制作一个STM32H7的例子所需的最基本API函数，对于一些常用的API函数，一定要熟练掌握这些函数都是实现了什么功能，不常用的函数有个了解即可，用到的时候再去学。

16.1 初学者重要提示

16.2 那些是必备的API

16.3 源文件stm32h7xx_hal.c

16.4 stm32h7xx_hal_rcc.c

16.5 stm32h7xx_hal_cortex.c

16.6 总结

16.1 初学者重要提示
- 对于一些常用的函数，大家一定要熟练的掌握都实现了什么功能，比如HAL_Init，HAL_RCC_OscConfig，HAL_RCC_ClockConfig等。最好的办法是把这些函数的源码读一遍。
16.2 那些是必备的API

这里我们通过一个简单的初始化流程来了解STM32H7的工程模板所必备的库文件和API：

第1步：系统上电复位，进入启动文件startup_stm32h743xx.s，在这个文件里面执行复位中断服务程序。
- 在复位中断服务程序里面执行函数SystemInit，此函数在文件system_stm32h7xx.c里面。
- 之后是调用编译器封装好的函数，比如用于MDK的启动文件是调用__main，最终进入到main函数。
第2步：进入到main函数就可以开始用户应用程序编程了。在这个函数里面要做几个重要的初始化，依次是：
- MPU初始化，需要用到库文件stm32h7xx_hal_cortex.c和stm32h7xx_hal_cortex.h。
- Cache初始化，需要用到core_cm7.h文件。
- HAL库初始化函数HAL_Init，需要用到文件stm32h7xx_hal.c。
- 系统时钟初始化，需要用到库文件stm32h7xx_hal_rcc.c。
前面的两步完成后，就可以开始做用户需要的按键、串口等方面的初始化和应用代码的实现了。这里把我们需要学习的几个库文件整理出来，依次有：
- startup_stm32h743xx.s
- system_stm32h7xx.c
- stm32h7xx_hal.c
- stm32h7xx_hal_cortex.c
- stm32h7xx_hal_rcc.c
- core_cm7.h
其中startup_stm32h743xx.s和system_stm32h7xx.c已经在第13章为大家讲解过，这里不再赘述。而MPU和Cache涉及到的文件core_cm7.h在第23和24章为大家讲解。本章教程重点为大家讲解文件stm32h7xx_hal.c、stm32h7xx_hal_cortex.c和sm32h7xx_hal_rcc.c。

16.3 源文件stm32h7xx_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)
{
  /* 设置中断优先级分组 */
  HAL_NVIC_SetPriorityGrouping(NVIC_PRIORITYGROUP_4);

  /* 使用滴答定时器做为默认时基，配置为1ms滴答，另外系统上电后默认使用的HIS时钟 */
  if(HAL_InitTick(TICK_INT_PRIORITY) != HAL_OK)
  {
    return HAL_ERROR;
  }

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

  /* 返回函数状态 */
  return HAL_OK;
}
```
函数描述：

此函数用于初始化HAL库，此函数主要实现如下功能：
- 设置NVIC优先级分组是4。
- 设置滴答定时器的每1ms中断一次。
- HAL库不像之前的标准库，在系统启动函数SystemInit里面做了RCC初始化，HAL库是没有做的，所以进入到main函数后，系统还在用内部高速时钟HSI，对于H7来说，HSI主频是64MHz。
- 函数HAL_Init里面调用的HAL_MspInit一般在文件stm32h7xx_hal_msp.c里面做具体实现，主要用于底层初始化。当前此函数也在文件stm32h7xx_hal.c里面，只是做了弱定义。
函数参数：
- 返回值，返回HAL_ERROR表示参数错误，HAL_OK表示发送成功，HAL_BUSY表示忙，正在使用中。
注意事项：
1. 必须在main函数里面优先调用此函数。
2. 用户务必保证每1ms一次滴答中断。
3. 关于优先级分组的设置可以看第21章节。
使用举例：

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

16.3.2 函数HAL_DeInit

函数原型：
```
HAL_StatusTypeDef HAL_DeInit(void)
{
  /* 复位所有外设 */__set_PRIMASK
  __HAL_RCC_AHB3_FORCE_RESET();
  __HAL_RCC_AHB3_RELEASE_RESET();

  /* 省略未写 */

  __HAL_RCC_APB4_FORCE_RESET();
  __HAL_RCC_APB4_RELEASE_RESET();

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

  /* 返回值 */
  return HAL_OK;
}
```
函数描述：

此函数用于复位HAL库和滴答时钟。
- 复位了AHB1,2,3,4的时钟以及APB1L，APB1H，APB2,3,4的时钟。
- 函数HAL_DeInit里面调用的HAL_MspDeInit一般在文件stm32h7xx_hal_msp.c里面做具体实现，主要用于底层初始化，跟函数HAL_Init里面调用的HAL_MspInit是一对。当前此函数也在文件stm32h7xx_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 函数HAL_SYSCFG_VREFBUF_VoltageScalingConfig

函数原型：
```
void HAL_SYSCFG_VREFBUF_VoltageScalingConfig(uint32_t VoltageScaling)
```
函数描述：

此函数用于配置STM32H7内部电压基准大小。
- 当形参VoltageScaling = SYSCFG_VREFBUF_VOLTAGE_SCALE0时
输出基准是2.048 V，条件是VDDA >= 2.4V。
- 当形参VoltageScaling = SYSCFG_VREFBUF_VOLTAGE_SCALE1时
输出基准是2.5 V，条件是VDDA >= 2.8V。
- 当形参VoltageScaling = SYSCFG_VREFBUF_VOLTAGE_SCALE2时
输出基准是1.5 V，条件是VDDA >= 1.8V。
- 当形参VoltageScaling = SYSCFG_VREFBUF_VOLTAGE_SCALE3时
输出基准是1.8 V，条件是VDDA >= 2.1V。

16.3.6 H7自带电压基准相关函数

函数原型：
```
void HAL_SYSCFG_VREFBUF_VoltageScalingConfig(uint32_t VoltageScaling)
void HAL_SYSCFG_VREFBUF_TrimmingConfig(uint32_t TrimmingValue)
HAL_StatusTypeDef HAL_SYSCFG_EnableVREFBUF(void)
void HAL_SYSCFG_DisableVREFBUF(void)
```
函数描述：
- 函数HAL_SYSCFG_VREFBUF_VoltageScalingConfig
此函数用于配置STM32H7内部电压基准是否在芯片内部与VREF+引脚接通。
1. 形参为SYSCFG_VREFBUF_HIGH_IMPEDANCE_DISABLE时，表示导通。
2. 形参为SYSCFG_VREFBUF_HIGH_IMPEDANCE_ENABLE时，表示高阻，即不导通。
- 函数HAL_SYSCFG_VREFBUF_TrimmingConfig
此函数用于内部电压基准的校准调节。
- 函数HAL_SYSCFG_EnableVREFBUF和HAL_SYSCFG_DisableVREFBUF是一对，分别用于内部电压参考基准的禁止和使能。
16.3.7 函数HAL_SYSCFG_AnalogSwitchConfig

函数原型：
```
void HAL_SYSCFG_AnalogSwitchConfig(uint32_t SYSCFG_AnalogSwitch , uint32_t SYSCFG_SwitchState )
```
函数描述：
- 引脚PA0，PA1，PC2，PC3用于ADC时，还有一组对应的可选引脚PA0_C，PA1_C，PC2_C和PC3_C。此函数的作用就是切换可选引脚。关于这个问题的详情可看此贴：http://www.armbbs.cn/forum.php?mod=viewthread&tid=87707 。
16.3.8 BOOST的使能和禁止（用于ADC）

函数原型：
```
void HAL_SYSCFG_EnableBOOST(void)
void HAL_SYSCFG_DisableBOOST(void)
```
函数描述：
- 这两个函数用于使能或者禁止Booster。如果使能了booster的话，在供电电压低于2.7V时，可以减少模拟开关总的谐波失真，这样的话，模拟开关的性能跟正常供电电压时的全范围测量一样。
16.3.9 函数HAL_SYSCFG_CM7BootAddConfig

函数原型：
```
void HAL_SYSCFG_CM7BootAddConfig(uint32_t BootRegister, uint32_t BootAddress)
```
函数描述：

用于配置BOOT = 0或者BOOT = 1时的启动地址，详情可以看第13章的13.4小节。

16.3.10 IO补偿相关函数

函数原型：
```
void HAL_EnableCompensationCell(void)
void HAL_DisableCompensationCell(void)
void HAL_SYSCFG_EnableIOSpeedOptimize(void)
void HAL_SYSCFG_DisableIOSpeedOptimize(void)
void HAL_SYSCFG_CompensationCodeSelect(uint32_t SYSCFG_CompCode)
void HAL_SYSCFG_CompensationCodeConfig(uint32_t SYSCFG_PMOSCode, uint32_t SYSCFG_NMOSCode )
```
函数描述：
- 函数HAL_EnableCompensationCell和HAL_DisableCompensationCell
分别用于使能或者禁止IO补偿，只有在供电电压范围是2.4V到3.6V之间时，使用此功能才有意义。
- 函数HAL_SYSCFG_EnableIOSpeedOptimize和HAL_SYSCFG_DisableIOSpeedOptimize
分别用于优化IO速度或者禁止优化，不过仅在供电电压低于2.5V时可用，高于2.5V是不可以使用的，另外使用这个功能的前提是用户使能了PRODUCT_BELOW_25V（是可选字节配置选项里面的一个bit）。
- 函数HAL_SYSCFG_CompensationCodeSelect
IO补偿单元的选择，函数形参可以是SYSCFG_CELL_CODE，即寄存器SYSCFG_CCVR，也可以是SYSCFG_REGISTER_CODE，即寄存器SYSCFG_CCCR。
- 函数HAL_SYSCFG_CompensationCodeConfig
用于设置GPIO内部构造中NMOS和PMOS的补偿值，两个形参的范围都是0-15。根据用户调用函数HAL_SYSCFG_CompensationCodeSelect选择的寄存器，这里仅有一个形参的设置是有效的。

16.3.11 低功耗和EXTI相关函数

低功耗和EXTI相关的函数暂时不做讲解，后面章节用到时候再说明。

16.4 源文件stm32h7xx_hal_rcc.c

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

学习这个文件注意事项：
- 系统上电复位后，通过内部高速时钟HSI运行（主频64MHz），Flash工作在0等待周期，所有外设除了SRAM、Flash、JTAG 和 PWR，时钟都是关闭的。这里特别注意SRAM，官方手册里面说的太笼统，这个SRAM到底是指的哪个SRAM。关于这个问题，详情看此贴：http://www.armbbs.cn/forum.php?mod=viewthread&tid=87784 。
1. AHB和APB总线无分频，所有挂载这两类总线上的外设都是以HSI频率运行。
2. 所有的GPIO都是模拟模式，除了JTAG相关的几个引脚。
- 系统上电复位后，用户需要完成以下工作：
1. 选择用于驱动系统时钟的时钟源。
2. 配置系统时钟频率和Flash设置。
3. 配置分频器。
4. 使能外设时钟。
5. 配置外设时钟源，部分外设的时钟可以不来自系统时钟，此时通过配置寄存器RCC_D1CCIPR、RCC_D2CCIP1R、RCC_D2CCIP2R 和 RCC_D3CCIPR 实现。
RCC局限性：

使能了外设时钟后，不能立即操作对应的寄存器，要加延迟。不同外设延迟不同：
- 如果是AHB的外设，使能了时钟后，需要等待2个AHB时钟周期才可以操作这个外设的寄存器。
- 如果是APB的外设，使能了时钟后，需要等待2个APB时钟周期才可以操作这个外设的寄存器。
当前HAL库的解决方案是在使能了外设时钟后，再搞一个读操作，算是当做延迟用。

比如下面使能GPIOA的时钟：
```
#define __HAL_RCC_GPIOA_CLK_ENABLE()   do { 
                                        __IO uint32_t tmpreg; 
                                        SET_BIT(RCC->AHB4ENR, RCC_AHB4ENR_GPIOAEN);
                                        /* Delay after an RCC peripheral clock enabling */ 
                                        tmpreg = READ_BIT(RCC->AHB4ENR, RCC_AHB4ENR_GPIOAEN);
                                        UNUSED(tmpreg); 
                                       } while(0)  
```
- 关于时钟方面的知识点补充
1、正确理解HCLK1，2，3，4以及PCLK1，2，3，4对应哪些总线的时钟，下面一张图可以说明问题：

由上图可以得出：

HCLK1，2，3，4对应的是AHB总线AHB1，AHB2，AHB3和AHB4时钟。

PCLK1、2、3、4对应的是APB总线APB1，APB2，APB3和APB4时钟。

2、内部和外部时钟配置：
- HSI (high-speed internal)
高速内部RC振荡器，可以直接或者通过PLL倍频后做系统时钟源。缺点是精度差些，即使经过校准。
- CSI (Low-power internal oscillator)
低功耗内部RC振荡器，作用同HSI，不过主要用于低功耗。
- LSI (low-speed internal)
低速内部时钟，主要用于独立看门狗和RTC的时钟源。
- HSE (high-speed external)
高速外部晶振，可接4 - 48MHz的晶振，可以直接或者通过PLL倍频后做系统时钟源，也可以做RTC的是时钟源。
- LSE (low-speed external)
低速外部晶振，主要用于RTC。
- CSS (Clock security system)
时钟安全系统，一旦使能后，如果HSE启动失败（不管是直接作为系统时钟源还是通过PLL输出后做系统时钟源），系统时钟将切换到HSI。如果使能了中断的话，将进入不可屏蔽中断NMI。
- MCO1 (micro controller clock output)
可以在PA8引脚输出HSI, LSE, HSE, PLL1(PLL1_Q）或HSI48 时钟。
- MCO2 (micro controller clock output)
可以在PC9引脚输出HSE, PLL2(PLL2_P), SYSCLK, LSI, CSI或PLL1(PLL1_P) 时钟。
- PLL锁相环，时钟输入来自HSI , HSE 或者CSI
主锁相环PLL1，用于给CPU和部分外设提供时钟。

专用锁相环PLL2和PLL3，用于给部分外设提供时钟。

3、System, AHB 和 APB总线时钟配置：
- 系统总线时钟源可以来自CSI，HIS，HSE 或 PLL。
- AHB总线时钟是通过系统时钟分频产生的，用于给AXI，AHB1，2，3，4和APB1，2，3，4九个总线上的外设提供时钟。另外用户可以通过函数HAL_RCC_GetSysClockFreq获取系统时钟。
- 所有外设时钟都可以通过系统时钟获取，并且部分外设还支持多个时钟源，比如下面串口1,6
16.4.1 函数HAL_RCC_DeInit

函数原型：
```
void HAL_RCC_DeInit(void)
{
  /* Set HSION bit */
  SET_BIT(RCC->CR, RCC_CR_HSION);

  /* Reset CFGR register */
  CLEAR_REG(RCC->CFGR);

  /* 省略未写 */

  /* Reset HSEBYP bit */
  CLEAR_BIT(RCC->CR, RCC_CR_HSEBYP);

  /* Disable all interrupts */
  CLEAR_REG(RCC->CICR);
}
```
函数描述：

此函数用于RCC复位函数，主要实现如下功能：
- HSI 打开作为系统时钟。
- HSE, PLL1, PLL2 和 PLL3 关闭。
- AHB, APB 总线无分频。
- CSS, MCO1 和 MCO2 关闭。
- 所有中断关闭。
注意事项：
1. 此函数不会修改外设时钟，LSI、LSE和RTC时钟。
使用举例：

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

16.4.2 函数HAL_RCC_OscConfig

函数原型：

函数描述：

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

函数参数：
- 函数的形参是RCC_OscInitTypeDef类型结构体变量，这个结构体的定义如下（主要是HSE、HSI、CSI、LSI、HSI48、LSE和PLL的配置变量）：
```
/**
  * @brief  RCC Internal/External Oscillator (HSE, HSI, CSI, 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;            
  uint32_t HSI48State;           
  uint32_t CSIState;            
  uint32_t CSICalibrationValue;  
  RCC_PLLInitTypeDef PLL;      
}RCC_OscInitTypeDef;
```
注意事项：
1. LSE Bypass 切换到 LSE On 或者 LSE On切换到 LSE Bypass都不支持，用需要先关闭LSE，然后才可以切换到LSE Bypass 或者LSE On。
2. HSE Bypass 切换到 HSE On 或者 LSE On切换到 LSE Bypass都不支持，用需要先关闭HSE，然后才可以切换到HSE Bypass 或者HSE On。
使用举例：
```
    RCC_OscInitTypeDef RCC_OscInitStruct;
    HAL_StatusTypeDef ret = HAL_OK;

    /* 使能HSE，并选择HSE作为PLL时钟源 */
    RCC_OscInitStruct.OscillatorType = RCC_OSCILLATORTYPE_HSE;
    RCC_OscInitStruct.HSEState = RCC_HSE_ON;
    RCC_OscInitStruct.HSIState = RCC_HSI_OFF;
    RCC_OscInitStruct.CSIState = RCC_CSI_OFF;
    RCC_OscInitStruct.PLL.PLLState = RCC_PLL_ON;
    RCC_OscInitStruct.PLL.PLLSource = RCC_PLLSOURCE_HSE;
        
    RCC_OscInitStruct.PLL.PLLM = 5;
    RCC_OscInitStruct.PLL.PLLN = 160;
    RCC_OscInitStruct.PLL.PLLP = 2;
    RCC_OscInitStruct.PLL.PLLR = 2;
    RCC_OscInitStruct.PLL.PLLQ = 4;        
        
    RCC_OscInitStruct.PLL.PLLVCOSEL = RCC_PLL1VCOWIDE;
    RCC_OscInitStruct.PLL.PLLRGE = RCC_PLL1VCIRANGE_2;    
    ret = HAL_RCC_OscConfig(&RCC_OscInitStruct);
    if(ret != HAL_OK)
    {
        Error_Handler(__FILE__, __LINE__);
    }
```
16.4.3 函数HAL_RCC_ClockConfig

函数原型：

函数描述：

通过上面函数原型，我们可以一目了然的看出此函数的作用，配置了CPU、AHB和APB的所有总线时钟，即HCLK，SYSTICK，D1PCLK1，PCLK1，PCLK2和D3PCLK1时钟。这里的D1PCLK1其实就是PCLK3，而D3PCLK1是PCLK4。

函数参数：
- 第1个参数是RCC_ClkInitTypeDef类型的结构体变量。
- 第2个参数是Flash的延迟设置。
- 返回值，返回HAL_ERROR表示参数错误，HAL_OK表示发送成功，HAL_BUSY表示忙，正在使用中。
注意事项：
1. 此函数会更新全局变量SystemCoreClock的主频值，并且会再次调用函数HAL_InitTick更新系统滴答时钟，这点要特别注意。
2. 系统上电复位或者从停机、待机模式唤醒后，使用的是HSI作为系统时钟。以防使用HSE直接或者通过PLL输出后做系统时钟时失败（如果使能了CSS）。
3. 目标时钟就绪后才可以从当前的时钟源往这个目标时钟源切换，如果目标时钟源没有就绪，就会等待直到时钟源就绪才可以切换。
4. 根据设备的供电范围，必须正确设置D1CPRE[3:0]位的范围，防止超过允许的最大频率。
使用举例：
```
    RCC_ClkInitTypeDef RCC_ClkInitStruct;
    HAL_StatusTypeDef ret = HAL_OK;

/* 
       选择PLL的输出作为系统时钟
       配置RCC_CLOCKTYPE_SYSCLK系统时钟
       配置RCC_CLOCKTYPE_HCLK 时钟，对应AHB1，AHB2，AHB3和AHB4总线
       配置RCC_CLOCKTYPE_PCLK1时钟，对应APB1总线
       配置RCC_CLOCKTYPE_PCLK2时钟，对应APB2总线
       配置RCC_CLOCKTYPE_D1PCLK1时钟，对应APB3总线
       配置RCC_CLOCKTYPE_D3PCLK1时钟，对应APB4总线     
    */
    RCC_ClkInitStruct.ClockType = (RCC_CLOCKTYPE_SYSCLK | RCC_CLOCKTYPE_HCLK | RCC_CLOCKTYPE_D1PCLK1 |
 RCC_CLOCKTYPE_PCLK1 | 
RCC_CLOCKTYPE_PCLK2  | RCC_CLOCKTYPE_D3PCLK1);

    RCC_ClkInitStruct.SYSCLKSource = RCC_SYSCLKSOURCE_PLLCLK;
    RCC_ClkInitStruct.SYSCLKDivider = RCC_SYSCLK_DIV1;
    RCC_ClkInitStruct.AHBCLKDivider = RCC_HCLK_DIV2;
    RCC_ClkInitStruct.APB3CLKDivider = RCC_APB3_DIV2;  
    RCC_ClkInitStruct.APB1CLKDivider = RCC_APB1_DIV2; 
    RCC_ClkInitStruct.APB2CLKDivider = RCC_APB2_DIV2; 
    RCC_ClkInitStruct.APB4CLKDivider = RCC_APB4_DIV2; 
    
    /* 此函数会更新SystemCoreClock，并重新配置HAL_InitTick */
    ret = HAL_RCC_ClockConfig(&RCC_ClkInitStruct, FLASH_LATENCY_4);
    if(ret != 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个形参用于选择输出的引脚，可选择RCC_MCO1（PA8引脚）或者RCC_MCO2（PC9引脚）。
- 第2个形参用于选择输出的时钟源，MCO1可选择的时钟源如下：
1. RCC_MCO1SOURCE_HSI
2. RCC_MCO1SOURCE_LSE
3. RCC_MCO1SOURCE_HSE
4. RCC_MCO1SOURCE_PLL1QCLK
5. RCC_MCO1SOURCE_HSI48
MCO1可选择的时钟源如下：
1. RCC_MCO2SOURCE_SYSCLK
2. RCC_MCO2SOURCE_PLL2PCLK
3. RCC_MCO2SOURCE_HSE
4. RCC_MCO2SOURCE_PLLCLK
5. RCC_MCO2SOURCE_CSICLK
6. RCC_MCO2SOURCE_LSICLK
- 第3个参数用于设置输出分频，范围从RCC_MCODIV_1到RCC_MCODIV_15。
使用举例：

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

16.4.5 RCC相关函数

函数原型：
```
void HAL_RCC_EnableCSS(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 源文件stm32h7xx_hal_cortex.c

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

更多NVIC相关知识需要大家看第21章节。

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

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

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;
  }
}
```
此函数在本教程第23章有专门的讲解。

16.6 总结

本章节就为大家讲解这么多，对于一些常用的函数，望大家务必要掌握。
相关阅读:
oracle unwrap解密工具
 介绍一款国产的矢量图形设计软件--百绘大师
 windows10上安装OpenSSL_1.1.1d_x64
centos7上安装phantomjs并对页面截屏
 如何用Java Socket实现一个简单的Redis客户端
 cenos上通过yum安装mariadb
windows上杀掉指定名称的进程
 centos磁盘满时查找大文件清理掉
 为Vertica数据库增加自定义函数to_base64和from_base64
解决Vertica集群某节点出现Clock skewed告警
原文地址：https://www.cnblogs.com/armfly/p/10824815.html

【STM32H7教程】第16章 STM32H7必备的HAL库API（重要）

第16章 STM32H7必备的HAL库API（重要）

16.1 初学者重要提示

16.2 那些是必备的API

16.3 源文件stm32h7xx_hal.c（重要）

16.3.1 函数HAL_Init

16.3.2 函数HAL_DeInit

16.3.3 函数HAL_InitTick

16.3.4 Systick的相关函数

16.3.5 函数HAL_SYSCFG_VREFBUF_VoltageScalingConfig

16.3.6 H7自带电压基准相关函数

16.3.7 函数HAL_SYSCFG_AnalogSwitchConfig

16.3.8 BOOST的使能和禁止（用于ADC）

16.3.9 函数HAL_SYSCFG_CM7BootAddConfig

16.3.10 IO补偿相关函数

16.3.11 低功耗和EXTI相关函数

16.4 源文件stm32h7xx_hal_rcc.c

16.4.1 函数HAL_RCC_DeInit

16.4.2 函数HAL_RCC_OscConfig

16.4.3 函数HAL_RCC_ClockConfig

16.4.4 函数HAL_RCC_MCOConfig

16.4.5 RCC相关函数

16.5 源文件stm32h7xx_hal_cortex.c

16.5.1 NVIC相关函数

16.5.2 SysTick相关函数

16.5.3 函数HAL_MPU_ConfigRegion

16.6 总结