掌握HAL API中面向對象設計的思想

1. 初識HAL

ST 為開發(fā)者提供了三種的開發(fā)庫：

1. 標準外設庫（Standard Peripheral Library, SPL庫）
2. 硬件抽象層庫（Hardware Abstraction Layer，HAL庫）
3. 底層庫（Low-Layer，底層庫）

其中，ST CubeMX軟件支持STM32全線產品的HAL和LL庫；SPL已經停更，部分芯片如STM32F7xx沒有推出SPL庫。

相比標準外設庫，STM32 HAL庫擁有更好的抽象整合水平，HAL API（HAL Application Programming Interface，HAL應用程序接口）集中關注各個外設（Peripheral）的公共函數功能，通過定義一套通用的、用戶友好的API函數接口，支持不同STM32系列產品之間的輕松移植。

以點亮LED的工程舉例。

1.首先配置MDK的代碼補全

Edit Configuration Text Completion Symbols after 3 Characters。

2.代碼補全效果。

HAL庫函數都以HAL作為開頭。打開代碼自動補全后，輸入HAL_GPIO即可彈出一系列支持的函數，如下圖的Init（初始化）、LockPin（鎖引腳）、ReadPin（讀引腳）、TogglePin（翻轉引腳）等。

3.HAL支持哪些函數？

如下圖所示，點擊MDK左側工程欄下方的Functions，點開對應的hal_xx.c文件，即可顯示出所有的HAL庫函數。

ST的HAL庫通過高度抽象化，使用統一的HAL API對硬件進行操作。無論是使用STM32F1系列、L4系列、F7系列、H7系列等，對GPIO的初始化、讀、寫、翻轉操作都是如下的統一接口，極大地方便了開發(fā)者將相同的代碼移植到不同的ST系列芯片中。

• void HAL_GPIO_Init(GPIO_TypeDef *GPIOx, GPIO_InitTypeDef *GPIO_Init)
• GPIO_PinState HAL_GPIO_ReadPin(GPIO_TypeDef* GPIOx, uint16_t GPIO_Pin)
• void HAL_GPIO_WritePin(GPIO_TypeDef* GPIOx, uint16_t GPIO_Pin, GPIO_PinState PinState)
• void HAL_GPIO_TogglePin(GPIO_TypeDef* GPIOx, uint16_t GPIO_Pin)

CubeMX通過圖形化界面操作，配置各個引腳、外設的工作狀態(tài)，自動生成驅動初始化代碼，方便用戶快速進行底層功能部署，開發(fā)者只關注CubeMX圖形化界面的配置，可以不關注寫底層硬件寄存器，通過調用統一的HAL API實現外設各種功能，這是HAL的一個典型特點。

2. STM32 Manual

關于STM32L4系列的手冊，可以在https://www.st.com/zh/microcontrollers-microprocessors/stm32l4-series.html下載相關手冊。

ST系列常見文檔的命名規(guī)則如下：

1.AN， Application Note ，應用手冊。一般是一些相對復雜、精細、精巧的應用原理與結果介紹，閱讀門檻較高，建議熟悉芯片、熟悉嵌入式系統后，再根據具體開發(fā)工作需求進行查找與閱讀。
2.DS， Data Sheet ，規(guī)格書。芯片手冊，說明芯片容量、芯片時序、芯片封裝等情況的文檔，一般用于硬件選型階段。
3.UM， User Manual ，用戶手冊，為開發(fā)者提供HAL庫使用說明、硬件使用說明等情況的文檔，開發(fā)階段可以作為參考書。瀏覽https://www.st.com/zh/embedded-software/stm32cubel4.html可以找到STM32L4系列的HAL庫UM手冊。本課程要求下載UM1884 Description of STM32L4/L4+ HAL and low-layer drivers.pdf手冊。建議將該手冊作為參考書，有需要時再查閱，不要通讀，以后該文件簡稱為UM1884.pdf文件。
RM， Reference Manual ，參考手冊。說明芯片內部寄存器如何配置的手冊，本課程要求下載RM0394_STM32L41xxx/42xxx/43xxx/44xxx/45xxx/46xxx advanced Arm?-based 32-bit MCUs.pdf文件，對應例程逐步深入了解。以后該文件簡稱為RM0394.pdf。
4.PM， Programming Manual ，編程手冊，針對具體芯片，一般是RISC匯編指令的解讀，不推薦給初學者。
5.TN， Technical Note ，技術手冊，一般是一些芯片規(guī)格、封裝、PCB制版、Toolchains等軟硬件方面的雜項技術要點和進一步解讀，不推薦給初學者。

