foxBMS-UnitTests  1.0.0
The foxBMS Unit Tests API Documentation
diag.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 diag.h
44  * @author foxBMS Team
45  * @date 2019-11-28 (date of creation)
46  * @updated 2019-12-10 (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 Prints contents of the error buffer on user request.
153  */
154 extern void DIAG_PrintErrors(void);
155 
156 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
157 
158 #endif /* FOXBMS__DIAG_H_ */
DIAG_IMPACT_LEVEL_e
enum DIAG_IMPACT_LEVEL DIAG_IMPACT_LEVEL_e
DIAG_HANDLER_RETURN_OK
@ DIAG_HANDLER_RETURN_OK
Definition: diag.h:64
DIAG_STATE_INITIALIZED
@ DIAG_STATE_INITIALIZED
Definition: diag.h:80
diag_cfg.h
Diagnostic module configuration header.
STD_RETURN_TYPE_e
enum STD_RETURN_TYPE STD_RETURN_TYPE_e
DIAG_HANDLER_INVALID_TYPE
@ DIAG_HANDLER_INVALID_TYPE
Definition: diag.h:69
DIAG::state
DIAG_STATE_e state
Definition: diag.h:85
DIAG
Definition: diag.h:84
DIAG_HANDLER_INVALID_ERR_IMPACT
@ DIAG_HANDLER_INVALID_ERR_IMPACT
Definition: diag.h:71
DIAG::err_enableflag
uint32_t err_enableflag[(DIAG_ID_MAX+31)/32]
Definition: diag.h:95
DIAG_s
struct DIAG DIAG_s
DIAG::id2ch
uint8_t id2ch[DIAG_ID_MAX]
Definition: diag.h:91
DIAG_PrintErrors
void DIAG_PrintErrors(void)
Prints contents of the error buffer on user request.
Definition: diag.c:161
DIAG_STATE_UNINITIALIZED
@ DIAG_STATE_UNINITIALIZED
Definition: diag.h:79
DIAG::warnflag
uint32_t warnflag[(DIAG_ID_MAX+31)/32]
Definition: diag.h:94
DIAG_ID_e
enum DIAG_ID DIAG_ID_e
DIAG_HANDLER_RETURN_UNKNOWN
@ DIAG_HANDLER_RETURN_UNKNOWN
Definition: diag.h:68
DIAG::errflag
uint32_t errflag[(DIAG_ID_MAX+31)/32]
Definition: diag.h:93
DIAG_STATE_e
DIAG_STATE_e
Definition: diag.h:78
DIAG::errcnttotal
uint16_t errcnttotal
Definition: diag.h:86
DIAG::entry_event
uint32_t entry_event[DIAG_ID_MAX]
Definition: diag.h:88
DIAG_CheckEvent
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:326
DIAG_HANDLER_RETURN_NOT_READY
@ DIAG_HANDLER_RETURN_NOT_READY
Definition: diag.h:72
DIAG_EVENT_e
enum DIAG_EVENT DIAG_EVENT_e
DIAG::nr_of_ch
uint8_t nr_of_ch
Definition: diag.h:92
DIAG_HANDLER_RETURN_ERR_OCCURRED
@ DIAG_HANDLER_RETURN_ERR_OCCURRED
Definition: diag.h:65
DIAG_RETURNTYPE_e
enum DIAG_RETURNTYPE DIAG_RETURNTYPE_e
DIAG::entry_cnt
uint8_t entry_cnt[DIAG_ID_MAX]
Definition: diag.h:89
DIAG_DEV
Definition: diag_cfg.h:276
DIAG_RETURNTYPE
DIAG_RETURNTYPE
Definition: diag.h:63
DIAG_HANDLER_RETURN_WRONG_ID
@ DIAG_HANDLER_RETURN_WRONG_ID
Definition: diag.h:67
DIAG_Handler
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:199
DIAG::occurrenceCounter
uint16_t occurrenceCounter[BS_NR_OF_STRINGS][DIAG_ID_MAX]
Definition: diag.h:90
DIAG_HANDLER_RETURN_WARNING_OCCURRED
@ DIAG_HANDLER_RETURN_WARNING_OCCURRED
Definition: diag.h:66
BS_NR_OF_STRINGS
#define BS_NR_OF_STRINGS
Definition: battery_system_cfg.h:89
DIAG::errcntreported
uint16_t errcntreported
Definition: diag.h:87
DIAG_HANDLER_INVALID_DATA
@ DIAG_HANDLER_INVALID_DATA
Definition: diag.h:70
DIAG_Initialize
STD_RETURN_TYPE_e DIAG_Initialize(DIAG_DEV_s *diag_dev_pointer)
DIAG_Init initializes all needed structures/buffers.
Definition: diag.c:111
DIAG_ID_MAX
@ DIAG_ID_MAX
Definition: diag_cfg.h:196