foxBMS - Unit Tests  1.4.0
The foxBMS Unit Tests API Documentation
nxpfs85xx.h
Go to the documentation of this file.
1 /**
2  *
3  * @copyright © 2010 - 2022, Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V.
4  * All rights reserved.
5  *
6  * SPDX-License-Identifier: BSD-3-Clause
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions are met:
10  *
11  * 1. Redistributions of source code must retain the above copyright notice, this
12  * list of conditions and the following disclaimer.
13  *
14  * 2. Redistributions in binary form must reproduce the above copyright notice,
15  * this list of conditions and the following disclaimer in the documentation
16  * and/or other materials provided with the distribution.
17  *
18  * 3. Neither the name of the copyright holder nor the names of its
19  * contributors may be used to endorse or promote products derived from
20  * this software without specific prior written permission.
21  *
22  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
23  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
25  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
26  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
28  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
29  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
30  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32  *
33  * We kindly request you to use one or more of the following phrases to refer to
34  * foxBMS in your hardware, software, documentation or advertising materials:
35  *
36  * - ″This product uses parts of foxBMS®″
37  * - ″This product includes parts of foxBMS®″
38  * - ″This product is derived from foxBMS®″
39  *
40  */
41 
42 /**
43  * @file nxpfs85xx.h
44  * @author foxBMS Team
45  * @date 2020-03-18 (date of creation)
46  * @updated 2022-07-28 (date of last update)
47  * @version v1.4.0
48  * @ingroup DRIVERS
49  * @prefix FS85
50  *
51  * @brief Header for the driver for the FRAM module
52  *
53  * @details It must always be used when creating new c header files.
54  *
55  */
56 
57 #ifndef FOXBMS__NXPFS85XX_H_
58 #define FOXBMS__NXPFS85XX_H_
59 
60 /*========== Includes =======================================================*/
61 #include "fram_cfg.h"
62 #include "nxpfs85xx_cfg.h"
63 
64 #include "sbc_fs8x.h"
65 #include "sbc_fs8x_communication.h"
66 #include "spi.h"
67 
68 /*========== Macros and Definitions =========================================*/
69 /** struct for fail-safe registers
70  * for register description see data sheet FS84_FS85 - Rev. 3.0 - 9 April 2019 */
71 typedef struct {
72  uint16_t grl_flags; /*!< FS8X_FS_GRL_FLAGS_ADDR */
73  uint16_t iOvervoltageUndervoltageSafeReaction1; /*!< FS8X_FS_I_OVUV_SAFE_REACTION1_ADDR */
74  uint16_t iOvervoltageUndervoltageSafeReaction2; /*!< FS8X_FS_I_OVUV_SAFE_REACTION2_ADDR */
75  uint16_t iWatchdogConfiguration; /*!< FS8X_FS_I_WD_CFG_ADDR */
76  uint16_t i_safe_inputs; /*!< FS8X_FS_I_SAFE_INPUTS_ADDR */
77  uint16_t iFailSafeSateMachine; /*!< FS8X_FS_I_FSSM_ADDR */
78  uint16_t i_svs; /*!< FS8X_FS_I_SVS_ADDR */
79  uint16_t watchdogWindow; /*!< FS8X_FS_WD_WINDOW_ADDR */
80  uint16_t watchdogSeed; /*!< FS8X_FS_WD_SEED_ADDR */
81  uint16_t watchdogAnswer; /*!< FS8X_FS_WD_ANSWER_ADDR */
82  uint16_t overvoltageUndervoltageRegisterStatus; /*!< FS8X_FS_OVUVREG_STATUS_ADDR */
83  uint16_t releaseFs0bPin; /*!< FS8X_FS_RELEASE_FS0B_ADDR */
84  uint16_t safeIos; /*!< FS8X_FS_SAFE_IOS_ADDR */
85  uint16_t diag_safety; /*!< FS8X_FS_DIAG_SAFETY_ADDR */
86  uint16_t intb_mask; /*!< FS8X_FS_INTB_MASK_ADDR */
87  uint16_t states; /*!< FS8X_FS_STATES_ADDR */
89 
90 /** struct for main registers
91  * for register description see data sheet FS84_FS85 - Rev. 3.0 - 9 April 2019 */
92 typedef struct {
93  uint16_t flag; /*!< FS8X_M_FLAG_ADDR */
94  uint16_t mode; /*!< FS8X_M_MODE_ADDR */
95  uint16_t registerControl1; /*!< FS8X_M_REG_CTRL1_ADDR */
96  uint16_t registerControl2; /*!< FS8X_M_REG_CTRL2_ADDR */
97  uint16_t analogMultiplexer; /*!< FS8X_M_AMUX_ADDR */
98  uint16_t clock; /*!< FS8X_M_CLOCK_ADDR */
99  uint16_t int_mask1; /*!< FS8X_M_INT_MASK1_ADDR */
100  uint16_t int_mask2; /*!< FS8X_M_INT_MASK2_ADDR */
101  uint16_t flag1; /*!< FS8X_M_FLAG1_ADDR */
102  uint16_t flag2; /*!< FS8X_M_FLAG2_ADDR */
103  uint16_t vmon_regx; /*!< FS8X_M_VMON_REGX_ADDR */
104  uint16_t lvb1_svs; /*!< FS8X_M_LVB1_SVS_ADDR */
105  uint16_t memory0; /*!< FS8X_M_MEMORY0_ADDR */
106  uint16_t memory1; /*!< FS8X_M_MEMORY1_ADDR */
107  uint16_t deviceId; /*!< FS8X_M_DEVICEID_ADDR */
109 
110 typedef enum {
114 
115 /** struct for FIN configuration */
116 typedef struct {
117  bool finUsed; /*!< flag if FIN feature of SBC is used */
118  STD_RETURN_TYPE_e finState; /*!< Is set to STD_NOT_OK if short circuit between FIN and RSTB pin detected */
119  volatile uint32_t *pGIOport; /*!< pointer to port where FIN pin of SBC is connected to */
120  uint32_t pin; /*!< pin where FIN pin of SBC is connected to */
122 
123 /** stores a pointer to the persistent entry in the FRAM */
124 typedef struct {
125  FRAM_BLOCK_ID_e entry; /*!< FRAM ID of persistent SBC entry in FRAM */
126  FRAM_SBC_INIT_s *data; /*!< pointer to SBC entry in FRAM module */
128 
129 /** state struct to create SBC instance */
130 typedef struct {
131  SPI_INTERFACE_CONFIG_s *pSpiInterface; /*< pointer to used SPI interface configuration */
132  fs8x_drv_data_t configValues; /*!< configuration of used communication interface */
133  FS85_FIN_CONFIGURATION_s fin; /*!< configurations for FIN functionality */
134  FS85_MAIN_REGISTERS_s mainRegister; /*!< FS85xx main registers */
135  FS85_FS_REGISTER_s fsRegister; /*!< FS85xx safety registers */
136  FS85_NVRAM_INFO_s nvram; /*!< configuration and data for persistent memory required for initialization */
137  FS85_OPERATION_MODE_e mode; /*!< current operation mode of FS85xx */
138 } FS85_STATE_s;
139 
140 /*========== Extern Constant and Variable Declarations ======================*/
142 
143 /*========== Extern Function Prototypes =====================================*/
144 /**
145  * @brief Configures SBC during INIT_FS phase
146  * @details Checks first if SBC currently is in INIT_FS phase and if
147  * not transfers SBC back into INIT_FS. Verifies basic checks,
148  * configures fail-safe registers and closes INIT_FS
149  * afterwards.
150  * @param[in,out] pInstance SBC instance that is initialized
151  * @return #STD_OK if all checks were successful and SBC configured
152  * correctly, otherwise #STD_NOT_OK
153  */
155 
156 /**
157  * @brief Calculates the number of required watchdog refresh to reset
158  * fault error counter
159  * @param[in,out] pInstance SBC instance that is
160  * initialized
161  * @param[out] requiredWatchdogRefreshes number of required good
162  * watchdog refreshes
163  * @return #STD_OK if required watchdog refreshes were calculated
164  * successfully, otherwise #STD_NOT_OK
165  */
167  FS85_STATE_s *pInstance,
168  uint8_t *requiredWatchdogRefreshes);
169 
170 /**
171  * @brief Checks if fault error counter is zero
172  * @param[in,out] pInstance SBC instance where fault error counter is
173  * checked
174  * @return #STD_OK if fault error counter equals zero, otherwise
175  * #STD_NOT_OK
176  */
178 
179 /**
180  * @brief Performs SBC safety path checks
181  * @details Function perform safety path checks for FIN, FS0B and RSTB
182  * to ensure that all pins work as expected
183  * @param[in,out] pInstance where the safety paths are checked
184  * @return #STD_OK if safety path check successful, otherwise
185  * #STD_NOT_OK
186  */
188 
189 /**
190  * @brief Trigger watchdog
191  * @details Triggers watchdog of passed SBC instance and verify if it
192  * was good refresh within the configured window
193  * @param[in,out] pInstance SBC instance where the watchdog is triggered
194  * @return #STD_OK if watchdog has been triggered successfully,
195  * otherwise #STD_NOT_OK
196  */
198 
199 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
200 #ifdef UNITY_UNIT_TEST
201 extern STD_RETURN_TYPE_e TEST_SBC_CheckRegisterValues(uint32_t registerValue, uint32_t expectedRegisterValue);
202 extern void TEST_SBC_UpdateRegister(
203  FS85_STATE_s *pInstance,
204  bool isFailSafe,
205  uint32_t registerAddress,
206  uint32_t registerValue);
208  FS85_FS_REGISTER_s *pFsRegister,
209  uint32_t registerAddress,
210  uint32_t registerValue);
211 extern void TEST_SBC_UpdateMainRegister(
212  FS85_MAIN_REGISTERS_s *pMainRegister,
213  uint32_t registerAddress,
214  uint32_t registerValue);
215 #endif
216 
217 #endif /* FOXBMS__NXPFS85XX_H_ */
Headers for the configuration for the FRAM module.
FRAM_BLOCK_ID_e
Definition: fram_cfg.h:100
STD_RETURN_TYPE_e
Definition: fstd_types.h:81
STD_RETURN_TYPE_e FS85_InitializeNumberOfRequiredWatchdogRefreshes(FS85_STATE_s *pInstance, uint8_t *requiredWatchdogRefreshes)
Calculates the number of required watchdog refresh to reset fault error counter.
Definition: nxpfs85xx.c:882
void TEST_SBC_UpdateRegister(FS85_STATE_s *pInstance, bool isFailSafe, uint32_t registerAddress, uint32_t registerValue)
Definition: nxpfs85xx.c:1243
FS85_STATE_s fs85xx_mcuSupervisor
Definition: nxpfs85xx.c:81
STD_RETURN_TYPE_e FS85_InitializeFsPhase(FS85_STATE_s *pInstance)
Configures SBC during INIT_FS phase.
Definition: nxpfs85xx.c:497
STD_RETURN_TYPE_e SBC_TriggerWatchdog(FS85_STATE_s *pInstance)
Trigger watchdog.
Definition: nxpfs85xx.c:1020
STD_RETURN_TYPE_e TEST_SBC_CheckRegisterValues(uint32_t registerValue, uint32_t expectedRegisterValue)
Definition: nxpfs85xx.c:1239
void TEST_SBC_UpdateFailSafeRegister(FS85_FS_REGISTER_s *pFsRegister, uint32_t registerAddress, uint32_t registerValue)
Definition: nxpfs85xx.c:1251
void TEST_SBC_UpdateMainRegister(FS85_MAIN_REGISTERS_s *pMainRegister, uint32_t registerAddress, uint32_t registerValue)
Definition: nxpfs85xx.c:1258
FS85_OPERATION_MODE_e
Definition: nxpfs85xx.h:110
@ SBC_DEBUG_MODE
Definition: nxpfs85xx.h:112
@ SBC_NORMAL_MODE
Definition: nxpfs85xx.h:111
STD_RETURN_TYPE_e FS85_SafetyPathChecks(FS85_STATE_s *pInstance)
Performs SBC safety path checks.
Definition: nxpfs85xx.c:954
STD_RETURN_TYPE_e FS85_CheckFaultErrorCounter(FS85_STATE_s *pInstance)
Checks if fault error counter is zero.
Definition: nxpfs85xx.c:939
Config header file for SBC module.
FS8x driver interface.
This file contains functions for SPI/I2C communication.
Headers for the driver for the SPI module.
volatile uint32_t * pGIOport
Definition: nxpfs85xx.h:119
STD_RETURN_TYPE_e finState
Definition: nxpfs85xx.h:118
uint16_t diag_safety
Definition: nxpfs85xx.h:85
uint16_t releaseFs0bPin
Definition: nxpfs85xx.h:83
uint16_t i_svs
Definition: nxpfs85xx.h:78
uint16_t iWatchdogConfiguration
Definition: nxpfs85xx.h:75
uint16_t watchdogAnswer
Definition: nxpfs85xx.h:81
uint16_t overvoltageUndervoltageRegisterStatus
Definition: nxpfs85xx.h:82
uint16_t i_safe_inputs
Definition: nxpfs85xx.h:76
uint16_t iOvervoltageUndervoltageSafeReaction2
Definition: nxpfs85xx.h:74
uint16_t safeIos
Definition: nxpfs85xx.h:84
uint16_t watchdogSeed
Definition: nxpfs85xx.h:80
uint16_t iFailSafeSateMachine
Definition: nxpfs85xx.h:77
uint16_t grl_flags
Definition: nxpfs85xx.h:72
uint16_t watchdogWindow
Definition: nxpfs85xx.h:79
uint16_t states
Definition: nxpfs85xx.h:87
uint16_t intb_mask
Definition: nxpfs85xx.h:86
uint16_t iOvervoltageUndervoltageSafeReaction1
Definition: nxpfs85xx.h:73
uint16_t registerControl1
Definition: nxpfs85xx.h:95
uint16_t registerControl2
Definition: nxpfs85xx.h:96
uint16_t analogMultiplexer
Definition: nxpfs85xx.h:97
FRAM_BLOCK_ID_e entry
Definition: nxpfs85xx.h:125
FRAM_SBC_INIT_s * data
Definition: nxpfs85xx.h:126
FS85_MAIN_REGISTERS_s mainRegister
Definition: nxpfs85xx.h:134
FS85_OPERATION_MODE_e mode
Definition: nxpfs85xx.h:137
FS85_FS_REGISTER_s fsRegister
Definition: nxpfs85xx.h:135
FS85_NVRAM_INFO_s nvram
Definition: nxpfs85xx.h:136
FS85_FIN_CONFIGURATION_s fin
Definition: nxpfs85xx.h:133
fs8x_drv_data_t configValues
Definition: nxpfs85xx.h:132
SPI_INTERFACE_CONFIG_s * pSpiInterface
Definition: nxpfs85xx.h:131
This data structure is used by the FS8x driver (this is the first parameter of most the FS8x function...