【STM32H7教程】第12章 STM32H7的HAL庫框架設計學習

完整教程下載地址：http://www.armbbs.cn/forum.php?mod=viewthread&tid=86980

第12章       STM32H7的HAL庫框架設計學習

通過本章節，主要是想讓大家對HAL庫程序設計的基本套路有個了解，防止踩坑。

12.1 初學者重要提示

12.2 HAL庫的配置文件

12.3 HAL庫的時間基准

12.4 HAL庫的啟動流程

12.5 HAL庫初始化外設

12.6 HAL庫的中斷處理思路

12.7 HAL庫的DMA處理思路

12.8 總結

 

 

12.1 初學者重要提示

1.   學習使用HAL庫前，有必要對他們的基本設計框架有所了解，然后深入學習，效果更好。
2.  為了方便調用，HAL庫為各種外設基本都配了三套API，查詢，中斷和DMA。

12.2 HAL庫的配置文件

HAL庫有一個專門的配置文件叫stm32h7xx_hal_conf.h，這個文件里面有一個很重要的參數，就是HSE_VALUE，大家所設計板子使用的實際晶振大小一定要與這個數值一致。比如V7的外置晶振是25MHz，那么這里就務必配置宏定義為：

#define HSE_VALUE    ((uint32_t)25000000)

 

完整的代碼如下：

