STM32库函数断言机制宏定义assert_param(expr)和assert_failed的使用方法

首先我们先了解一下，什么是断言？断言都有什么特点？

断言就是我们人为定义的一个宏，用于判断一些输入参数的布尔表达式是否为预设的值的范围内，如果是就为真，否则就为假。断言就是用于检查一些函数的输入参数的合法性。一般默认情况下，断言的功能是关闭的，在debug调试模式下，将断言功能打开；在release发布模式下，将断言功能关闭，断言打开的话，会在一定程度上影响函数的执行效率。

使用断言，可以创建更加稳定，不易出错的代码。如果在单元测试过程中，使用断言，将会非常方便。使用断言得区别于代码错误，代码错误编译就会不通过，但是断言有问题，代码编译是OK的。断言检查的就是在代码执行过程中，一些输入参数的合法性是否为真。

断言就是在debug模式下，代码运行过程中，对函数中输入的参数进行检查。如果输入的参数违规，将进行某些操作，输出一些信息提醒，或者控制代码进入一个死循环使得代码无法继续执行下去。在release版本，是不用断言功能的。

下面我们用STM32F407ZGT6的工程来解释断言的用法。我们使用的是STM32的固件库版本是3.5，使用的编译环境是keil MDK V5.24A，断言检测出异常的文件名和行号会通过串口输出，并将终止代码执行进入一个死循环。

如下的代码摘自文件“stm32f4xx_conf.h”

 1 /* #define USE_FULL_ASSERT    1 */
 2 
 3 /* Exported macro ------------------------------------------------------------*/
 4 #ifdef  USE_FULL_ASSERT
 5 
 6 /**
 7   * @brief  The assert_param macro is used for function's parameters check.
 8   * @param  expr: If expr is false, it calls assert_failed function
 9   *   which reports the name of the source file and the source
10   *   line number of the call that failed. 
11   *   If expr is true, it returns no value.
12   * @retval None
13   */
14   #define assert_param(expr) ((expr) ? (void)0 : assert_failed((uint8_t *)__FILE__, __LINE__))
15 /* Exported functions ------------------------------------------------------- */
16   void assert_failed(uint8_t* file, uint32_t line);
17 #else
18   #define assert_param(expr) ((void)0)
19 #endif /* USE_FULL_ASSERT */

第1行代码，默认情况下断言是关闭的，已经把“#define USE_FULL_ASSERT 1 ”注释掉，说明USE_FULL_ASSERT未被定义。

如果需要打开断言的功能，需要将“#define USE_FULL_ASSERT 1 ”注释去掉，如下代码所示

 1 #define USE_FULL_ASSERT    1 
 2 
 3 /* Exported macro ------------------------------------------------------------*/
 4 #ifdef  USE_FULL_ASSERT
 5 
 6 /**
 7   * @brief  The assert_param macro is used for function's parameters check.
 8   * @param  expr: If expr is false, it calls assert_failed function
 9   *   which reports the name of the source file and the source
10   *   line number of the call that failed. 
11   *   If expr is true, it returns no value.
12   * @retval None
13   */
14   #define assert_param(expr) ((expr) ? (void)0 : assert_failed((uint8_t *)__FILE__, __LINE__))
15 /* Exported functions ------------------------------------------------------- */
16   void assert_failed(uint8_t* file, uint32_t line);
17 #else
18   #define assert_param(expr) ((void)0)
19 #endif /* USE_FULL_ASSERT */

第1行，宏定义常量USE_FULL_ASSERT的值为1

第14行，是一个宏定义assert_param(expr)，通过一个条件判断语句，如果表达式expr的值为真，则assert_param(expr)返回（void）0，如果表达式expr的值为假，则assert_param(expr)返回assert_failed((uint8_t *)__FILE__, __LINE__)。

第16行，函数声明void assert_failed(uint8_t* file, uint32_t line);这个函数的作用就是返回调用这个函数的文件名和行数。

断言打开之后，编译工程出现一个错误如下：

..\OBJ\Template.axf: Error: L6218E: Undefined symbol assert_failed (referred from misc.o).
Not enough information to list image symbols.
Not enough information to list load addresses in the image map.
Finished: 2 information, 0 warning and 1 error messages.
"..\OBJ\Template.axf" - 1 Error(s), 0 Warning(s).
Target not created.
Build Time Elapsed: 00:00:00