3. 熟悉GPIO HAL Driver

STM32L431RCT6芯片有GPIOA~GPIOE、GPIOH等6個IO口，其中，每個IO口都有16個引腳，從GPIOx的PIN0 ~ PIN15。

在第一個EVB MX+的GPIO例程中，我們翻轉GPIOC的引腳13，實現LED的點亮和熄滅。

HAL_GPIO_TogglePin(GPIOC, GPIO_PIN_13);

/* 其函數原型為 */
/**
  * @brief  Toggle the specified GPIO pin.
  * @param  GPIOx where x can be (A..H) to select the GPIO peripheral for STM32L4 family
  * @param  GPIO_Pin specifies the pin to be toggled.
  * @retval None
  */
void HAL_GPIO_TogglePin(GPIO_TypeDef* GPIOx, uint16_t GPIO_Pin)

我們依次認識GPIOC和GPIO_PIN_13，從HAL庫的數據結構、操作原理、STM32的GPIO結構的角度，來逐步深入了解。GPIO是最基礎的內容，掌握了GPIO的HAL操作原理，也就理解了USART、SPI、ADC、IIC等更復雜外設的HAL庫工作原理。

3.1 回顧指針

3.1.1 內存中的數據與數據類型

計算機的內存，可以簡單看作一條長街上的一行房子，每一個房子內能容納數據，并且每一個房子具有獨一無二的編號。

• 上圖中，每一個格子表示1個字節(jié)，一個字節(jié)的無符號數的表示范圍是
• 為了存儲更大的數，我們也可以將4個字節(jié)看作一個單元，在32位計算機中，4個字節(jié)即一個字word

計算機中所有的數據都必須放在內存中，不同類型的數據占用的字節(jié)數不一樣。如 int 占用 4 個字節(jié)，char 占用 1 個字節(jié)。為了正確地訪問這些數據，必須為每個字節(jié)都編上號碼，就像門牌號、身份證號一樣，每個字節(jié)的編號是唯一的，根據編號可以準確地找到某個字節(jié)。

我們將內存中字節(jié)的編號稱為地址（Address）。地址從 0 開始依次增加。對于32位環(huán)境，程序能夠使用的內存為 4GB，最小的地址為0x00000000，最大的地址為0XFFFFFFFF。

下圖是 4G 內存中每個字的編號（以十進制表示）：

舉個簡單例子：下圖表明計算機中， 5個連續(xù)的字單元中的存儲內容。

• 不得不說，如果直接通過地址編號去讀取/修改這些數據，是一件讓人為難的事情 ；
• 高級語言提供了解決方案，支持通過變量名進行訪問；
• 通過變量名來訪問變量，對于開發(fā)者非常友好。但是要時刻記住計算機硬件依然是通過地址來訪問內存單元(Hardware still accesses memory locations using addresses)。

下圖和代碼表示通過變量名訪問內存：

int a = 112, b = -1;
float c = 3.14;
int *d = &a;
float *e = &c;

在上述代碼中，變量d和e是指針，它們不是int和float類型，而分別是(int *)和(float *)類型，它們是變量，也存儲在內存中。在變量d中，可以存儲int類型變量的地址，在變量e中，可以存儲float類型變量的地址。

通過前面的圖，我們已經知道，變量a存儲在地址編號為100的格子中。如果需要將變量a的數值修改為200，則下面語句互相完全等價：

a = 200;
*d = 200; /*變量d之前的*，是指針變量的解引用操作符，derefrence,返回存儲在指針地址中的值*/
*( (int *)(100) ) = 200;

• 第三條語句是典型的C語言Cast，即類型轉換。
• 第三條語句將無符號數100強制轉換成了(int *)的指針，然后在編號為100的地址中寫入數據200。
• 但是，務必要注意，這種寫法很危險。我們在編譯程序之后，一般并不知道某個變量在內存中的存放地址，通過直接地址編號進行數據操作，很容易造成程序崩潰。
• 但是，ST HAL庫對內部寄存器操作，卻主動采用了這種看似危險的做法。后文會清晰說明原因。

3.1.2 指針是變量

假設聲明的變量被依次存放在0x20000000UL地址開始的單元格內。