1.    /* ########################## Module Selection ############################## */
2.    /**
3.      * @brief This is the list of modules to be used in the HAL driver 
4.      */
5.    #define HAL_MODULE_ENABLED
6.    #define HAL_ADC_MODULE_ENABLED
7.    #define HAL_CEC_MODULE_ENABLED
8.    
9.     /* 省略未寫 */
10.    
11.    /* ########################## Oscillator Values adaptation ####################*/
12.    /**
13.      * @brief Adjust the value of External High Speed oscillator (HSE) used in your application.
14.      *        This value is used by the RCC HAL module to compute the system frequency
15.      *        (when HSE is used as system clock source, directly or through the PLL).  
16.      */
17.    #if !defined  (HSE_VALUE) 
18.    #define HSE_VALUE    ((uint32_t)25000000) /*!< Value of the External oscillator in Hz */
19.    #endif /* HSE_VALUE */
20.    
21.    #if !defined  (HSE_STARTUP_TIMEOUT)
22.      #define HSE_STARTUP_TIMEOUT    ((uint32_t)5000)   /*!< Time out for HSE start up, in ms */
23.    #endif /* HSE_STARTUP_TIMEOUT */
24.    
25.    /**
26.      * @brief Internal  oscillator (CSI) default value.
27.      *        This value is the default CSI value after Reset.
28.      */
29.    #if !defined  (CSI_VALUE)
30.      #define CSI_VALUE    ((uint32_t)4000000) /*!< Value of the Internal oscillator in Hz*/
31.    #endif /* CSI_VALUE */
32.       
33.    /**
34.      * @brief Internal High Speed oscillator (HSI) value.
35.      *        This value is used by the RCC HAL module to compute the system frequency
36.      *        (when HSI is used as system clock source, directly or through the PLL). 
37.      */
38.    #if !defined  (HSI_VALUE)
39.      #define HSI_VALUE    ((uint32_t)64000000) /*!< Value of the Internal oscillator in Hz*/
40.    #endif /* HSI_VALUE */
41.    
42.    /**
43.      * @brief External Low Speed oscillator (LSE) value.
44.      *        This value is used by the UART, RTC HAL module to compute the system frequency
45.      */
46.    #if !defined  (LSE_VALUE)
47.      #define LSE_VALUE    ((uint32_t)32768) /*!< Value of the External oscillator in Hz*/
48.    #endif /* LSE_VALUE */
49.    
50.       
51.    #if !defined  (LSE_STARTUP_TIMEOUT)
52.      #define LSE_STARTUP_TIMEOUT    ((uint32_t)5000)   /*!< Time out for LSE start up, in ms */
53.    #endif /* LSE_STARTUP_TIMEOUT */
54.    
55.    /**
56.      * @brief External clock source for I2S peripheral
57.      *        This value is used by the I2S HAL module to compute the I2S clock source 
58.      *        frequency, this source is inserted directly through I2S_CKIN pad. 
59.      */
60.    #if !defined  (EXTERNAL_CLOCK_VALUE)
61.      #define EXTERNAL_CLOCK_VALUE    12288000U /*!< Value of the External clock in Hz*/
62.    #endif /* EXTERNAL_CLOCK_VALUE */
63.    
64.    /* Tip: To avoid modifying this file each time you need to use different HSE,
65.       ===  you can define the HSE value in your toolchain compiler preprocessor. */
66.    
67.    /* ########################### System Configuration ######################### */
68.    /**
69.      * @brief This is the HAL system configuration section
70.      */     
71.    #define  VDD_VALUE                    ((uint32_t)3300) /*!< Value of VDD in mv */
72.    #define  TICK_INT_PRIORITY            ((uint32_t)0x0F) /*!< tick interrupt priority */
73.    #define  USE_RTOS                     0
74.    /* #define  USE_SD_TRANSCEIVER           1U   */            /*!< use uSD Transceiver */
75.    
76.    /* ########################### Ethernet Configuration ######################### */
77.    #define ETH_TX_DESC_CNT         4  /* number of Ethernet Tx DMA descriptors */
78.    #define ETH_RX_DESC_CNT         4  /* number of Ethernet Rx DMA descriptors */
79.    
80.    #define ETH_MAC_ADDR0    ((uint8_t)0x02)
81.    #define ETH_MAC_ADDR1    ((uint8_t)0x00)
82.    #define ETH_MAC_ADDR2    ((uint8_t)0x00)
83.    #define ETH_MAC_ADDR3    ((uint8_t)0x00)
84.    #define ETH_MAC_ADDR4    ((uint8_t)0x00)
85.    #define ETH_MAC_ADDR5    ((uint8_t)0x00)
86.    
87.    /* ########################## Assert Selection ############################## */
88.    /**
89.      * @brief Uncomment the line below to expanse the "assert_param" macro in the 
90.      *        HAL drivers code
91.      */
92.    /* #define USE_FULL_ASSERT    1 */
93.    
94.    
95.    /* ################## SPI peripheral configuration ########################## */
96.    /** 
97.      * @brief Used to activate CRC feature inside HAL SPI Driver
98.      *        Activated   (1U): CRC code is compiled within HAL SPI driver
99.      *        Deactivated (0U): CRC code excluded from HAL SPI driver
100.      */
101.    
102.    #define USE_SPI_CRC                   1U
103.    
104.    
105.    /* Includes ------------------------------------------------------------------*/
106.    /**
107.      * @brief Include module's header file 
108.      */
109.    
110.    #ifdef HAL_RCC_MODULE_ENABLED
111.      #include "stm32h7xx_hal_rcc.h"
112.    #endif /* HAL_RCC_MODULE_ENABLED */
113.    /* 省略未寫 */
114.    
115.       
116.    /* Exported macro ------------------------------------------------------------*/
117.    #ifdef  USE_FULL_ASSERT
118.    /**
119.      * @brief  The assert_param macro is used for function's parameters check.
120.      * @param  expr: If expr is false, it calls assert_failed function
121.      *         which reports the name of the source file and the source
122.      *         line number of the call that failed. 
123.      *         If expr is true, it returns no value.
124.      * @retval None
125.      */
126.      #define assert_param(expr) ((expr) ? (void)0 : assert_failed((uint8_t *)__FILE__, __LINE__))
127.    /* Exported functions ------------------------------------------------------- */
128.      void assert_failed(uint8_t* file, uint32_t line);
129.    #else
130.      #define assert_param(expr) ((void)0)
131.    #endif /* USE_FULL_ASSERT */

除了HSE_VALUE，下面幾個也要作為了解：

•   第72行，滴答定時器的優先級設置。這個優先級的設置至關重要。因為HAL庫中各個外設驅動里面的延遲實現是基於此文件提供的時間基准。

如果在中斷服務程序里面調用基於此時間基准的延遲函數HAL_Delay要特別注意，因為這個函數的時間基准是基於滴答定時器或者其他通用定時器實現，實現方式是滴答定時器或者其他通用定時器里面對變量計數。如此以來，結果是顯而易見的，如果其他中斷服務程序調用了此函數，且中斷優先級高於滴答定時器，會導致滴答定時器中斷服務程序一直得不到執行，從而卡死在里面。所以滴答定時器的中斷優先級一定要比他們高。

