小猫爪：S32K3学习笔记21-S32K3之SAF及其应用

1 前言

  这一篇来讲一讲NXP针对S32K3的Safety特征安全软件框架SAF。这篇文章旨帮助使用SAF的用户更好更快的理解和上手SAF，更多的细节还是需要仔细参考SAF每个模块的UM手册。NXP官方提供了一个免费评估的版本，感兴趣的可以去下载一下。

2 SAF简介

  SAF是什么呢？它是一个完整的安全软件框架，简单的来说，SAF实现了从一个错误发生，到这个错误被检测，再到这个错误被处理，再到这个MCU针对这个错误的反应这一系列行为内容。所以它是一个完整的软件框架，只需要客户将其移植到自己的应用中，作一些小小的完善和改变就OK了。

  去官网上下载SAF的体验卡安装包后，如下：

  这些模块所实现的具体的功能为：

名字	完整名字	描述
Base	、、、	一些头文件，无需移植
SafetyBase	、、、	一些跟安全相关的必要头文件
Rte	、、、	一种防覆盖的软件保护措施
Bist	BIST Manager	BIST管理模块(STCU2)
eMcem	Error Manager	错误管理模块(FCCU, ERM, EIM, XBIC, DCM)
sBoot	Safe Boot	检测硬件外设配置
sCheck	Square Check	潜在错误检测模块，主动发起检测
sReco	Software Recovery	软件恢复模块，发生错误后，通过复位来修复错误
mSel	Mode Slector	进行安全分析，进行MCU状态模式切换，相当于是SAF的状态切换机

3 SAF框架

  完整的SAF的软件框架如下：

  从图中可以看出在有SAF的软件运行流程如下：

1. POR阶段
     POR阶段也就是复位事件产生，MCU正式启动，如果使能了HSE，那MCU进入 HSE boot阶段，如果没有使能HSE， MCU进入Safe Boot阶段。
2. HSE boot阶段
     如果使能Security Boot功能，那么就会进行HSE信息安全启动验证程序的合法性。验证通过，MCU进入Safe Boot阶段。
3. Safe Boot阶段
     在这个阶段，主要做三件事。第一件事是使用Bist模块进行BIST测试，再使用mSel进行安全分析，决定是否进行MCU状态模式切换；第二件事是使用sCheck进行相关错误检测，继续使用mSel进行安全分析和模式切换；第三件事就是一系列的初始化，包括SAF相关外设的初始化和用户应用外设初始化。在此过程中，mSel根据MCU的状态进行安全分析并进行模式切换，会决定MCU模式状态，而mSel定义的的状态模式有三种，分别是Normal Mode，Degraded mode和Software Recovery 。安全分析后，如果没有任何错误则切换至Normal Mode，MCU进入Normal Operation阶段；如果有一些可恢复错误（用户自定义）则切换至Degraded mode，MCU进入Degrad Operation阶段；如果有致命错误（用户自定义）则切换至Software Recovery，MCU会立即执行复位操作。
4. Normal Operation阶段
     在这个阶段其实就是正常运行模式，第一步就是使用sBoot来检测一些外设的配置是否正确，如果不正确的话，则MCU复位。如果正确，则进入while循环状态，周期性的运行一些任务，比如SCST， sCheck，用户自定义任务等等。在整个while循环阶段，如果发生错误后，错误被eMcem收集并处理（详情见FCCU文章），如果FCCU最终触发NMI中断，那么就会使用sReco进行MCU复位，在执行sReco复位前，SAF会将相关错误信息存储到RAM或者NVM中，供启动后的下个Safe Boot阶段中的mSel作错误分析，以决定MCU状态模式。
5. Degrad Operation阶段
     这个阶段其实就是安全运行模式，用户可以定义多个安全模式，来决定在不同的安全模式下运行不同的安全应用任务，除了安全任务，当然也可以运行SCST， sCheck。 同Normal Operation阶段一样，如果在整个过程中发生错误，还是会走eMcem错误处理机制。
6. Shutdown阶段
     因为很多错误恢复的手段都是复位，所以如果在以上阶段MCU复位次数累计超过设置的阈值，MCU就会进入Shutdown阶段，即MCU卡在复位的DEST0阶段不启动。

  对于S32K3来说，由于其功能结构比较简单，所以说阉割版的SAF更加适合S32K3，如下：

  与完整SAF相比，K3上阉割版SAF就少了Degrad Operation阶段，所以mSel进行安全分析后切换MCU状态模式时只有两个选择，要不就是没有任何错误进入Normal Mode，要不就是有错误使用sReco进行复位清除错误。这样的阉割版SAF被称为SAF的Normal Mode Only Mode。

4 SAF组件

  这一节详细来说说SAF每个组件的工作原理。

4.1 eMcem和Bist

  eMcem和Bist是SPD的组件，所以说SPD是SAF的一小部分，其中eMcem是SAF的错误管理器，而Bist是专门用来进行BIST测试的，其在Safety系列文章已经对这两个模块的使用进行了详细的介绍。详情请见如下文章：