unsignedint  a    = 0xFFFFFFFF; /*無符號數據，4294967295*/
signedint    b    = -1;         /*有符號數，-1*/
unsignedint  c    = 0xFFFFFFFD; /*無符號數據，4294967293*/
signedint    d    = -2;         /*有符號數，-2*/
unsignedint *pa   = &a;         /*指針變量pa指向a，即，將a的地址賦值給變量pa*/
unsignedint **ppa = &pa;        /*指針變量ppa指向pa，即，將pa的地址賦值給變量ppa*/

typedefstruct{
    unsignedint a;
    signedint b;
    unsignedint c;
    signedint   d;
}User_Typedef; /*自定義某個數據類型，將其命名為User_Typedef*/

User_Typedef data     = {0xFFFFFFFF,0xFFFFFFFF,0xFFFFFFFD,0xFFFFFFFD};
User_Typedef *pdata   = &data;  /*指針變量pdata指向data*/
User_Typedef **ppdata = &pdata; /*指針變量ppdata指向pdata*/

在C語言中，字節(jié)對齊的情況下，結構體所占用的內存是連續(xù)的，且每個成員也是連續(xù)存放的。在本例中，結構體變量data中的各個成員data.a、data.b、data.c、data.d的內存地址是連續(xù)的。因此，雖然兩段代碼表面上完全不同，但是程序編譯和運行后，數據在內存中的分布完全相同。

值得指出的是，結構體指針中，存放的數據是結構體變量第一個成員的地址。在本例中，data.a的地址，即0x20000000被賦值給了結構體指針pdata。而pdata存放在編號為0x20000010的內存地址中，所以該地址中存放的數據是0x20000000。

從上面的程序中可以看出：

• C語言是強類型語言，不僅要聲明變量，還要關注變量類型。a和b的內存地址中存放的數據其實是一樣的，但是因為類型不同，所以程序對數據的理解完全不同。
• 指針也是變量，所以也需要存儲在某個內存地址中。指針并不特殊，(Type *)類型的指針變量中，只能存儲Type類型變量的地址。此處的Type，適用于C語言的基礎類型數據、結構體、聯合體、函數等各種類型。
• 在32位環(huán)境中，一個指針變量占用4個字節(jié)的存儲空間，無論該指針是何種類型。

在第二段代碼中，可以用如下方式訪問結構體中的各個成員，第5~7行完全等價。

User_Typedef data；/*data中的成員還沒有初始化*/
User_Typedef *pdata   = &data;  /*指針變量，pdata指向data*/
User_Typedef **ppdata = &pdata; /*指針變量，ppdata指向pdata*/

data.a       = 0xFFFFFFFF;
pdata- >a     = 0xFFFFFFFF；
(*ppdata)- >a = 0xFFFFFFFF；

3.2 初識GPIOx

在GPIOC上點擊右鍵，選擇Go To Definition of 'GPIOC'

#define GPIOA               ((GPIO_TypeDef *) GPIOA_BASE)
#define GPIOB               ((GPIO_TypeDef *) GPIOB_BASE)
#define GPIOC               ((GPIO_TypeDef *) GPIOC_BASE)
#define GPIOD               ((GPIO_TypeDef *) GPIOD_BASE)
#define GPIOE               ((GPIO_TypeDef *) GPIOE_BASE)
#define GPIOH               ((GPIO_TypeDef *) GPIOH_BASE)

目前，先不管GPIO_TypeDef這種自定義的結構體中含有哪些成員，但是我們可以清楚地知道，GPIOx是一個自定義的GPIO_TypeDef *類型的指針，通過GPIOx->member的方式，可以直接訪問到各個成員。

進一步在GPIOC_BASE上點擊右鍵，依次得到：

#define GPIOA_BASE            (AHB2PERIPH_BASE + 0x0000UL)
#define GPIOB_BASE            (AHB2PERIPH_BASE + 0x0400UL)
#define GPIOC_BASE            (AHB2PERIPH_BASE + 0x0800UL)
#define GPIOD_BASE            (AHB2PERIPH_BASE + 0x0C00UL)
#define GPIOE_BASE            (AHB2PERIPH_BASE + 0x1000UL)
#define GPIOH_BASE            (AHB2PERIPH_BASE + 0x1C00UL)

#define AHB2PERIPH_BASE       (PERIPH_BASE + 0x08000000UL)

#define PERIPH_BASE           (0x40000000UL)

通過換算，GPIOA、GPIOB、GPIOC等實際上等價于：

