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