foxBMS  1.2.0
The foxBMS Battery Management System API Documentation
nxpfs85xx.h
Go to the documentation of this file.
1 /**
2  *
3  * @copyright © 2010 - 2021, 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 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_ */
Headers for the configuration for the FRAM module.
enum FRAM_BLOCK_ID FRAM_BLOCK_ID_e
enum STD_RETURN_TYPE STD_RETURN_TYPE_e
struct FS85X_FIN_CONFIGURATION FS85X_FIN_CONFIGURATION_s
enum FS85X_OPERATION_MODE FS85X_OPERATION_MODE_e
struct FS85X_MAIN_REGISTERS FS85X_MAIN_REGISTERS_s
STD_RETURN_TYPE_e FS85X_InitFS(FS85xx_STATE_s *pInstance)
Configures SBC during INIT_FS phase.
Definition: nxpfs85xx.c:461
struct SBC_NVRAM_INFO SBC_NVRAM_INFO_s
STD_RETURN_TYPE_e SBC_TriggerWatchdog(FS85xx_STATE_s *pInstance)
Trigger watchdog.
Definition: nxpfs85xx.c:973
struct FS85xx_STATE FS85xx_STATE_s
STD_RETURN_TYPE_e FS85X_CheckFaultErrorCounter(FS85xx_STATE_s *pInstance)
Checks if fault error counter is zero.
Definition: nxpfs85xx.c:898
struct FS85X_FS_REGISTERS FS85X_FS_REGISTER_s
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
STD_RETURN_TYPE_e FS85X_SafetyPathChecks(FS85xx_STATE_s *pInstance)
Performs SBC safety path checks.
Definition: nxpfs85xx.c:910
FS85xx_STATE_s fs85xx_mcuSupervisor
Definition: nxpfs85xx.c:80
FS85X_OPERATION_MODE
Definition: nxpfs85xx.h:109
@ SBC_DEBUG_MODE
Definition: nxpfs85xx.h:111
@ SBC_NORMAL_MODE
Definition: nxpfs85xx.h:110
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.
STD_RETURN_TYPE_e finState
Definition: nxpfs85xx.h:117
volatile uint32_t * pGIOport
Definition: nxpfs85xx.h:118
uint16_t diag_safety
Definition: nxpfs85xx.h:84
uint16_t iOvervoltageUndervolateSafeReaction2
Definition: nxpfs85xx.h:73
uint16_t releaseFs0bPin
Definition: nxpfs85xx.h:82
uint16_t iWatchdogConfiguration
Definition: nxpfs85xx.h:74
uint16_t watchdogAnswer
Definition: nxpfs85xx.h:80
uint16_t grl_flags
Definition: nxpfs85xx.h:71
uint16_t intb_mask
Definition: nxpfs85xx.h:85
uint16_t iFailSafeSateMachine
Definition: nxpfs85xx.h:76
uint16_t i_svs
Definition: nxpfs85xx.h:77
uint16_t i_safe_inputs
Definition: nxpfs85xx.h:75
uint16_t states
Definition: nxpfs85xx.h:86
uint16_t watchdogWindow
Definition: nxpfs85xx.h:78
uint16_t safeIos
Definition: nxpfs85xx.h:83
uint16_t iOvervoltageUndervolateSafeReaction1
Definition: nxpfs85xx.h:72
uint16_t watchdogSeed
Definition: nxpfs85xx.h:79
uint16_t overvoltageUndervoltageRegisterStatus
Definition: nxpfs85xx.h:81
uint16_t int_mask2
Definition: nxpfs85xx.h:99
uint16_t int_mask1
Definition: nxpfs85xx.h:98
uint16_t registerControl1
Definition: nxpfs85xx.h:94
uint16_t analogMultiplexer
Definition: nxpfs85xx.h:96
uint16_t registerControl2
Definition: nxpfs85xx.h:95
FS85X_FS_REGISTER_s fsRegister
Definition: nxpfs85xx.h:134
FS85X_MAIN_REGISTERS_s mainRegister
Definition: nxpfs85xx.h:133
SPI_INTERFACE_CONFIG_s * pSpiInterface
Definition: nxpfs85xx.h:130
SBC_NVRAM_INFO_s nvram
Definition: nxpfs85xx.h:135
FS85X_OPERATION_MODE_e mode
Definition: nxpfs85xx.h:136
fs8x_drv_data_t configValues
Definition: nxpfs85xx.h:131
FS85X_FIN_CONFIGURATION_s fin
Definition: nxpfs85xx.h:132
FRAM_BLOCK_ID_e entry
Definition: nxpfs85xx.h:124
FRAM_SBC_INIT_s * data
Definition: nxpfs85xx.h:125
This data structure is used by the FS8x driver (this is the first parameter of most the FS8x function...