#define GPIOA               ((GPIO_TypeDef *) (0x40800000UL))
#define GPIOB               ((GPIO_TypeDef *) (0x40800400UL))
#define GPIOC               ((GPIO_TypeDef *) (0x40800800UL))

結合C語言存儲結構體變量的特點，我們可以得出推論：以GPIOC為例，從地址0x40800800UL開始，是一段連續(xù)地址空間，這段連續(xù)的空間可以完整存儲GPIO_TypeDef類型的數據。但是，這一段連續(xù)地址空間到底占用了多少字節(jié)？我們還需要深入了解自定義結構體GPIO_TypeDef。

3.3 深入了解GPIO_TypeDef

認識GPIO_TypeDef，等于認識了ST HAL中所有外設的xxx_TypeDef。在GPIO_TypeDef上點擊右鍵，選擇Go To Definition of 'GPIO_TypeDef'，它是一個結構體，包括MODER、OTYPER等成員，每個成員都是uint32_t類型（無符號32位整型），__IO表示volatile。每個成員的作用見下圖的注釋部分，翻譯成中文分別是模式寄存器、輸出模式寄存器、輸出速度寄存器、上拉-下拉寄存器、輸入數據寄存器、輸出數據寄存器、置位-復位寄存器、鎖定配置寄存器、復用功能寄存器、Bit復位寄存器。

在RM0394.pdf的274 ~ 275頁，有GPIOx的寄存器布局圖，其中x表示A ~ E，H：

結合GPIOx的地址和寄存器布局圖，可以得到推論：

• 如果要設置GPIOx的各個引腳模式，需要向GPIOx的MODER寄存器中寫入相應數值；
• 如果要設置GPIOx的各個引腳輸出模式，需要向GPIOx的OTYPER寄存器中寫入相應數值；
• GPIOA MODER的地址是0x40800000UL，GPIOA OTYPER的地址是0x40800004UL；
• GPIOB MODER的地址是0x40800400UL，GPIOB OTYPER的地址是0x40800404UL；
• GPIOC MODER的地址是0x40800800UL，GPIOC OTYPER的地址是0x40800804UL。

顯然，對于GPIOA ~ GPIOH，所有寄存器的布局是相同的，寄存器地址依次偏移4個字節(jié)，圖示如下：

• 圖中，每個地址都是32位的，每個地址中能容納的數據也是32位。
• 向地址0x40800000UL中寫入一個32位的數據，等價于向GPIOA的MODER寄存器中寫入一個32位的數據，顯然，地址編號不如寄存器名稱方便。
• 在C語言中，字節(jié)對齊的情況下，結構體所占用的內存是連續(xù)的，且每個成員也是連續(xù)存放的。利用C語言的特性，HAL庫中聲明了一個自定義的結構體GPIO_TypeDef，該結構體的各個成員嚴格按照STM32L4xx系列的GPIOx各寄存器順序進行排序，且每個成員都能容納（存儲）一個32位的數據。
• 在STM32中，還有諸如USART、IIC、SPI、CAN、ADC等各種不同的外設，自然也就有對應的xxx_Typedef的自定義結構體類型。下圖給出了USART_TypeDef的結構體定義，我們無需查看手冊就知道在STM32處理器中，控制USART外設工作需要向CR1、CR2等系列寄存器寫入符合芯片RM手冊中規(guī)定的數據即可。USART_TypeDef的聲明如下圖所示：

3.4 進一步了解GPIOx

#define GPIOC   ((GPIO_TypeDef *) (0x40800800UL))

define是一個宏，表示GPIOC等價于((GPIO_TypeDef *) (0x40800800UL))。因此，GPIOC本質上是GPIO_TypeDef *類型的指針。

Q&A

Q1： 如何對GPIOA的MODER寄存器執(zhí)行寫操作？如何對GPIOC的OTYPER寄存器執(zhí)行寫操作？

A1： ->是C語言中的指向結構體成員運算符，用于使用指向某種結構的指針來訪問結構內的成員。使用GPIOA->MODE = 0x1234; GPIOC->OTYPER= 0x789A;即可完成GPIOA和GPIOC對應寄存器的數據寫入。

Q2： (0x40800800UL)是一個整形數據，也能轉化為指針嗎？