另外這個時間基准既可以使用滴答定時器實現也可以使用通用的定時器實現，默認情況下是用的滴答定時器。

•   第73行，當前HAL庫還不支持RTOS方式。
•   第74行，STM32H7的SDIO外接支持UHS-I 模式 (SDR12, SDR25, SDR50, SDR104和DDR50)的SD卡，需要1.8的電平轉換器，此選項就是來使能此功能用的。
•   第92行，用於使能斷言功能，在HAL庫的API里面都有用到，用來判斷函數形參是否有效。默認情況下是關閉的。
•   第126行，使能斷言功能后，實際對應的代碼位置。這里沒有對函數void assert_failed(uint8_t* file, uint32_t line)做具體實現，大家可以根據自己的需求去實現，這里提供一個參考：

/* 
    ST庫函數使用了C編譯器的斷言功能，如果定義了USE_FULL_ASSERT，那么所有的ST庫函數將檢查函數形參
    是否正確。如果不正確將調用 assert_failed() 函數，這個函數是一個死循環，便於用戶檢查代碼。
    
    關鍵字 __LINE__ 表示源代碼行號。
    關鍵字__FILE__表示源代碼文件名。
    
    斷言功能使能后將增大代碼大小，推薦用戶僅在調試時使能，在正式發布軟件是禁止。

    用戶可以選擇是否使能ST固件庫的斷言供能。使能斷言的方法有兩種：
    (1) 在C編譯器的預定義宏選項中定義USE_FULL_ASSERT。
    (2) 在本文件取消"#define USE_FULL_ASSERT    1"行的注釋。    
*/

/*
*********************************************************************************************************
*    函 數 名: assert_failed
*    形    參：file : 源代碼文件名稱。關鍵字__FILE__表示源代碼文件名。
*              line ：代碼行號。關鍵字 __LINE__ 表示源代碼行號
*    返 回 值: 無
*********************************************************************************************************
*/
void assert_failed(uint8_t* file, uint32_t line)
{ 
    /* 
        用戶可以添加自己的代碼報告源代碼文件名和代碼行號，比如將錯誤文件和行號打印到串口
        printf("Wrong parameters value: file %s on line %d\r\n", file, line) */
    */
    
    /* 這是一個死循環，斷言失敗時程序會在此處死機，以便於用戶查錯 */
    while (1)
    {
    }
}

12.3 HAL庫的時間基准

為了方便各種外設延遲的實現，HAL庫專門搞了一個時間基准，默認來源是滴答定時器，也可以通過重定向使用其他定時器實現。相關函數全部集中在stm32h7xx_hal.c文件里面實現，關於這些函數在本教程的第16章有詳細講解。

12.4 HAL庫的啟動流程

這里通過V7板子初始化流程做個說明：

1.    /*
2.    ******************************************************************************************************
3.    *    函 數 名: bsp_Init
4.    *    功能說明: 初始化所有的硬件設備。該函數配置CPU寄存器和外設的寄存器並初始化一些全局變量。
5.    *              只需要調用一次
6.    *    形    參：無
7.    *    返 回 值: 無
8.    ******************************************************************************************************
9.    */
10.    void bsp_Init(void)
11.    {
12.        /* 配置MPU */
13.        MPU_Config();
14.        
15.        /* 使能L1 Cache */
16.        CPU_CACHE_Enable();
17.    
18.        /* 
19.           STM32H7xx HAL 庫初始化，此時系統用的還是H7自帶的64MHz，HSI時鍾:
20.           - 調用函數HAL_InitTick，初始化滴答時鍾中斷1ms。
21.           - 設置NVIV優先級分組為4。
22.         */
23.        HAL_Init();
24.    
25.        /* 
26.           配置系統時鍾到400MHz
27.           - 切換使用HSE。
28.           - 此函數會更新全局變量SystemCoreClock，並重新配置HAL_InitTick。
29.        */
30.        SystemClock_Config();
31.    
32.        
33.        bsp_InitKey();        /* 按鍵初始化，要放在滴答定時器之前，因為按鈕檢測是通過滴答定時器掃描 */
34.        bsp_InitTimer();      /* 初始化滴答定時器 */
35.        bsp_InitUart();    /* 初始化串口 */
36.        bsp_InitExtIO();    /* 初始化FMC總線74HC574擴展IO. 必須在 bsp_InitLed()前執行 */    
37.        bsp_InitLed();        /* 初始化LED */    
38.        
39.        bsp_InitLPTIMOutPWM(); /* 低功耗定時器PWM輸出 */
40.    }

