【正点原子STM32连载】第七章 认识HAL库 摘自【正点原子】MiniPro STM32H750 开发指南_V1.1
1）實驗平臺：正點原子MiniPro H750開發板
2）平臺購買地址：https://detail.tmall.com/item.htm?id=677017430560
3）全套實驗源碼+手冊+視頻下載地址：http://www.openedv.com/thread-336836-1-1.html
4）對正點原子STM32感興趣的同學可以加群討論：879133275
第七章 認識HAL庫
HAL，英文全稱Hardware Abstraction Layer，即硬件抽象層。HAL庫是ST公司提供的外設驅動代碼的驅動庫，用戶只需要調用庫的API函數，便可間接配置寄存器。我們要寫程序控制STM32芯片，其實最終就是控制它的寄存器，HAL庫就為了更方便我們去控制寄存器，從而節約開發時間。
本章將分為如下幾個小節：
7.1 初識STM32 HAL庫
7.2 HAL庫驅動包
7.3 HAL庫框架結構
7.4 如何使用HAL庫
7.5 HAL庫使用注意事項
7.1 初識STM32 HAL庫
STM32開發中常說的HAL庫開發，指的是利用HAL庫固件包里封裝好的c語言編寫的驅動文件，來實現對STM32內部和外圍電器元件的控制的過程。但只有HAL庫還不能直接驅動一個STM32的芯片，其它的組件已經由ARM與眾多芯片硬件、軟件廠商制定的通用的軟件開發標準CMSIS實現了，本文只簡單介紹這個標準，等大家熟悉開發后再研究這個框架。
簡單地了解HAL庫的發展和作用，可以方便學習者確定HAL庫是否適合作為學習者自己長期開發STM32的工具，以降低開發、學習的成本。
7.1.1 CMSIS標準
根據一些調查研究表明，軟件開發已經被嵌入式行業公認為最主要的開發成本,為了降低這個成本，ARM與Atmel、IAR、KEIL、SEGGER和ST等諸多芯片和軟件工具廠商合作，制定了一個將所有Cortex芯片廠商的產品的軟件接口標準化的標準CMSIS（Cortex Microcon troller Software Interface Standard）。下面來看ARM官方提供的CMSIS規范架構圖，如圖7.1.1.1所示：
圖7.1.1.1 CorteX芯片的CMSIS分級實現
從圖中可以看出這個標準分級明顯，從用戶程序到內核底層實現做了分層。按照這個分級，HAL庫屬于CMSIS-Pack中的“Peripheral HAL”層。CMSIS規定的最主要的3個部分為：核內外設訪問層（由ARM負責實現）、片上外設訪問層和外設訪問函數（后面兩個由芯片廠商負責實現）。ARM整合并提供了大量的模版，各廠商根據自己的芯片差異修改模版，這其中包括匯編文件startup_device.s、system_.h和system_.c這些與初始化和系統相關的函數。
結合STM32H7的芯片來說，其CMSIS應用程序的簡單結構框圖，不包括實時操作系統和中間設備等組件，其結構如圖7.1.1.2所示。
圖7.1.1.2 CMSIS分級下的STM32H7的文件分布
上面的框架是根據我們現在已經學習到的知識回過頭來作的一個總結，這里只是作簡單介紹，告訴大家它們之間存在一定聯系，關于組成這些部分的文件、文件的作用及各文件如何組合、各分層的作用和意義，我們會在今后的學習過程中慢慢學習。
7.1.2 HAL庫簡介
庫函數的引入，大大降低STM主控芯片開發的難度。ST公司為了方便用戶開發STM32芯片開發提供了三種庫函數，從時間產生順序是：標準庫、HAL庫和LL庫。目前ST已經逐漸暫停對部分標準庫的支持，ST的庫函數維護重點對角已經轉移到HAL庫和LL庫上，下面我們分別為這三種庫作一下簡單的介紹。
1.標準外設庫（Standard Peripheral Libraries）
標準外設庫（Standard Peripherals Library）是對STM32芯片的一個完整的封裝，包括所有標準器件外設的器件驅動器，是ST最早推出的針對STM系列主控的庫函數。標準庫的設計的初衷是減少用戶的程序編寫時間，進而降低開發成本。幾乎全部使用C語言實現并嚴格按照“Strict ANSI-C”、MISRA-C 2004等多個C語言標準編寫。但標準外設庫仍然接近于寄存器操作，主要就是將一些基本的寄存器操作封裝成了C函數。開發者仍需要關注所使用的外設是在哪個總線之上，具體寄存器的配置等底層信息。
圖7.1.2.1 ST的標準庫函數家族
ST為各系列提供的標準外設庫稍微有些區別。例如，STM32F1x的庫和STM32F3x的庫在文件結構上就有些不同，此外，在內部的實現上也稍微有些區別，這個在具體使用（移植）時，需要注意一下！但是，不同系列之間的差別并不是很大，而且在設計上是相同的。
STM32的標準外設庫涵蓋以下3個抽象級別：
? 包含位，位域和寄存器在內的完整的寄存器地址映射。
? 涵蓋所有外圍功能（具有公共API的驅動器）的例程和數據結構的集合。
? 一組包含所有可用外設的示例，其中包含最常用的開發工具的模板項目。
關于更詳細的信息，可以參考ST的官方文檔《STM32 固件庫使用手冊中文翻譯版》，文檔中對于標準外設庫函數命名、文件結構等都有詳細的說明，這里我們就不多介紹了。
值得一提的是由于STM32的產品性能及標準庫代碼的規范和易讀性以及例程的全覆蓋性，使STM32的開發難度大大下降，更多。但ST從L1以后的芯片L0、L4和F7等系列就沒有再推出相應的標準庫支持包了。
2.HAL庫
HAL是Hardware Abstraction Layer的縮寫，即硬件抽象層。是ST為可以更好的確保跨STM32產品的最大可移植性而推出的MCU操作庫。這種程序設計由于抽離應用程序和硬件底層的操作，更加符合跨平臺和多人協作開發的需要。
HAL庫是基于一個非限制性的BSD許可協議（Berkeley Software Distribution）而發布的開源代碼。ST制作的中間件堆棧（USB主機和設備庫，STemWin）帶有允許輕松重用的許可模式， 只要是在ST公司的MCU 芯片上使用，庫中的中間件(USB主機/設備庫，STemWin)協議棧即被允許修改，并可以反復使用。至于基于其它著名的開源解決方案商的中間件（FreeRTOS，FatFs，LwIP和PolarSSL）也都具有友好的用戶許可條款。
HAL庫是從ST公司從自身芯片的整個生產生態出發，為了方便維護而作的一次整合，以改變標準外設庫帶來各系列芯片操作函數結構差異大、分化大、不利于跨系列移植的情況。相比標準外設庫，STM32Cube HAL庫表現出更高的抽象整合水平，HAL庫的API集中關注各外設的公共函數功能，這樣便于定義一套通用的用戶友好的API函數接口，從而可以輕松實現從一個STM32產品移植到另一個不同的STM32系列產品。但由于封閉函數為了適應最大的兼容性，HAL庫的一些代碼實際上的執行效率要遠低于寄存器操作。但即便如此，HAL庫仍是ST未來主推的庫。
3.LL庫
LL庫（Low Layer）目前與HAL庫捆綁發布，它的設計為比HAL庫更接近于硬件底層的操作，代碼更輕量級，代碼執行效率更高的庫函數組件，可以完全獨立于HAL庫來使用，但LL庫不匹配復雜的外設，如USB等。所以LL庫并不是每個外設都有對應的完整驅動配置程序。使用LL庫需要對芯片的功能有一定的認知和了解，它可以：
? 獨立使用，該庫完全獨立實現，可以完全拋開HAL庫，只用LL庫編程完成。
? 混合使用，和HAL庫結合使用。
對于HAL庫和LL庫的關系，如圖7.1.2.2 Cube的軟件框架所示，可以看出它們設計為彼此獨立的分支，但又同屬于HAL庫體系。
圖7.1.2.2 Cube的軟件框架
通過以上簡介我們對目前主流的STM32開發庫有了一個初步的印象。標準庫和HAL庫、LL庫完全相互獨立，HAL庫更傾向于外設通用化，擴展組件中解決芯片差異操作部分；LL傾向于最簡單的寄存器操作，ST在未來還將重點維護和建設HAL庫，標準庫已經部分停止更新。HAL庫和LL庫的應用將是未來的一個趨勢。
7.1.3 HAL庫能做什么
用過標準庫的朋友應該知道，使用標準庫可以忽略很多芯片寄存器的細節，根據提供的接口函數快速配置和使用一個STM32芯片，使用HAL庫也是如此。不論何種庫，本質都是配置指定寄存器使芯片工作在我們需要的工作模式下。HAL庫在設計的時候會更注重軟硬件分離。HAL庫的API集中關注各個外設的公共函數功能，便于定義通用性更好、更友好的API函數接口，從而具有更好的可移植性。HAL庫寫的代碼在不同的STM32產品上移植，非常方便。
我們需要學會調用HAL庫的API函數，配置對應外設按照我們的要求工作，這就是HAL庫能做的事。但是無論庫封裝得多高級，最終還是要通過配置寄存器來實現。所以我們學習HAL庫的同時，也建議同時學習外設的工作原理和寄存器的配置。只有掌握了原理，才能更好的使用HAL庫，一旦發生問題也能更快速了定位和解決問題。
HAL庫還可以和STM32CubeMX（圖形化軟件配置工具）配套一起使用，開發者可以使用該工具進行可視化配置，并且自動生成配置好的初始化代碼，大大的節省開發時間。
7.2 HAL庫驅動包
HAL庫是一系列封裝好的驅動函數，本節將從下載渠道、固件包的內容分析及在實際開發中用到的幾個文件的詳細介紹。
7.2.1 如何獲取HAL庫固件包
HAL庫是ST推出的STM32Cube軟件生態下的一個分支。STM32Cube是ST公司提供的一套免費開發工具和STM32Cube 固件包，旨在通過減少開發工作、時間和成本來簡化開發人員的工作，并且覆蓋整個STM32產品。它包含兩個關鍵部分：
1、允許用戶通過圖形化向導來生成C語言工程的圖形配置工具STM32CubeMX。可以通過CubeMX實現方便地下載各種軟件或開發固件包。
2、包括由STM32Cube硬件抽象層（HAL），還有一組一致的中間件組件（RTOS、USB、FAT文件系統、圖形、TCP/IP和以太網），以及一系列完整的例程組成的STM32Cube固件包。
ST提供了多種獲取固件包的方法。本節只介紹從ST官方網站上直接獲取固件庫的方法。網頁登陸：www.st.com，在打開的頁面中依次選擇：“Tools & Software”->“Ecosystem”-> “STM32Cube”->新頁面->選擇“Prodcut selector”，具體如下圖所示：
圖7.2.1.1 找到STM32CubeH7固件包的下載位置
在展開的頁面中選擇我們需要和固件，這里展開“STM32CubeH7”即可看到我們需要的H7的固件包，按下圖操作，在新的窗口中拉到底部，選擇適合自己的下載方式，注冊帳號即可獲取相應的驅動包。
圖7.2.1.2 下載STM32CubeH7固件包
STM32Cube固件包，我們已經給大家下載好并且放到A盤8，STM32參考資料1，STM32CubeH7固件包，當前固件包版本是：STM32Cube_FW_H7_V1.6.0。因為現在是STM32H750的學習，所以我們準備好的固件包是H7的。大家要根據自己學習的芯片，下載對應的固件包。如果需要最新的固件包，大家按照上述的方法到官網重新獲取即可。
7.2.2 STM32Cube固件包分析
STM32Cube 固件包完全兼容STM32CubeMX。對于圖形配置工具STM32CubeMX入門使用，由于需要STM32F1基礎才能入門使用，所以我們安排在后面第十章給大家講解。本小節，我們主要講解STM32Cube固件包的結構。
解壓STM32CubeH7固件包后，我們看看其目錄結構，如圖7.2.2.1所示。
圖7.2.2.1 STM32CubeH7固件包的目錄結構
下面對STM32CubeH7固件包進行簡要介紹。對于Documentation文件夾，里面是一個STM32CubeH7英文說明文檔，這里我們就不做過多解釋。接下來我們通過幾個表格依次來介紹一下STM32CubeH7中幾個關鍵的文件夾。
（1）Drivers文件夾
Drivers文件夾包含BSP，CMSIS和STM32H7xx_HAL_Driver三個子文件夾。三個子文件夾具體說明請參考下表7.2.2.1：
表7.2.2.1 Drivers文件夾介紹
（2）Middlewares文件夾
該文件夾下面有ST和Third_Party 2個子文件夾。ST文件夾下面存放的是STM32相關的一些文件，包括STemWin和USB庫等。Third_Party文件夾是第三方中間件，這些中間價都是非常成熟的開源解決方案。具體說明請見下表7.2.2.2：
表7.2.2.2 Middlewares文件夾介紹
（3）Projects文件夾
該文件夾存放的是ST官方的開發板的適配例程，每個文件夾對應一個ST官方的Demo板，根據型號的不同提供MDK和IAR等類型的例程。里面有很多實例，讀者可以根據自己的需要來作為參考。比如我們要查看STM32H750相關工程，所以我們直接打開子文件夾STM32H750B-DK即可。里面有很多實例，我們都可以用來參考。這里大家注意，每個工程下面都有一個MDK-ARM子文件夾，該子文件夾內部會有名稱為Project.uvprojx的工程文件，我們只需要雙擊它就可在MDK中打開工程。
（4）Utilities文件夾
該文件夾是一些公用組件，也是主要為ST官方的Demo板提供的，在我們的例程中使用得不多。有興趣的同學可以深入研究一下，這里我們不做過多介紹。
（5）其它幾個文件
文件夾中還有幾個單獨的文件，用于聲明軟件版本或者版權信息，我們使用ST的芯片已經默認得到這個軟件的版權使用授權，可以簡單了解一下各文件的內容，實際項目中我們一般不添加。
License.md：用于聲明軟件版權信息的文件。
package.xml：描述固件包版本信息的文件。
Release_Notes.html：超文本文件，用瀏覽器打開可知它是對固件包的補充描述和固件版本更新的記錄說明。
7.2.3 CMSIS文件夾關鍵文件
上一節中我們對STM32cube固件包的主要目錄結構做了分析。這一小節在上一小節的基礎上，我們來分析一下CMSIS文件夾：由命名可知該文件夾和7.1.1小節中提到的CMSIS標準是一致的，CMSIS為軟件包的內容制定了標準，包括文件目錄的命名和內容構成，CMSIS版本5.7.0的規定軟件包目錄如表7.2.3.1所示：
表7.2.3.1 CMSIS v5.7.0的文件夾規范
知道了CMSIS規定的組件及其文件目錄的大概內容后，我們再來看看ST提供的CMSIS文件夾，如上節提到的，它的位置是“STM32Cube_FW_H7_V1.6.0\Drivers\CMSIS”。打開文件夾內容如圖7.2.3.1所示，可以發現它的目錄結構完全按照CMSIS標準執行，僅僅是作了部分刪減。
圖7.2.3.1 STM32CubeH7固件包的CMSIS文件夾
CMSIS文件夾中的Device和Include這兩個文件夾中的文件是我們工程中最常用到的。下面對這兩個文件夾作簡單的介紹：
（1）Device文件夾
Device文件夾關鍵文件介紹如下表7.2.3.1所示：
表7.2.3.1 Device文件夾關鍵文件介紹
表7.1.2.1列出的文件都是正式工程中必須的文件。固件包的CMSIS文件包括了所有STM32H7芯片型號的文件，而我們只用到STM32H750系列，所以只是挑我們用到的系列文件來講。
（2）Include文件夾
Include文件夾存放了符合CMSIS標準的 Cortex-M 內核頭文件。 想要深入學習內核的朋友可以配合內核相關的手冊去學習。對于STM32H7的工程，我們只要把我們需要的添加到工程即可，需要的頭文件有：cmsis_armcc.h、cmsis_armclang.h、cmsis_compiler.h、cmsis_version.h、core_cm7.h和mpu_armv7.h。這幾個頭文件，對比起來，我們會比較多接觸的是core_cm7.h。
core_cm7.h是內核底層的文件，由ARM公司提供，包含一些AMR內核指令，如軟件復位，開關中斷等功能。今后在需要的例程再去講解其程序，現在之所以提到，是因為它包含了一個重要的頭文件stdint.h。
7.2.4 stdint.h簡介
stdint.h是從c99中引進的一個標準C庫的文件。在2000年3月，ANSI 采納了 C99 標準。ANSI C被幾乎所有廣泛使用的編譯器（如：MDK、IAR）支持。多數C代碼是在ANSI C基礎上寫的。任何僅僅使用標準C并且沒有和任何硬件有依賴的代碼實際上能保證在任何平臺上用遵循C標準的編譯器編譯成功。就是說這套標準不依賴硬件，獨立于任何硬件，可以跨平臺。
stdint.h可以在MDK安裝目錄下找到，如MDK5安裝在C盤時，可以在路徑：C:\Keil_v5\ARM\ARMCC\include找到。stdint.h的作用就是提供了類型定義，其部分類型定義代碼如下：
在今后的程序，我們都將會使用這些類型，比如：uint32_t（無符號整型）、int16_t等。
7.3 HAL庫框架結構
這一節我們將簡要分析一下HAL驅動文件夾下的驅動文件，
7.3.1 HAL庫文件夾結構
HAL庫頭文件和源文件在STM32Cube固件包的STM32H7xx_HAL_Driver文件夾中，打開該文件夾，如圖7.3.1.1所示。
圖7.3.1.1 STM32H7xx_HAL_Driver文件夾目錄結構
STM32H7xx_HAL_Driver文件夾下的Src（Source的簡寫）文件夾存放是所有外設的驅動程序源碼，Inc（Include的簡寫）文件夾存放的是對應源碼的頭文件。Release_Notes.html是HAL庫的版本更新信息。最后三個是庫的用戶手冊，這個需要可以去熟悉一下，查閱起來很方便。
打開Src和Inc文件夾，大家會發現基本都是stm32h7xx_hal_和stm32h7xx_ll_開頭的.c和
.h文件。剛學HAL庫的朋友可能會說，stm32h7xx_hal_開頭的是HAL庫，我能理解。那么stm32h7xx_ll_開頭的文件又是什么？stm32h7xx_ll_開頭的文件是前面介紹過的LL庫的文件。
7.3.2 HAL庫文件介紹
HAL庫關鍵文件介紹如下表7.3.2.1所示，表中ppp代表任意外設。
表7.3.2.1 HAL庫關鍵文件介紹
以上是HAL庫最常見的文件的列表，在Src/Inc下面還有Legacy文件夾，用于特殊外設的補充說明。我們的教程中用到的比較少，這里不展開描述。
不止文件命名有一定規則，stm32h7xx_hal_ppp (c/h)中的函數和變量命名也嚴格按照命名規則，如表7.3.2.2所示的命名規則在大部分情況下都是正確的：
表7.3.2.2 HAL庫函數、變量命名規則
對于HAL的API函數，常見的有以下幾種：
?初始化/反初始化函數:HAL_PPP_Init()， HAL_PPP_DeInit()
?外設讀寫函數:HAL_PPP_Read()，HAL_PPP_Write()，HAL_PPP_Transmit()，HAL_PPP_Receive()
?控制函數:HAL_PPP_Set ()，HAL_PPP_Get ()
?狀態和錯誤:HAL_PPP_GetState ()， HAL_PPP_GetError ()
HAL庫封裝的很多函數都是通過定義好的結構體將參數一次性傳給所需函數，參數也有一定的規律，主要有以下三種：
? 配置和初始化用的結構體
一般為PPP_InitTypeDef或PPP_ ConfTypeDef的結構體類型，根據外設的寄存器設計成易于理解和記憶的結構體成員。
? 特殊處理的結構體
專為不同外設而設置的，帶有“Process”的字樣，實現一些特異化的中間處理操作等。
? 外設句柄結構體
HAL驅動的重要參數，可以同時定義多個句柄結構以支持多外設多模式。HAL驅動的操作結果也可以通過這個句柄獲得。有些HAL驅動的頭文件中還定義了一些跟這個句柄相關的一些外設操作。如用外設結構體句柄與HAL定義的一些宏操作配合，即可實現一些常用的寄存器位操作。
表7.3.2.3 HAL庫驅動部分與外設句柄相關的宏
但對于SYSTICK/NVIC/RCC/FLASH/ GPIO這些內核外設或共享資源，不使用PPP_HandleTypedef這類外設句柄進行控制，如：HAL_GPIO_Init() 只需要初始化的GPIO編號和具體的初始化參數。
HAL_StatusTypeDef HAL_GPIO_Init (GPIO_TypeDef* GPIOx, GPIO_InitTypeDef Init)
{
/ GPIO 初始化程序…… */
}
最后要分享的是HAL庫的回調函數，這部分允許用戶重定義，并在其中實現用戶自定義的功能，也是我們使用HAL庫的最常用的接口之一：
表7.3.2.4 HAL庫驅動中常用的回調函數接口
至此，我們大概對HAL庫驅動文件的一些通用格式和命名規則有了初步印象，記住這些規則可以幫助我們快速對HAL庫的驅動進行歸類和判定這些驅動函數的用法。
ST官方給我們提供了快速查找API函數的幫助文檔。在路徑“STM32Cube_FW_H7 _V1.6.0\Drivers\STM32H7xx_HAL_Driver”下有幾個chm格式的文檔，根據我們開發板主控芯片STM32H750VBT6我們沒有找到直接可用的，但可以查看型號接近的：STM32H753xx_User _Manual.chm。雙擊打開后，可以看到左邊目錄下有四個主題，我們來查看Modules。以外設GPIO為例，講一下怎么使用這個文檔。點擊GPIO外設的主題下的IO operation functions /functions看看里面的API函數接口描述，如圖7.3.2.1所示。
圖7.3.2.1 文檔的API函數描述
這個文檔提供的信息很全，不看源碼都可以直接使用它來編寫代碼，還給我們指示源碼位置，非常方便。大家多翻一下其他主題了解一下文檔的信息結構，很容易使用。
下面舉個例子，比如我們要讓PB4輸出高電平。先看函數功能，HAL_GPIO_WritePin函數就是我們的GPIO口輸出設置函數。
函數有三個形參：
第一個形參是GPIO_TypeDef *GPIOx，形參描述說：x可以是A到K之間任何一個，而我們是PB4引腳，所以第一個形參確認是GPIOB。
第二個形參是uint16_t GPIO_Pin，看形參描述：該參數可以是GPIO_PIN_x，x可以1到15，那么我們第二個形參就是GPIO_PIN_4。
第三個形參是GPIO_PinState PinState，看形參描述：該參數可以是枚舉里的兩個數，一個是GPIO_PIN_RESET：表示該位清零，另一個是GPIO_PIN_SET：表示設置該位，即置1，我們要輸出1，所以要置1該位，那么我們第三個形參就是GPIO_PIN_SET。
最后看函數返回值：None，沒有返回值。
所以最后得出我們要調用的函數是：
HAL_GPIO_WritePin(GPIOB, GPIO_PIN_4, GPIO_PIN_SET);
文檔的使用就講到這。
7.4 如何使用HAL庫
我們要先知道STM32芯片的某個外設的性能和工作模式，才能借助HAL庫來幫助我們編程，甚至修改HAL庫來適配我們的開發項目。HAL庫的API雖多，但是查找和使用有規律可循，只要學會其中一個，其他的外設就是類似的，只是添加自己的特性的API而已。
7.4.1 學會用HAL庫組織開發工具鏈
需要按照芯片使用手冊建議的步驟去配置芯片。HAL庫驅動提供了芯片的驅動接口，但我們需要強調一個概念是使用HAL庫的開發是對芯片功能的開發，而不是開發這個庫，也不是由這個庫能就直接開發。如果我們對芯片的功能不作了解的話，仍然不知道按照怎樣的步驟和尋找哪些可用的接口去實現想要實現的功能。
ST提供芯片使用手冊《STM32H7xx參考手冊_V7（英文版）.pdf》告訴我們使用某一外設功能時如何具體地去操作每一個用到的寄存器的細節，后面我們的例程講解過程也會結合這個手冊來分析配置過程。
嵌入式的軟件開發流程總遵循以下步驟：組織工具鏈、編寫代碼、生成可執行文件、燒錄到芯片、芯片根據內部指令執行我們編程生成的可執行代碼。
在HAL庫學習前期，建議以模仿和操作體驗為基礎，通過例程來學習如何配置和驅動外設。下面根據我們后續要學習的工程梳理出來的基于CMSIS的一個HAL庫應用程序文件結構，幫助讀者學習和體會這些文件的組成意義，如下表7.4.1.1所示。
表7.4.1.1基于CMSIS應用程序文件描述
把這些文件組織起來的方法，我們會在后續章節新建工程中介紹，這只提前告訴一下大家組成我們需要的編譯工具鏈大概需要哪些文件。
7.4.2 HAL庫的用戶配置文件
stm32h7xx_hal_conf.h用于裁剪HAL庫和定義一些變量，官方沒有直接提供這個文件，但在STM32Cube_FW_H7_V1.6.0\Drivers\STM32H7xx_HAL_Driver\Inc這個路徑下提供了一個模版文件《stm32h7xx_hal_conf_template.h》，我們可以直接復制這個文件重命名為stm32h7xx_ hal_conf.h，做一些簡單的修改即可，也可以從在官方的例程中直接復制過來。我們一般都直接從官方的模板例程中直接復制過來即可。因為我們的芯片是STM32H750系列，所以選擇的路徑是：STM32Cube_FW_H7_V1.6.0\Projects\STM32H750B-DK\Templates\Template_Project\ Inc。
（1）stm32h7xx_hal_conf.h文件里面的內容不多，對我們來說最重要的是HSE_VALUE這個參數，這個參數表示我們的外部高速晶振的頻率。這個參數請務必根據我們板子外部焊接的晶振頻率來修改，官方默認是25M。正點原子STM32H750MINI PRO開發板外部高速晶振的頻率是8MHZ。注意事項：我們要修改這個參數，源碼在99行，具體修改如下：
（2）還有一個參數就是外部低速晶振頻率，這個官方默認是32.768KHZ，我們開發板的低速晶振也是這個頻率，所以不用修改，源碼在128行。
#if !defined (LSE_VALUE)#define LSE_VALUE ((uint32_t)32768) /* 外部低速振蕩器的值，單位HZ */ #endif /* LSE_VALUE */其他源碼都可以不作修改，按照默認的配置即可。下面我們再來了解一下其他程序。
（3）用戶配置文件可以用來選擇使能何種外設，源碼配置在37行到90行，代碼如下。
這是一個條件編譯符，與#endif配合使用。這里的要表達的意思是，只要工程中定義了HAL_GPIO_MODULE_ENABLED這個宏，#ifdef到#endif之間的程序（119行到550行）就會參與編譯，否則不編譯。所以只要我們屏蔽了stm32h7xx_hal_conf.h文件53行的宏，GPIO的驅動代碼就不被編譯。也就起到選擇使能何種外設的功能，其他外設同理。
可以看官方的示范例程，就是通過屏蔽外設的宏的方法來選擇使能何種外設。好處就是編譯時間會變短，因為屏蔽了沒有用的程序，編譯時間自然就短了。正點原子的例程選擇另外一中方法，就是工程中只保留需要的stm32h7xx_hal_ppp.c，不需要的不添加到工程里，這樣編譯時間就不會太長。
（4）大家看到stm32h7xx_hal_conf.h文件的159行。
#define TICK_INT_PRIORITY ((uint32_t)0x0F) /*!< tick interrupt priority */
宏定義TICK_INT_PRIORITY是滴答定時器的優先級。這個優先級很重要，因為如果其它的外設驅動程序的延時是通過滴答定時器提供的時間基準，來實現延時的話，又由于實現方式是滴答定時器對寄存器進行計數，所以當我們在其它中斷服務程序里調用基于此時間基準的延遲函數 HAL_Delay，那么假如該中斷的優先級高于滴答定時器的優先級，就會導致滴答定時器中斷服務函數一直得不到運行，從而程序卡死在這里。所以滴答定時器的中斷優先級一定要比這些中斷高。
請注意這個時間基準可以是滴答定時器提供，也可以是其他的定時器，默認是用滴答定時器。
（5）下面說一下關于斷言這個功能，這個功能用來判斷函數的形參是否有效，在HAL庫的API里面有用到。這個功能的使能開關代碼是一個宏，在源碼的180行，默認是關閉的，代碼如下。
也是通過條件編譯符來選擇對應的功能。當用戶自己需要使用斷言功能，怎么做呢？首先需要定義宏USE_FULL_ASSERT來使能斷言功能，即把源碼的180行的注釋去掉即可。然后看到源碼423行的assert_failed（）這個函數。其實這個函數是需要我們自己實現的，我們把這個函數定義在正點原子提供的sys.c文件里面。后面再跟大家講sys.c文件，現在我們把assert_failed（）這個函數拿出來給大家先講，assert_failed（）函數的定義在sys.c的176行到190行，具體如下：
#ifdef USE_FULL_ASSERT/*** @brief 當編譯提示出錯的時候此函數用來報告錯誤的文件和所在行* @param file：指向源文件* line：指向在文件中的行數* @retval 無*/ void assert_failed(uint8_t* file, uint32_t line) { while (1){} } #endif可以看到這個函數里面沒有實現如何功能，就是一個什么不做的死循環，具體功能請根據自己的需求去實現。file是指向源文件的指針，line是指向源文件的行數。__FILE__是表示源文件名，__LINE__是表示在源文件中的行數。比如我們可以實現打印出這個錯誤的兩個信息等等。
總的來說斷言功能就是，在HAL庫中，如果定義了USE_FULL_ASSERT這個宏，那么所有的HAL庫函數將會檢查函數的形參是否正確。如果錯誤將會調用assert_failed（）這個函數，這個函數我們默認是個什么事不做的死循環，用戶請根據自己的需求設計功能。使用斷言功能將會增加了代碼量，減慢運行速度等，所以一般只是在調試的時候用，正式發布的軟件是不推薦的。
7.4.3 stm32h7xx_hal.c文件
這個文件內容比較多，包括HAL庫的初始化、系統滴答、基準電壓配置、IO補償、低功耗、EXTI配置等都集合在這個文件里面。下面我們對該文件進行講解。
源碼在134行到172行，簡化函數如下：
該函數是HAL庫的初始化函數，在程序中必須優先調用，其主要實現如下功能：
1）設置NVIC優先級分組為4。
2）配置滴答定時器每1ms產生一個中斷。
3）在這個階段，系統時鐘還沒有配置好，因此系統還是默認使用內部高速時鐘源HSI在跑程序。對于H7來說，HSI的主頻是64MHZ。所以如果用戶不配置系統時鐘的話，那么系統將會使用HIS作為系統時鐘源。
4）調用HAL_MspInit函數初始化底層硬件，HAL_MspInit函數在stm32h7xx_hal.c文件里面做了弱定義。關于弱定義這個概念，后面會有講解，現在不理解沒關系。正點原子的HAL庫例程是沒有使用到這個函數去初始化底層硬件，而是單獨調用需要用到的硬件初始化函數。用戶可以根據自己的需求選擇是否重新定義該函數來初始化自己的硬件。
注意事項：
為了方便和兼容性，正點原子的HAL庫例程中的中斷優先級分組設置為分組2，即把源碼的145行改為如下代碼：
HAL_NVIC_SetPriorityGrouping(NVIC_PRIORITYGROUP_2);
中斷優先級分組為2，也就是2位搶占優先級，2位響應優先級，搶占優先級和響應優先級的值的范圍均為0-3。
2. HAL_DeInit ()函數
源碼在179行到214行，函數如下：
HAL_StatusTypeDef HAL_DeInit(void) {/* 復位所有外設 */__HAL_RCC_AHB3_FORCE_RESET();__HAL_RCC_AHB3_RELEASE_RESET();__HAL_RCC_AHB1_FORCE_RESET();__HAL_RCC_AHB1_RELEASE_RESET();__HAL_RCC_AHB2_FORCE_RESET();__HAL_RCC_AHB2_RELEASE_RESET();__HAL_RCC_AHB4_FORCE_RESET();__HAL_RCC_AHB4_RELEASE_RESET();__HAL_RCC_APB3_FORCE_RESET();__HAL_RCC_APB3_RELEASE_RESET();__HAL_RCC_APB1L_FORCE_RESET();__HAL_RCC_APB1L_RELEASE_RESET();__HAL_RCC_APB1H_FORCE_RESET();__HAL_RCC_APB1H_RELEASE_RESET();__HAL_RCC_APB2_FORCE_RESET();__HAL_RCC_APB2_RELEASE_RESET();__HAL_RCC_APB4_FORCE_RESET();__HAL_RCC_APB4_RELEASE_RESET();/* 對底層硬件初始化進行復位 */HAL_MspDeInit();/* 返回函數狀態 */return HAL_OK; }該函數取消初始化HAL庫的公共部分，并且停止systick，是一個可選的函數。該函數做了一下的事：
1）復位了AHB1、AHB2、AHB3、AHB4、APB1L、APB1H、APB2、APB3、APB4的時鐘。
2）調用HAL_MspDeInit函數，對底層硬件初始化進行復位。HAL_MspDeInit也在stm32h7xx _hal.c文件里面做了弱定義，并且與HAL_MspInit函數是一對存在。HAL_MspInit函數負責對底層硬件初始化，HAL_MspDeInit函數則是對底層硬件初始化進行復位。這兩個函數都是需要用戶根據自己的需求去實現功能，也可以不使用。
3. HAL_InitTick ()函數
源碼在254行到302行，簡化函數如下：
__weak HAL_StatusTypeDef HAL_InitTick(uint32_t TickPriority) {/* uwTickFreq是個枚舉類型，如果檢測到uwTickFreq為零，則返回 */if((uint32_t)uwTickFreq == 0UL){return HAL_ERROR;}/* 配置滴答定時器1ms產生一次中斷 */if (HAL_SYSTICK_Config(SystemCoreClock /(1000UL / (uint32_t)uwTickFreq))> 0U){return HAL_ERROR;} #endif/* 配置滴答定時器中斷優先級 */if (TickPriority < (1UL << __NVIC_PRIO_BITS)){HAL_NVIC_SetPriority(SysTick_IRQn, TickPriority, 0U);uwTickPrio = TickPriority;}else{return HAL_ERROR;}/* 返回函數狀態 */return HAL_OK; }該函數用于初始化滴答定時器的時鐘基準，主要功能如下：
1）配置滴答定時器1ms產生一次中斷。
2）配置滴答定時器的中斷優先級。
3）該函數是__weak定義的“弱函數”，用戶可以重新定義該函數。
該函數可以通過HAL_Init()或者HAL_RCC_ClockConfig()重置時鐘。在默認情況下，滴答定時器是時間基準的來源。如果其他中斷服務函數調用了HAL_Delay()，必須小心，滴答定時器中斷必須具有比調用了HAL_Delay()函數的其他中斷服務函數的優先級高(數值較低)，否則會導致滴答定時器中斷服務函數一直得不到執行，從而卡死在這里。
4. 滴答定時器相關的函數
源碼在331行到463行，相關函數如下：
/* 該函數在滴答定時器時鐘中斷服務函數中被調用，一般滴答定時器1ms中斷一次，
所以函數每1ms讓全局變量uwTick計數值加1 */
這些函數不是很難，請參照注釋理解。注意：如果函數被前綴__weak定義，則用戶可以重新定義該函數。更多的內容可以參考8.1.5小節。
5. HAL庫版本相關的函數
源碼在465行到517行，相關函數聲明如下：
uint32_t HAL_GetHalVersion(void); /* 獲取HAL庫驅動程序版本 */ uint32_t HAL_GetREVID(void); /* 獲取設備修訂標識符 */ uint32_t HAL_GetDEVID(void); /* 獲取設備標識符 */ uint32_t HAL_GetUIDw0(void); /* 獲取唯一設備標識符的第一個字 */ uint32_t HAL_GetUIDw1(void); /* 獲取唯一設備標識符的第二個字 */ uint32_t HAL_GetUIDw2(void); /* 獲取唯一設備標識符的第三個字 */這些函數了解一下就好了，用得不多。
6. 芯片內部電壓基準相關函數
源碼在519行到602行，函數聲明如下：
HAL_SYSCFG_VREFBUF_VoltageScalingConfig函數用于配置芯片內部電壓基準大小，形參有四個值可以選擇：
1）當形參為SYSCFG_VREFBUF_VOLTAGE_SCALE0時，
電壓輸出基準為2.048V，條件是VDDA >= 2.4V。
2）當形參為SYSCFG_VREFBUF_VOLTAGE_SCALE1時，
電壓輸出基準為2.5V，條件是VDDA >= 2.8V。
3）當形參為SYSCFG_VREFBUF_VOLTAGE_SCALE2時，
電壓輸出基準為1.5V，條件是VDDA >= 1.8V。
4）當形參為SYSCFG_VREFBUF_VOLTAGE_SCALE3時，
電壓輸出基準為1.8V，條件是VDDA >= 2.1V。
HAL_SYSCFG_VREFBUF_HighImpedanceConfig函數用于配置芯片內部電壓是否與VREF+引腳連接，即是否選擇高阻抗模式，有兩個形參選擇：
1）當形參為SYSCFG_VREFBUF_HIGH_IMPEDANCE_DISABLE，表示導通。
2）當形參為SYSCFG_VREFBUF_HIGH_IMPEDANCE_ENABLE，表示高阻抗，即不導通。
HAL_SYSCFG_VREFBUF_TrimmingConfig函數用于調整校準內部電壓基準。
HAL_SYSCFG_EnableVREFBUF函數用于使能內部電壓基準參考。
HAL_SYSCFG_DisableVREFBUF函數用于禁止內部電壓基準參考。
7. 以太網PHY接口選擇函數
源碼在605行到619行，函數聲明如下：
void HAL_SYSCFG_ETHInterfaceSelect(uint32_t SYSCFG_ETHInterface);
該函數用于以太網PHY接口的選擇，可以是MII或RMII接口。
8. HAL_SYSCFG_AnalogSwitchConfig()函數
源碼在622行到650行，函數聲明如下：
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。該函數的作用就是切換這些可選的引腳。關于這個不理解，請參考圖7.4.3.1。該函數操作了SYSCFG_PMCR寄存器，關于該寄存器請查閱參考手冊。
圖7.4.3.1 連接到ADC輸入的模擬輸入
9. Booster的使能和禁止函數（用于ADC）
源碼在653行到676行，函數聲明如下：
void HAL_SYSCFG_EnableBOOST(void); /* 使能Booster /
void HAL_SYSCFG_DisableBOOST(void); / 禁止Booster */
如果使能Booster，當供電電壓低于2.7V時，能夠減少模擬開關總的諧波失真。這樣就使得模擬開關的性能和供電正常的情況時一樣，能夠正常工作。
10. HAL_SYSCFG_CM7BootAddConfig()函數
源碼在680行到712行，函數如下：
void HAL_SYSCFG_CM7BootAddConfig(uint32_t BootRegister, uint32_t BootAddress)
該函數用于配置程序啟動模式，BOOT=0或者BOOT=1，來選擇啟動地址。詳細的內容請看第九章的9.1小節。
11. IO補償、低功耗、EXTI等相關函數
IO補償、低功耗、EXTI等相關函數，這里先不進行講解了，后面用到再進行說明。
7.4.4 HAL庫中斷處理
中斷是STM32開發的一個很重要的概念，這里我們可以簡單地理解為：STM32暫停了當前手中的事并優先去處理更重要的事務。而這些“更重要的事務”是由軟件開發人員在軟件中定義的。關于STM32中斷的概念，我們會在中斷例程的講解再跟大家詳細介紹。
由于HAL庫中斷處理的邏輯比較統一，我們將這個處理過程抽象為圖7.4.4.1所表示的業務邏輯：
圖7.4.4.1 HAL驅動中斷處理流程
結合以前的HAL庫文件介紹章節，以上的流程大概就是：設置外設的控制句柄結構體PPP_HandleType和初始化PPP_InitType結構體的參數，然后調用HAL庫對應這個驅動的初始化HAL_PPP_Init()，由于這個API中有針對外設初始化細節的接口Hal_PPP_Mspinit()，我們需要重新實現這個函數并完成外設時鐘、IO等細節差異的設置， 完成各細節處理后，使用HAL_NVIC_SetPriority()、HAL_NVIC_EnableIRQ()來使能我們的外設中斷；定義中斷處理函數PPP_IRQHandler，并在中斷函數中調用HAL_ppp_function_IRQHandler()來判斷和處理中斷標記； HAL庫中斷處理完成后，根據對應中的調用我們需要自定義的中斷回調接口HAL_ PPP_ProcessCpltCallback();如串口接收函數HAL_UART_RxCpltCallback()，我們在這個函數中實現我們對串口接收數據想做的處理；中斷響應處理完成后，stm32芯片繼續順序執行我們定義的主程序功能，按照以上處理的標準流程完成了一次中斷響應。
7.4.5 正點原子對HAL庫用法的個性化修改
前面按ST官方建議的HAL庫的使用方法給介紹了一個HAL庫。
1、將中斷處理函數獨立到每個外設中，便于獨立驅動；同類型的外設驅動處理函數不使用HAL回調函數接口處理操作而直接在中斷函數中處理判斷對應中斷。
2、我們把原來的中斷分組進行了修改，由搶占式無子優先級改為中斷分組2；便于管理同類外設的優先級響應。
3、在很多芯片的初始化過程中，我們使用到了delay_ms()、delay_us()等函數進行初始化，使用的是Systick作的精準延時，而HAL庫默認也使用Systick作延時處理，為解決這種沖突和兼容我們大部分的驅動代碼，我們在例程中使用delay.c中的延時函數取代Hal_Delay();取消原來HAL庫的Systick延時設置。
7.5 HAL庫使用注意事項
本小節根據經驗跟大家講述一些關于HAL庫使用的注意事項，供讀者參考。
1、即使我們已經在使用庫函數作為開發工具了，我們可以忽略很多芯片的硬件外設使用上的細節，但當發生問題時，我們仍需要回歸到芯片使用手冊查看當前操作是否違規或缺漏。
2、使用HAL庫和其它第三方的庫開發類似，把我們需要編寫的軟件和第三方的庫分開成相互獨立的文件，開發過程中我們盡量不去修改第三方的軟件源碼，需要修改的部分盡量在自己的代碼中實現；這樣一旦我們需要更新第三方庫時，我們原來編寫的功能也能很快地匹配新的庫去執行功能。
3、即使HAL庫目前較以前已經相對更完善了，但它仍無法覆蓋我們要想實現的所有細節功能，甚至可能存在錯誤，我們要有懷疑精神，辯證地去使用好這個工具；如我們在PWM一節編碼時發現HAL庫中有個宏定義TIM_RESET_CAPTUREPOLARITY括號不匹配導致編譯報錯，這時我們不得不修改一下HAL庫的源碼了。
4、注意HAL庫的執行效率。由于HAL庫的驅動對相同外設大多是可重入的，在執行HAL驅動的API函數的效率沒有直接寄存器操作來得高，如果在對時序要求比較嚴苛的代碼，建議使用簡潔的寄存器操作代替。
5、我們在例程中使用delay.c中的延時函數取代Hal_Delay();取消原來HAL庫的Systick延時設置；但這會有一個問題：原來HAL庫的超時處理機制不再適用，所以對于設置了超時的函數，可能會導致停留在這個函數的處理中，無法按正常的超時退出。
總結
以上是生活随笔為你收集整理的【正点原子STM32连载】第七章 认识HAL库 摘自【正点原子】MiniPro STM32H750 开发指南_V1.1的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： Halcon：手眼标定——眼在手外与眼在
- 下一篇： 企业全面运营管理沙盘模拟心得_企业沙盘模