通过编译错误的说明提示，函数assert_failed没有定义，我们在main.c文件中定义函数assert_failed，如下所示：

1 void assert_failed(uint8_t* file, uint32_t line)
2 {
3  printf("Wrong parameters value: file %s on line %d\r\n", file, line);
4  while(1);
5 }

注意printf是通过串口1输出的，因为我们已经将输出重定位到串口1了。

再编译工程，无错误无警告。

现在我们人为修改一些不合法的参数，比如文件“led.c”中，函数LED_Init的第15行代码屏蔽掉，增加16行代码，然后将GPIO_Pin_9 | GPIO_Pin_10用0x0替代，请参考如下代码：

 1 void LED_Init(void)
 2 {         
 3   GPIO_InitTypeDef  GPIO_InitStructure;
 4 
 5   RCC_AHB1PeriphClockCmd(RCC_AHB1Periph_GPIOF, ENABLE);//使能GPIOF时钟
 6 
 7   //GPIOF9,F10初始化设置
 8   GPIO_InitStructure.GPIO_Pin = GPIO_Pin_9 | GPIO_Pin_10;
 9   GPIO_InitStructure.GPIO_Mode = GPIO_Mode_OUT;//普通输出模式
10   GPIO_InitStructure.GPIO_OType = GPIO_OType_PP;//推挽输出
11   GPIO_InitStructure.GPIO_Speed = GPIO_Speed_100MHz;//100MHz
12   GPIO_InitStructure.GPIO_PuPd = GPIO_PuPd_UP;//上拉
13   GPIO_Init(GPIOF, &GPIO_InitStructure);//初始化
14     
15 //    GPIO_SetBits(GPIOF,GPIO_Pin_9 | GPIO_Pin_10);//GPIOF9,F10设置高，灯灭
16     GPIO_SetBits(GPIOF,0x0);
17 }

我们定位到GPIO_Pin_9宏定义的地方，如下代码所示：

 1 #define GPIO_Pin_0                 ((uint16_t)0x0001)  /* Pin 0 selected */
 2 #define GPIO_Pin_1                 ((uint16_t)0x0002)  /* Pin 1 selected */
 3 #define GPIO_Pin_2                 ((uint16_t)0x0004)  /* Pin 2 selected */
 4 #define GPIO_Pin_3                 ((uint16_t)0x0008)  /* Pin 3 selected */
 5 #define GPIO_Pin_4                 ((uint16_t)0x0010)  /* Pin 4 selected */
 6 #define GPIO_Pin_5                 ((uint16_t)0x0020)  /* Pin 5 selected */
 7 #define GPIO_Pin_6                 ((uint16_t)0x0040)  /* Pin 6 selected */
 8 #define GPIO_Pin_7                 ((uint16_t)0x0080)  /* Pin 7 selected */
 9 #define GPIO_Pin_8                 ((uint16_t)0x0100)  /* Pin 8 selected */
10 #define GPIO_Pin_9                 ((uint16_t)0x0200)  /* Pin 9 selected */
11 #define GPIO_Pin_10                ((uint16_t)0x0400)  /* Pin 10 selected */
12 #define GPIO_Pin_11                ((uint16_t)0x0800)  /* Pin 11 selected */
13 #define GPIO_Pin_12                ((uint16_t)0x1000)  /* Pin 12 selected */
14 #define GPIO_Pin_13                ((uint16_t)0x2000)  /* Pin 13 selected */
15 #define GPIO_Pin_14                ((uint16_t)0x4000)  /* Pin 14 selected */
16 #define GPIO_Pin_15                ((uint16_t)0x8000)  /* Pin 15 selected */
17 #define GPIO_Pin_All               ((uint16_t)0xFFFF)  /* All pins selected */
18 
19 #define GPIO_PIN_MASK              ((uint32_t)0x0000FFFF) /* PIN mask for assert test */
20 #define IS_GPIO_PIN(PIN)           (((PIN) & GPIO_PIN_MASK ) != (uint32_t)0x00)

第20行，宏定义IS_GPIO_PIN(PIN)，如果PIN为0，则IS_GPIO_PIN(PIN)的值就为0。

我们查看函数GPIO_SetBits定义的代码，来自文件stm32f4xx_gpio.c。代码如下：

STM32库函数断言机制宏定义assert_param(expr)和assert_failed的使用方法