1. 《S32K3之FCCU》
2. 《S32K3之STCU2》

  注：关于eMcem模块和Bist模块的MCAL配置在其的UM手册已经被描述的非常清楚了，这里就不多做介绍了，详情请见《S32K3_SAF_BIST_UM.pdf》和《S32K3_SAF_EMCEM_UM.pdf》。

4.2 sReco

  在简介中提到sReco是软件恢复模块，发生错误后，恢复MCU状态。下图显示了sReco在SAF中充当的角色：

  可以看到sReco在SAF中被调只存在两种情况：第一是mSel模式选择时未能进入Normal Mode和Degraded Mode；第二是MCU发生致命错误进入NMI中断。查看其源码就能了解到它恢复MCU状态的方式其实就是让MCU进行软件功能性复位。需要注意的是在进行复位前，如果发现有ECC错误，那么它会记录发生ECC错误的地址信息至RAM中，所以为了在复位之后保留这个数据，需要在启动时加个判断，如果是软件复位或者FCCU复位，那么则不进行RAM ECC 初始化。

  该模块是一个纯粹的执行模块，没有相对应的MCAL配置模块，无需配置。

4.3 mSel

  在上面说SAF软件状态机切换流程的时候，提到mSel是用来在Safety Boot阶段切换MCU状态模式的，那么mSel的工作原理是怎样的呢？如下图所示：

  mSel会整合所有的错误源信息来做安全分析，而这些错误源信息包括eMcem模块收集的错误信息， sCheck模块检查的结果，Bist模块执行后的结果，以及mSel存储的历史错误信息。整合所有的错误信息进行安全分析后，来决定MCU状态模式。

  下面再来说说mSel安全分析的原理是怎样？首先mSel会划分若干个功能域（Functional Region），比如我先划分四个功能域，分别是A,B,C,D，接下来再把所有的错误源按照一定需求分别链接到这四个功能域。如果当一个功能域所链接的所有错误源都没有发生错误，那么则就撑这个功能域为正常，反之异常。比如我将所有的Memory ECC错误源链接到A域，那么mSel作安全分析时，如果没有任何的ECC错误，则A域正常。接下里用户可将功能域与不同的MCU状态模式按照需求进行关联，如果我将A,B,C,D四个功能域关联到Normal Mode，那么就代表着进入Normal Mode必须要求这四个功能域都正常，显然只有当所有的功能域全部正常时，mSel才会切换至Normal Mode；如果我将A域和B域关联到Degraded Mode0，那么就代表着进入Degraded Mode0只要求这A域和B域都正常。所以当有些功能域不正常导致MCU无法进入Normal Mode时，此时如果A域和B域正常，则mSel会切换MCU至Degraded Mode0。当然有Degraded Mode0，那肯定也能有Degraded Mode1，所以可以同时有多个Degraded Mode，用户可自定义。如果由于功能域的状态无法进入所定义的所有模式，那么mSel就会直接存储错误信息并切换状态至Software Recovery让MCU进行功能性复位。

  上面提到过mSel可以存储错误信息至RAM或者NVM中供下次mSel作安全统计分析使用。首先mSel是一定会将数据存储到RAM中，所以为了避免RAM中在复位后被清除，那么就要需要在RAM初始化加个判断，读取复位原因，如果是软件功能性复位或者FCCU功能复位，那么则不进行RAM ECC初始，并且还需要将这些变量链接到启动时不会进行初始化的数据section。而存储在NVM中则是可选的，如果使能这个功能，则客户必须初始化mSel读写NVM的接口供mSel调用。

  mSel还提供了一个Threshold机制，这个机制其实就是为所有的错误源设置一个阈值，当错误源出现错误时，SAF会进行其次数累加并将其存储，只有当一个错误源出现错误的次数到达其对应的阈值，SAF才会认定该错误源所链接的功能域异常。

  mSel还提供了事件戳功能，记录所有错误发生的时间，在做安全分析时，还会对错误时间戳进行判断，不符合时间要求的错误源不会被包括在判断范围内。所以用户在进行代码集成时，需要在代码中维护提供时间戳的外设源。

  注：关于mSel模块的MCAL配置在其的UM手册已经被描述的非常清楚了，这里就不多做介绍了，详情请见《S32K3_SAF_MSEL_UM.pdf》。

4.4 sBoot

  前面在SAF框架中提到sBoot模块主要是在MCU从Safe Boot阶段进入Normal Operation阶段时检查一下当前外设的初始化情况是否正常，如果不正确的话，则MCU复位。

  其实sBoot的检查项内容也是非常的简单，我截取一小部分（详细请参照sBoot的UM手册的Table4）如下：

  sBoot的检查项主要有时钟是否使能，一些外设的Debug模式是否使能，一些外设的Freeze模式是否使能。此外用户可根据自己的需求来决定每一个检查项是否被检查。

  注：关于sBoot模块的MCAL配置在其的UM手册已经被描述的非常清楚了，这里就不多做介绍了，详情请见《S32K3_SAF_SBOOT_UM.pdf》。

4.5 sCheck

  sCheck是用来发现错误和收集错误信息，其主要是让MCU主动运行一些安全检测机制来发现潜在的错误，并收集错误信息。

  sCheck根据MCU的启动阶段，运行阶段和复位阶段这3种状态提供了3种检测方式，分别是Start-up Test，Runtime Test和Shutdown Test。