A2： 通過前文，已經知道GPIOx的所有寄存器在STM32的內存中，是連續(xù)存放的。而C語言的結構體在字節(jié)對齊的情況下，內部成員也是連續(xù)存放的，且結構體指針指向結構體第一個成員的地址。利用這個特點，將數據0x40800800UL強制轉換為(GPIO_TypeDef *)類型的指針，那么，從0x40800800UL到0x40800828UL地址段，每4個字節(jié)就對應GPIOx中的一個寄存器，完美構建了軟件與硬件的溝通橋梁。

Q3： 如果不用宏表示GPIOC，那么GPIOC->OTYPER = 0x1234應該用什么形式實現？

A3： ( (GPIO_TypeDef *) (0x40800800UL) )->OTYPER = 0x1234;，意味著，程序將訪問0x40800800UL開始的地址空間內的OTYPER成員，即將32位的十六進制數據0x1234寫入地址0x40800804UL。顯然，這種寫法很難看，不如GPIOC->OTYPER 直觀。

3.5 HAL API的設計

在C語言中，指針是最核心的內容，也是難點。通過前文分析，我們已經知道指針只是變量而已，并不復雜，HAL庫中所用的指針很簡單。

現在對比兩種不同方式設計的HAL_GPIO_TogglePin函數，其中，方式1是ST HAL官方庫的正確設計，方式2是不合理方案。

/* 方式1：HAL庫官方方案*/
void HAL_GPIO_TogglePin(GPIO_TypeDef* GPIOx, uint16_t GPIO_Pin)
/* 方式2：不合理方案*/    
GPIO_TypeDef HAL_GPIO_TogglePin(GPIO_TypeDef GPIOx, uint16_t GPIO_Pin)

/* 方式1：HAL庫官方方案進行函數調用*/
HAL_GPIO_TogglePin(GPIOC, GPIO_PIN_13);
/* 方式2：不合理方案進行函數調用*/
*(GPIOC) = HAL_GPIO_TogglePin(*(GPIOC), GPIO_PIN_13);

C 語言使用傳值調用方法來傳遞參數，即將形參的值復制給實參。在發(fā)生函數調用時，形參的存放地址空間來源于堆棧。

方式1：HAL庫官方方案進行函數調用：

• 第一個實參的值，GPIOC，即0x40800800UL 被復制給了形參GPIOx，占用4個字節(jié)；
• 第二個實參的值，GPIO_PIN_13，被復制給了形參GPIO_Pin，占用4個字節(jié)。
• 堆棧在形參上的開銷至少是8個字節(jié)。
• 傳遞指針GPIOC的值給了臨時變量GPIOx，臨時變量GPIOx存放的具體地址不明，但是，可直接通過GPIOx->MODE = xx的方式，即( (GPIO_TypeDef *) (0x40800800UL) )->MODE = xx，以地址訪問的形式直接修改了GPIOC MODE寄存器所對應的內存，從而成功修改寄存器的值。

方式2：不合理方案進行函數調用：

• 第一個實參的值，*GPIOC，即從0x40800800UL到0x40800828UL地址空間內的所有數據，被復制給了形參GPIOx，合計占用44字節(jié)；
• 第二個實參的值，GPIO_PIN_13，被復制給了形參GPIO_Pin，占用4個字節(jié)。
• 堆棧在形參上的開銷至少是48個字節(jié)。
• 由于GPIOx是個GPIO_TypeDef類型的臨時變量，存放的具體地址不明，即使在程序中使用GPIOx.MODE修改了GPIOx成員MODE的數值，也不會真正影響GPIOC->MODE。GPIOC->MODE表示地址0x40800800UL，而GPIOx.MODE肯定不存放在該地址，修改GPIOx.MODE中存放的數值，自然不可能影響到內存地址0x40800800UL，必須通過函數返回值進行賦值，而這又會帶來一系列堆棧開銷。

綜上，對比兩種設計方法，毫無疑問是HAL庫提供的方式1效果更加，更加高效，占用內存更少。HAL庫中，都是通過傳遞指針來進行API函數設計的。

4. 小結

1. HAL的精髓在于Abstract抽象。
2. STM32的RM、UM手冊是基礎，AN手冊是進階。
3. 指針到底是什么？指針是變量。
4. 指向int指針和指向結構體的指針的相同點在于，在32位環(huán)境中占用4個字節(jié)；不同點是存儲不同類型變量的地址。
5. HAL的GPIO_TypeDef之類的xxx_TypeDef是嚴格與RM手冊中的寄存器分布一一對應的。
6. HAL庫通過封裝xxx_TypeDef類型的指針，利用C語言的結構體實現了典型的面向對象編程的思路。