•   第13 – 16行，配置MPU和使能Cache，對於H7而已，這兩個函數要優先執行，因為Flash速度，SRAM速度跟CPU和TCM有些差距的，所以要使能Cache。而不同存儲區的Cache策略要通過MPU分別進行配置。
•   第23行，調用函數HAL_Init時，系統依然使用的64MHz HSI時鍾，這點要特別注意。此函數會調用函數HAL_InitTick，初始化滴答時鍾中斷1ms，並設置NVIV優先級分組為4。

這里就隱含了一個知識點，就是它會開啟滴答定時器中斷，如果用戶也要使用滴答定時器中斷，此問題就要引起注意，我們的bsp_timer.C文件解決辦法如下：

/*
*********************************************************************************************************
*    函 數 名: SysTick_Handler
*    功能說明: 系統嘀嗒定時器中斷服務程序。啟動文件中引用了該函數。
*    形    參:  無
*    返 回 值: 無
*********************************************************************************************************
*/
void SysTick_Handler(void)
{
    HAL_IncTick();    /* ST HAL庫的滴答定時中斷服務程序 */
    
    if (g_ucEnableSystickISR == 0) /* 做了一個變量標志，調用了函數bsp_InitTimer才置位此變量 */
    {
        return;
    }
    
    SysTick_ISR();    /* 安富萊bsp庫的滴答定時中斷服務程序 */
}

•   第30行，通過此函數切換HSI到外部高速時鍾HSE，並配置系統時鍾到400MHz。調用這個函數會更新全局變量SystemCoreClock，並重新配置HAL_InitTick。
•   前面幾步執行完畢后就可以初始化外設了。

12.5 HAL庫初始化外設

HAL庫為外設初始化提供了一套框架，這里以串口為例進行說明，調用函數HAL_UART_Init初始化串口，此函數就會調用HAL_UART_MspInit，這個函數是弱定義的，在stm32h7xx_hal_uart.c文件里面：

/**

  * @brief Initialize the UART MSP.

  * @param huart: UART handle.

  * @retval None

  */

__weak void HAL_UART_MspInit(UART_HandleTypeDef *huart)

{

  /* Prevent unused argument(s) compilation warning */

  UNUSED(huart);

 

  /* NOTE : This function should not be modified, when the callback is needed,

            the HAL_UART_MspInit can be implemented in the user file

   */

}

如果要初始化，直接將此函數在其它源文件里面實現即可，如果用到了中斷和DMA，也是直接在這里填寫。