1. Start-up Test
      Start-up Test应该在MCU启动时被启动，它可能会修改一些外设的配置而不会复原，所以启动 Start-up Test后用户必须要重新初始化自己的外设，所以一般都是在开机后以及用户初始化外设之前启动Start-up Test。如果是S32K324这种双核运行的PN上，Start-up Test只能在主核被调用。Start-up Test会在mSel进行安全分析时会被执行(mSel_SelectMode), 无需用户自己启动。
2. Runtime Test
     Runtime Test应该是在MCU运行时被启动，它也会修改外设配置但是它在检测结束后是会恢复现场的，所以它可以在应用中反复被启动，其可以同时在不同的核上被调用。在启动测试时，用户需要考虑到sCheck和APP同时访问外设的情况，这样会导致sCheck失败，所以在启动 Runtime Test时必须要确保APP已经释放了那些测试外设的访问。另外Runtime Test需要用户调用函数自行启动。
3. Shutdown Test
     Shutdown Test应该是在MCU执行复位复位前被启动，它也会修改外设配置但是它在检测结束后是会恢复现场的，其可以同时在不同的核上被调用。在启动测试时，用户需要考虑到sCheck和APP同时访问外设的情况，这样会导致sCheck失败，所以在启动 Runtime Test时必须要确保APP已经释放了那些测试外设的访问。另外Shutdown Test需要用户调用函数自行启动。

  下面列举一些sCheck的检测项（其他检测项请参考sCheck的UM手册中Table 4）：

  可以看到在这个表中，对每一个检测项所检测的内容，建议放在哪种检测方式中以及运行检测时长都作了详细的介绍，可自行去参考。

  注：在运行sCheck的时候可能会做一些如修改寄存器，禁用中断等一些操作，这势必会影响用户APP的运行，所以对于sCheck的一些检测项强烈建议将其尽量放在Start-up Test和Shutdown Test中被执行。用户可参考sCheck的UM手册中5.8 Conditions, Limitations And Side Effects章节了解每一检测项对外设的影响和限制从而评估运行sCheck对APP的影响从而决定这些测试项将以哪种方式被启动。

  注：关于sCheck模块的MCAL配置在其的UM手册已经被描述的非常清楚了，这里就不多做介绍了，详情请见《S32K3_SAF_SCHECK_UM.pdf》。

5 SAF集成

  接下来就是SAF的集成了，集成起来也是非常简单，具体步骤如下：

1. 将SAF软件包中的主体源文件加入自己的工程中，如下：
   

2. 将SAF软件包中的相关接口源文件加入工程中：
   

3. 按照下图修改链接文件，将SAF的相关段按照要求链接指定地方，在每个模块的UM手册的Software Integration->Memory Allocation章节对其都进行详细的介绍，截取一部分如下：
   
   然后再结合每个模块对应的x_Memmap.h文件找到对应的section名，截取一部分如下：
   
   之后就可以在链接文件中将这些section链接到要求的位置，截取链接文件的一部分如下：
   
   之后编译代码，可能会出现一些错误，按照错误提示将错误消除掉就好了。

4. 查看interrupt.c文件，发现有很多中断服务函数，这是运行sCheck测试项时，有些测试项会主动触发中断，需要这些中断服务函数来配合sCheck完成测试，所以我们需要在一开始注册这些函数，详情见interrupt.c中的Handle_Init函数。

5. 在mSel中提到其有错误时间戳记录功能，所以需要为其提供一个时间戳，这里我使用STM0为其提供，所以需要在STM0中断中周期调用mSel_TimerCnt_Update来维护mSel时间戳，详情见interrupt.c中的STM0_init和ISR_STM0函数(注：用户也可以使用其他定时外设来实现)。

6. sCheck还会触发HardFault中断，所以需要重定义HardFault中断函数，详情见interrupt.c中的HardFault_Handler函数。

7. sCheck的有一些检测项会触发一些外设的中断，比如CMU，SWT，所以需要编写相关的中断服务函数来配合sCheck完成检测，详情见interrupt.c中的ISR_SWTx，ISR_CMUx，ISR_EMAC函数。

8. 如果错误最终导致FCCU触发NMI中断，根据SAF软件框架，SAF必须调用sReco来复位MCU，所以需要重定义NMI中断服务函数，详情见interrupt.c中NMI_Handler函数。

9. 到此，SAF的软件框架算是全部移植完毕了，此外用户需要根据自己的应用需求来完善一个非常重要的函数，那就是FCCU的Alarm中断callback函数eMcemDefaultAlarmHandler，用户需要根据自己的需求在此函数中添加一些自己的处理手段。在《S32K3之FCCU》中对其作了详细的介绍。

6 SAF应用

  至于SAF的应用，它的使用方式大抵和SAF软件框架一致，在每个模块的UM手册中对每个模块的API函数都作了详细的介绍，再结合相关SAF的Demo自行参考，就比较简单了。可参考SAF的软件包里的SAF Demo，也可参考NXP提供的其他例程。

END