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