void HAL_UART_MspInit(UART_HandleTypeDef* huart)
{
    GPIO_InitTypeDef GPIO_InitStruct = {0};
    
    if(huart->Instance==USART1)
    {
        __HAL_RCC_USART1_CLK_ENABLE();

        __HAL_RCC_GPIOB_CLK_ENABLE();

        GPIO_InitStruct.Pin = GPIO_PIN_7;
        GPIO_InitStruct.Mode = GPIO_MODE_AF_PP;
        GPIO_InitStruct.Pull = GPIO_NOPULL;
        GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_LOW;
        GPIO_InitStruct.Alternate = GPIO_AF7_USART1;
        HAL_GPIO_Init(GPIOB, &GPIO_InitStruct);

        GPIO_InitStruct.Pin = GPIO_PIN_14;
        GPIO_InitStruct.Mode = GPIO_MODE_AF_PP;
        GPIO_InitStruct.Pull = GPIO_NOPULL;
        GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_LOW;
        GPIO_InitStruct.Alternate = GPIO_AF4_USART1;
        HAL_GPIO_Init(GPIOB, &GPIO_InitStruct);
    }
    else if(huart->Instance==USART2)
    {
        __HAL_RCC_USART2_CLK_ENABLE();

        __HAL_RCC_GPIOD_CLK_ENABLE();
        __HAL_RCC_GPIOA_CLK_ENABLE();

        GPIO_InitStruct.Pin = GPIO_PIN_6;
        GPIO_InitStruct.Mode = GPIO_MODE_AF_PP;
        GPIO_InitStruct.Pull = GPIO_NOPULL;
        GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_LOW;
        GPIO_InitStruct.Alternate = GPIO_AF7_USART2;
        HAL_GPIO_Init(GPIOD, &GPIO_InitStruct);

        GPIO_InitStruct.Pin = GPIO_PIN_2;
        GPIO_InitStruct.Mode = GPIO_MODE_AF_PP;
        GPIO_InitStruct.Pull = GPIO_NOPULL;
        GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_LOW;
        GPIO_InitStruct.Alternate = GPIO_AF7_USART2;
        HAL_GPIO_Init(GPIOA, &GPIO_InitStruct);
    }
}

由於所有串口都是通過函數HAL_UART_Init做初始化，所以函數HAL_UART_MspInit也是共用的。因此需要大家在這個里面區分是配置的哪個串口。

12.6 HAL庫的中斷處理思路

為了加強對中斷的管理，HAL庫也為各種外設中斷也配套一個函數，比如串口就是函數HAL_UART_IRQHandler。

void USART1_IRQHandler(void)
{
    /* USER CODE BEGIN USART1_IRQn 0 */
         此處可以添加用戶代碼
    /* USER CODE END USART1_IRQn 0 */

     /* 參數是串口句柄 */
    HAL_UART_IRQHandler(&huart1); 

    /* USER CODE BEGIN USART1_IRQn 1 */
         此處可以添加用戶代碼
    /* USER CODE END USART1_IRQn 1 */
}

那么問題來了，如果要實現功能，用戶的應用程序怎么寫入中斷？用戶可以直接在函數HAL_UART_IRQHandler的前面或者后面添加新代碼，也可以直接在HAL_UART_IRQHandler調用的各種回調函數里面執行，這些回調都是弱定義的，方便用戶直接在其它文件里面重定義（下面回調主要是用於串口DMA時調用的）：

HAL_UART_TxHalfCpltCallback()
HAL_UART_TxCpltCallback()
HAL_UART_RxHalfCpltCallback()
HAL_UART_RxCpltCallback()
HAL_UART_ErrorCallback()

12.7 HAL庫的DMA處理思路

為了方便各種外設直接啟動DMA，HAL庫專門為支持DMA操作的外設都提供了對應的DMA函數，比如串口的：

HAL_UART_Transmit_DMA()
HAL_UART_Receive_DMA()
HAL_UART_DMAPause()
HAL_UART_DMAResume()
HAL_UART_DMAStop()

這里特別注意一點，針對外設的DMA函數基本都有開啟中斷，如果用戶使能此外設的NVIC，使用中務必別忘了寫DMA的中斷服務程序，比如使用DMA1_Stream1：

void DMA1_Stream1_IRQHandler(void)
{
    /* USER CODE BEGIN USART1_IRQn 0 */
         此處可以添加用戶代碼
    /* USER CODE END USART1_IRQn 0 */

      /* 參數是DMA句柄 */
     HAL_DMA_IRQHandler(&hdma_usart1_tx);

    /* USER CODE BEGIN USART1_IRQn 1 */
         此處可以添加用戶代碼
    /* USER CODE END USART1_IRQn 1 */
}

如果要在DMA傳輸完成，半傳輸完成等中斷里面執行功能，也是通過HAL_DMA_IRQHandler調用的各種回調函數里面實現，這些回調都是弱定義的，方便用戶直接在其它文件里面重定義：

HAL_UART_TxHalfCpltCallback()
HAL_UART_TxCpltCallback()
HAL_UART_RxHalfCpltCallback()
HAL_UART_RxCpltCallback()

12.8 總結

先從整體框架上把握HAL庫，然后具體外設具體學習，后面做應用會得心應手些。