第8章 初识STM32标准库
8.1 CMSIS标准及库层次关系
在上一章中，我们构建了几个控制GPIO外设的函数，实现了函数库的雏形，但还有很多GPIO功能函数我们没有实现，而且STM32芯片不仅只有GPIO这一个外设。如果我们想要亲自完成这个函数库，工作量是非常巨大的。ST公司提供的标准软件库中包含了STM32芯片所有寄存器的控制操作，学习如何使用ST标准库，会极大地方便控制STM32芯片。
Cortex系列芯片采用的内核都是相同的，区别主要为核外的片上外设的差异，这些差异却导致软件在相同内核、不同外设的芯片上移植困难。为了解决不同的芯片厂商生产的Cortex微控制器软件的兼容性问题，ARM与芯片厂商建立了CMSIS标准（Cortex Microcontroller Software Interface Standard）。
所谓CMSIS标准，实际是新建了一个软件抽象层，见图8-1。
图8-1 CMSIS标准架构
CMSIS标准中最主要的是CMSIS核心层，它包括以下部分：
□ 内核函数层：即SIMD Cortex-M4，其中包含用于访问内核寄存器的名称、地址定义，主要由ARM公司提供。
□ 设备外设访问层：提供了片上的核外外设的地址和中断定义，主要由芯片生产商提供。
可见CMSIS层位于硬件层与操作系统或用户层之间，提供了与芯片生产商无关的硬件抽象层，可以为接口外设、实时操作系统提供简单的处理器软件接口，屏蔽了硬件差异，这对软件的移植是有极大的好处的。STM32的库就是按照CMSIS标准建立的。
8.1.1 库目录、文件简介
STM32标准库可以从秉火论坛获得。本书讲解的例程全部采用1.5.1版的库文件。以下内容结合STM32标准库文件配合阅读。
解压库文件后进入其目录：STM32F4xx_DSP_StdPeriph_Lib_V1.5.1\。
标准库各文件夹及内容说明见图8-2。
图8-2 ST标准库文件夹及说明
□ Libraries：文件夹下是驱动库的源代码及启动文件。
□ Project：文件夹下是用驱动库写的范例和工程模板。
□ Utilities：包含了基于ST官方实验板的例程，以及第三方软件库，如emwin图形软件库、Fatfs文件系统。
□ MCD-ST Liberty…：库文件的License说明。
□ Release_Notes.html：库的版本更新说明。
□ stm32f4xx_dsp_stdperiph…：库帮助文档。这是一个已经编译好的HTML文件，主要讲述如何使用驱动库来编写自己的应用程序。说得形象一点，这个HTML就是告诉我们：ST公司已经为你写好了每个外设的驱动了，想知道如何运用这些例子就来向我求助吧。目前这个帮助文档是英文的，这对很多英文不好的朋友来说是一个障碍。
在使用库开发时，我们需要把Libraries目录下的库函数文件添加到工程中，并查阅库帮助文档来了解ST提供的库函数，这个文档说明了每一个库函数的使用方法。
进入Libraries文件夹看到，关于内核与外设的库文件分别存放在CMSIS和STM32F4xx_StdPeriph_Driver文件夹中。
1. CMSIS文件夹
STM32F4xx_DSP_StdPeriph_Lib_V1.5.1\Libraries\CMSIS文件夹的内容见图8-3。
图8-3 CMSIS文件夹内容
（1）Include文件夹
在Include文件夹中包含的是位于CMSIS标准的核内设备函数层的Cortex-M核通用的头文件，它们的作用是为那些采用Cortex-M核设计SoC的芯片商设计的芯片外设提供一个进入内核的接口，其中定义了一些与内核相关的寄存器（类似我们前面介绍的stm32f4xx.h文件，但定义的是内核部分的寄存器）。这些文件在其他公司的Cortex-M系列芯片中也是相同的。至于这些功能是怎样用源码实现的，可以不用管它，只需把这些文件加进我们的工程文件即可，有兴趣的朋友可以深究。内核的寄存器说明可查阅《Cortex_m4_Technical Reference Manual》及《Cortex-M4内核参考手册》，《STM32参考手册》只包含片上外设说明，不包含内核寄存器。
我们写STM32F4的工程，必须用到其中的4个文件：core_cm4.h、core_cmFunc.h、corecmInstr.h、core_cmSimd.h，其他的文件是属于其他内核的，还有几个文件是DSP函数库使用的头文件。
core_cm4.c文件有一些与编译器相关的条件编译语句，用于屏蔽不同编译器的差异。里面包含了一些与编译器相关的信息，如：“__CC_ARM”（本书采用的RVMDK、KEIL）、“__GNUC__”（GNU编译器）、“ICC Compiler”（IAR编译器）。这些不同的编译器对于C嵌入汇编或内联函数关键字的语法不一样，这段代码统一使用“__ASM”“__INLINE”宏来定义，而在不同的编译器下，宏自动更改到相应的值，这就实现了差异屏蔽，见代码清单8-1。
代码清单8-1 core_cm4.h文件中对编译器差异的屏蔽
1 #if defined ( __CC_ARM ) /＊代码注释见core_cm4.h原文件＊/
2 /＊使用KEIL编译器的嵌入汇编和内联函数的关键字形式＊/
3 #define __ASM __asm
4 #define __INLINE __inline
5 #define __STATIC_INLINE static __inline
6 #elif defined ( __GNUC__ )
7 /＊使用GNU时的嵌入汇编和内联函数的关键字形式＊/
8 #define __ASM __asm
9 #define __INLINE inline
10 #define __STATIC_INLINE static inline
11 #elif defined ( __ICCARM__ )
12 #define __ASM __asm
13
14 #define __STATIC_INLINE static inline
15 #define __INLINE inline
16
17 #elif defined ( __TMS470__ )
18 #define __ASM __asm
19 #define __STATIC_INLINE static inline
20
21 #elif defined ( __TASKING__ )
22 #define __ASM __asm
23 #define __INLINE inline
24 #define __STATIC_INLINE static inline
25
26 #elif defined ( __CSMC__ )
27 #define __packed
28 #define __ASM _asm
29
30 #define __INLINE inline
31 #define __STATIC_INLINE static inline
32
33 #endif
较重要的是在core_cm4.c文件中包含了stdint.h这个头文件，这是一个ANSI C文件，是独立于处理器的，就像我们熟知的C语言头文件stdio.h文件一样。它位于RVMDK这个软件的安装目录下，主要作用是提供一些类型定义，见代码清单8-2。
代码清单8-2 ：stdint.c文件中的类型定义
1 /＊ exact-width signed integer types ＊/
2 typedef signed char int8_t;
3 typedef signed short int int16_t;
4 typedef signed int int32_t;
5 typedef signed __int64 int64_t;
6
7 /＊ exact-width unsigned integer types ＊/
8 typedef unsigned char uint8_t;
9 typedef unsigned short int uint16_t;
10 typedef unsigned int uint32_t;
11 typedef unsigned __int64 uint64_t;
这些新类型定义屏蔽了在不同芯片平台中出现的诸如int的大小是16位还是32位的差异。所以在我们以后的程序中，都将使用新类型，如uint8_t、uint16_t等。
在稍旧版的程序中还经常会出现如u8、u16、u32这样的类型，分别表示无符号的8位、16位、32位整型。初学者碰到这样的旧类型可能会感觉一头雾水，它们定义的位置在stm32f4xx.h文件中。建议在以后的新程序中尽量使用uint8_t、uint16_t类型的定义。
core_cm4.c与启动文件一样都是底层文件，都是由ARM公司提供的，遵守CMSIS标准，即所有CM4芯片的库都带有这个文件，使软件在不同的CM4芯片的移植工作得以简化。
（2）Device文件夹
在Device文件夹下是与具体芯片直接相关的文件，其中包含启动文件、芯片外部寄存器定义、系统时钟初始化功能等文件，这是由ST公司提供的。
system_stm32f4xx.c文件
文件目录：\Libraries\CMSIS\Device\ST\STM32F4xx\Source\Templates
这个文件包含了STM32芯片上电后初始化系统时钟、扩展外部存储器用的函数，例如前两章提到供启动文件调用的SystemInit函数，用于上电后初始化时钟，该函数的定义就存储在system_stm32f4xx.c文件中。STM32F429系列的芯片调用库的这个SystemInit函数后，系统时钟被初始化为180MHz，如果需要可以修改这个文件的内容，设置成自己所需的时钟频率。
启动文件
文件目录：Libraries\CMSIS\Device\ST\STM32F4xx\Source\Templates
在这个目录下，还有很多文件夹，如ARM、gcc_ride7、iar等，这些文件夹下包含了对应编译平台的汇编启动文件，在实际使用时要根据编译平台来选择。我们使用的MDK启动文件在“ARM”文件夹中。其中的“strartup_stm32f429_439xx.s”即为STM32F429芯片的启动文件，前面两章工程中使用的启动文件就是从这里复制过去的。如果使用其他型号的芯片，要在此处选择对应的启动文件，如STM32F446型号使用startup_stm32f446xx.s文件。
stm32f4xx.h文件
文件目录：Libraries\CMSIS\Device\ST\STM32F4xx\Include
stm32f4xx.h文件非常重要，是一个与STM32芯片底层相关的头文件。它是前两章自己定义的stm32f4xx.h文件的完整版，包含了STM32中所有的外部寄存器地址和结构体类型定义，在用到STM32标准库的地方都要包含这个头文件。
CMSIS文件夹中的主要内容就是这样，接下来我们看看STM32F4xx_StdPeriph_Driver文件夹。
2. STM32F4xx_StdPeriph_Driver文件夹
文件目录为：Libraries\STM32F4xx_StdPeriph_Driver。Libraries目录下的STM32F4xx_StdPeriph_Driver文件夹中的内容见图8-4。
图8-4 外设驱动
STM32F4xx_StdPeriph_Driver文件夹下有inc（include的缩写）与src（source的简写）这两个文件夹，这里的文件属于CMSIS之外的、芯片片上外设部分。src里面是每个设备外设的驱动源程序，inc则是相对应的外设头文件。src和inc文件夹是ST标准库的主要内容，甚至不少人直接认为ST标准库就是指这些文件，可见其重要性。
在src和inc文件夹里的就是ST公司针对每个STM32外设而编写的库函数文件，每个外设对应一个后缀名为．c和．h的文件。我们把这类外设文件统称为stm32f4xx_ppp.c或stm32f4xx_ppp.h文件，其中ppp表示外设名称。如在上一章中我们自建的stm32f4xx_gpio.c和stm32f4xx_gpio.h文件，就属于这一类。
如针对模数转换（ADC）外设，在src文件夹下有一个stm32f4xx_adc.c源文件，在inc文件夹下有一个stm32f4xx_adc.h头文件，若我们开发的工程中用到了STM32内部的ADC，则至少要把这两个文件包含到工程里，见图8-5。
图8-5 驱动的源文件和头文件
在这两个文件夹中还有一个很特别的misc.c文件，这个文件提供了外设对内核中的NVIC（中断向量控制器）的访问函数，在配置中断时，必须把这个文件添加到工程中。
3. Project文件夹
在STM32F4xx_DSP_StdPeriph_Lib_V1.5.1\Project\STM32F4xx_StdPeriph_Templates文件夹下存放了官方的一个库工程模板，在用库建立一个完整的工程时，还需要添加这个目录下的stm32f4xx_it.c、stm32f4xx_it.h、stm32f4xx_conf.h这3个文件。
stm32f4xx_it.c这个文件是专门用来编写中断服务函数的，在我们修改前，这个文件已经定义了一些系统异常（特殊中断）的接口，其他普通中断服务函数由我们自己添加。但是我们怎么知道这些中断服务函数的接口如何写？是不是可以自定义呢？当然不可以，这些都可以在汇编启动文件中找到，在学习中断和启动文件的时候我们会详细介绍。
stm32f4xx_conf.h这个文件被包含进stm32f4xx.h文件。ST标准库支持所有STM32F4型号的芯片，但有的型号芯片外设功能比较多，所以使用这个配置文件根据芯片型号增减ST库的外设文件，见代码清单8-3。针对STM32F429和STM32F427型号芯片的差异，它们实际包含不一样的头文件，我们通过宏来指定芯片的型号。
代码清单8-3 stm32f4xx_conf.h文件配置软件库
1
2 #if defined (STM32F429_439xx) || defined(STM32F446xx)
3 #include "stm32f4xx_cryp.h"
4 #include "stm32f4xx_hash.h"
5 #include "stm32f4xx_rng.h"
6 #include "stm32f4xx_can.h"
7 #include "stm32f4xx_dac.h"
8 #include "stm32f4xx_dcmi.h"
9 #include "stm32f4xx_dma2d.h"
10 #include "stm32f4xx_fmc.h"
11 #include "stm32f4xx_ltdc.h"
12 #include "stm32f4xx_sai.h"
13 #endif /＊ STM32F429_439xx || STM32F446xx ＊/
14
15 #if defined (STM32F427_437xx)
16 #include "stm32f4xx_cryp.h"
17 #include "stm32f4xx_hash.h"
18 #include "stm32f4xx_rng.h"
19 #include "stm32f4xx_can.h"
20 #include "stm32f4xx_dac.h"
21 #include "stm32f4xx_dcmi.h"
22 #include "stm32f4xx_dma2d.h"
23 #include "stm32f4xx_fmc.h"
24 #include "stm32f4xx_sai.h"
25 #endif /＊ STM32F427_437xx ＊/
26
27 #if defined (STM32F40_41xxx)
stm32f4xx_conf.h这个文件还可配置是否使用“断言”编译选项，见代码清单8-4。
代码清单8-4 断言配置
1 #ifdef USE_FULL_ASSERT
2
3 /＊＊
4 ＊ @简介 assert_param宏用于检测函数的形参是否正确
5 ＊ @形参 expr：如果形参expr为假, 将调用assert_failed函数，该函数会输出
6 调用出错的文件名和出错的行号，如果形参expr为真，则没有返回值
7 ＊ @返回值 无
8 ＊/
9 #define assert_param(expr) ((expr) ? (void)0 : assert_failed((uint8_t
＊)__FILE__, __LINE__))
10 /＊ Exported functions ---------------------------------- ＊/
11 void assert_failed(uint8_t＊ file, uint32_t line);
12 #else
13 #define assert_param(expr) ((void)0)
14 #endif /＊ USE_FULL_ASSERT ＊/
在ST标准库的函数中，一般会包含输入参数检查。assert_param宏用于检测函数的形参是否正确，它没有返回值。expr为函数的形参。如果expr为假，将调用assert_failed函数，该函数会输出调用出错的文件和出错行号；如果expr为真，则没有返回值。
在实际开发中使用断言时，先通过定义USE_FULL_ASSERT宏来使能断言，然后定义assert_failed函数，通常我们会让它调用printf函数输出错误说明。使能断言后，程序运行时会检查函数的输入参数，当软件经过测试、可发布时，再取消USE_FULL_ASSERT宏去掉断言功能，使程序得以全速运行。
8.1.2 各库文件间的关系
前面简单介绍了各个库文件的作用，使用时将库文件直接包含进工程即可，丝毫不用修改。但有的文件就要我们在使用的时候根据具体的需要进行配置。接下来，从整体上把握一下各个文件在库工程中的层次或关系，这些文件对应到CMSIS标准架构上，见图8-6。
图8-6 各库文件间的关系
图8-6描述了STM32各库文件之间的调用关系，这个图省略了DSP核和实时系统层部分的文件关系。在实际使用库开发工程的过程中，我们把位于CMSIS层的文件包含进工程，除了特殊系统时钟需要修改system_stm32f4xx.c以外，其他文件丝毫不用修改，也不建议修改。
而位于用户层的几个文件，就是我们在使用库的时候，针对不同的应用对库文件进行增删（用条件编译的方法增删）和改动的文件。