foxBMS  1.3.0
The foxBMS Battery Management System API Documentation
diag.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 diag.h
44  * @author foxBMS Team
45  * @date 2019-11-28 (date of creation)
46  * @updated 2022-05-30 (date of last update)
47  * @version v1.3.0
48  * @ingroup ENGINE
49  * @prefix DIAG
50  *
51  * @brief Diagnosis driver header
52  *
53  */
54 
55 #ifndef FOXBMS__DIAG_H_
56 #define FOXBMS__DIAG_H_
57 
58 /*========== Includes =======================================================*/
59 #include "diag_cfg.h"
60 
61 /*========== Macros and Definitions =========================================*/
62 
63 /** diagnosis handler return types */
64 typedef enum {
65  DIAG_HANDLER_RETURN_OK, /*!< error not occurred or occurred but threshold not reached */
66  DIAG_HANDLER_RETURN_ERR_OCCURRED, /*!< error occurred and enabled */
67  DIAG_HANDLER_RETURN_WARNING_OCCURRED, /*!< warning occurred (error occurred but not enabled) */
68  DIAG_HANDLER_RETURN_WRONG_ID, /*!< wrong diagnosis id */
69  DIAG_HANDLER_RETURN_UNKNOWN, /*!< unknown return type */
70  DIAG_HANDLER_INVALID_TYPE, /*!< invalid diagnosis type, error in configuration */
71  DIAG_HANDLER_INVALID_DATA, /*!< invalid data, dependent of the diagHandler */
72  DIAG_HANDLER_INVALID_ERR_IMPACT, /*!< event neither string nor system level related */
73  DIAG_HANDLER_RETURN_NOT_READY, /*!< diagnosis handler not ready */
75 
76 /** possible states of the diagnosis module */
77 typedef enum {
78  DIAG_STATE_UNINITIALIZED, /*!< diagnosis module not initialized */
79  DIAG_STATE_INITIALIZED, /*!< diagnosis module initialized (ready for use) */
81 
82 /** central state struct of the diag module */
83 typedef struct {
84  DIAG_MODULE_STATE_e state; /*!< actual state of diagnosis module */
85  uint16_t errcnttotal; /*!< total counts of diagnosis entry records*/
86  uint16_t errcntreported; /*!< reported error counts to external tool*/
87  uint32_t entry_event[DIAG_ID_MAX]; /*!< last detected entry event*/
88  uint8_t entry_cnt[DIAG_ID_MAX]; /*!< reported event counter used for limitation */
89  uint16_t occurrenceCounter[BS_NR_OF_STRINGS][DIAG_ID_MAX]; /*!< counter for the occurrence of diag events */
90  uint8_t id2ch[DIAG_ID_MAX]; /*!< diagnosis-id to configuration channel selector*/
91  uint8_t nrOfConfiguredDiagnosisEntries; /*!< number of configured diagnosis entries */
92  uint32_t errflag[(DIAG_ID_MAX + 31) / 32]; /*!< detected error flags (bit_nr = diag_id) */
93  uint32_t warnflag[(DIAG_ID_MAX + 31) / 32]; /*!< detected warning flags (bit_nr = diag_id) */
94  uint32_t err_enableflag[(DIAG_ID_MAX + 31) / 32]; /*!< enabled error flags (bit_nr = diag_id) */
96 
97 /*========== Extern Constant and Variable Declarations ======================*/
98 
99 /*========== Extern Function Prototypes =====================================*/
100 
101 /**
102  * @brief DIAG_Handler provides generic error handling, based on diagnosis
103  * group.
104  * @details This function calls the handler functions depending on the
105  * diagnosis group of call. It needs to get called in every function
106  * which wants to apply some kind of diagnosis handling. According to
107  * its return value further treatment is either left to the calling
108  * module itself, or can be done in the callback function defined in
109  * diag_cfg.c
110  * @ingroup API_DIAG
111  * @param diag_id #DIAG_ID_e of the event that has occurred
112  * @param event event that occurred (OK, NOK, RESET)
113  * @param impact #DIAG_IMPACT_LEVEL_e of #DIAG_ID_e
114  * @param data individual information for #DIAG_ID_e e.g. string number,..
115  * @return #DIAG_HANDLER_RETURN_UNKNOWN if invalid #DIAG_EVENT_e, otherwise
116  * return value of #DIAG_RETURNTYPE_e
117  */
118 extern DIAG_RETURNTYPE_e DIAG_Handler(DIAG_ID_e diag_id, DIAG_EVENT_e event, DIAG_IMPACT_LEVEL_e impact, uint32_t data);
119 
120 /**
121  * @brief DIAG_CheckEvent provides a simple interface to check an event for
122  * #STD_OK
123  * @details DIAG_CheckEvent is a wrapper function for #DIAG_Handler(). In simple
124  * cases where a return value that is not #STD_OK (or a 0 casted to
125  * #STD_OK) should increase the error counter in a diagnosis channel,
126  * this function should be used instead of directly calling the
127  * #DIAG_Handler().
128  * @param cond condition
129  * @param diag_id event ID of the event that has occurred
130  * @param impact #DIAG_IMPACT_LEVEL_e of #DIAG_ID_e
131  * @param data individual information for #DIAG_ID_e e.g. string number,..
132  * @return STD_OK if ok, STD_NOT_OK if not ok
133  */
135  STD_RETURN_TYPE_e cond,
136  DIAG_ID_e diag_id,
137  DIAG_IMPACT_LEVEL_e impact,
138  uint32_t data);
139 
140 /**
141  * @brief DIAG_Init initializes all needed structures/buffers.
142  * @details This function provides initialization of the diagnose module. In
143  * case of miss behaviour it calls Reset and adds an entry into
144  * database to ensure data validity/report back malfunction
145  * @param diag_dev_pointer
146  * @return #STD_OK if ok, #STD_NOT_OK if not ok
147  */
148 extern STD_RETURN_TYPE_e DIAG_Initialize(DIAG_DEV_s *diag_dev_pointer);
149 
150 /**
151  * @brief Checks if passed diagnosis entry has been triggered or not
152  * @param diagnosisEntry event ID of diagnosis entry
153  * @return #STD_OK if diagnosis entry has not surpassed error threshold, otherwise #STD_NOT_OK
154  */
156 
157 /**
158  * @brief Prints contents of the error buffer on user request.
159  */
160 extern void DIAG_PrintErrors(void);
161 
162 /**
163  * @brief Get configured delay of passed diagnosis entry
164  * @param diagnosisEntry event ID of diagnosis entry
165  * @return configured delay in ms
166  */
167 extern uint32_t DIAG_GetDelay(DIAG_ID_e diagnosisEntry);
168 
169 /**
170  * @brief Check if any fatal error is set
171  * @return true, if a diagnosis entry with severity #DIAG_FATAL_ERROR is set,
172  * otherwise false
173  */
174 extern bool DIAG_IsAnyFatalErrorSet(void);
175 
176 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
177 
178 #endif /* FOXBMS__DIAG_H_ */
#define BS_NR_OF_STRINGS
Number of parallel strings in the battery pack.
DIAG_MODULE_STATE_e
Definition: diag.h:77
@ DIAG_STATE_UNINITIALIZED
Definition: diag.h:78
@ DIAG_STATE_INITIALIZED
Definition: diag.h:79
DIAG_RETURNTYPE_e
Definition: diag.h:64
@ DIAG_HANDLER_RETURN_NOT_READY
Definition: diag.h:73
@ DIAG_HANDLER_INVALID_DATA
Definition: diag.h:71
@ DIAG_HANDLER_RETURN_WRONG_ID
Definition: diag.h:68
@ DIAG_HANDLER_INVALID_TYPE
Definition: diag.h:70
@ DIAG_HANDLER_RETURN_WARNING_OCCURRED
Definition: diag.h:67
@ DIAG_HANDLER_RETURN_ERR_OCCURRED
Definition: diag.h:66
@ DIAG_HANDLER_INVALID_ERR_IMPACT
Definition: diag.h:72
@ DIAG_HANDLER_RETURN_OK
Definition: diag.h:65
@ DIAG_HANDLER_RETURN_UNKNOWN
Definition: diag.h:69
uint32_t DIAG_GetDelay(DIAG_ID_e diagnosisEntry)
Get configured delay of passed diagnosis entry.
Definition: diag.c:372
void DIAG_PrintErrors(void)
Prints contents of the error buffer on user request.
Definition: diag.c:191
STD_RETURN_TYPE_e DIAG_GetDiagnosisEntryState(DIAG_ID_e diagnosisEntry)
Checks if passed diagnosis entry has been triggered or not.
Definition: diag.c:175
bool DIAG_IsAnyFatalErrorSet(void)
Check if any fatal error is set.
Definition: diag.c:377
DIAG_RETURNTYPE_e DIAG_Handler(DIAG_ID_e diag_id, DIAG_EVENT_e event, DIAG_IMPACT_LEVEL_e impact, uint32_t data)
DIAG_Handler provides generic error handling, based on diagnosis group.
Definition: diag.c:229
STD_RETURN_TYPE_e DIAG_Initialize(DIAG_DEV_s *diag_dev_pointer)
DIAG_Init initializes all needed structures/buffers.
Definition: diag.c:112
STD_RETURN_TYPE_e DIAG_CheckEvent(STD_RETURN_TYPE_e cond, DIAG_ID_e diag_id, DIAG_IMPACT_LEVEL_e impact, uint32_t data)
DIAG_CheckEvent provides a simple interface to check an event for STD_OK.
Definition: diag.c:356
Diagnostic module configuration header.
DIAG_EVENT_e
Definition: diag_cfg.h:237
DIAG_IMPACT_LEVEL_e
Definition: diag_cfg.h:250
DIAG_ID_e
Definition: diag_cfg.h:157
@ DIAG_ID_MAX
Definition: diag_cfg.h:233
STD_RETURN_TYPE_e
Definition: fstd_types.h:81
uint16_t errcnttotal
Definition: diag.h:85
uint16_t errcntreported
Definition: diag.h:86
uint8_t nrOfConfiguredDiagnosisEntries
Definition: diag.h:91
DIAG_MODULE_STATE_e state
Definition: diag.h:84