foxBMS - Unit Tests  1.4.0
The foxBMS Unit Tests API Documentation
bal.c
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 bal.c
44  * @author foxBMS Team
45  * @date 2020-02-24 (date of creation)
46  * @updated 2022-07-28 (date of last update)
47  * @version v1.4.0
48  * @ingroup APPLICATION
49  * @prefix BAL
50  *
51  * @brief Driver for the Balancing module
52  *
53  */
54 
55 /*========== Includes =======================================================*/
56 #include "bal.h"
57 
58 /*========== Macros and Definitions =========================================*/
59 
60 /*========== Static Constant and Variable Definitions =======================*/
61 
62 /*========== Extern Constant and Variable Definitions =======================*/
63 
64 /*========== Static Function Prototypes =====================================*/
65 
66 /*========== Static Function Implementations ================================*/
67 
68 /*========== Extern Function Implementations ================================*/
69 #pragma WEAK(BAL_SaveLastStates)
70 extern void BAL_SaveLastStates(BAL_STATE_s *pBalancingState) {
71  FAS_ASSERT(pBalancingState != NULL_PTR);
72  if (pBalancingState->lastState != pBalancingState->state) {
73  pBalancingState->lastState = pBalancingState->state;
74  pBalancingState->lastSubstate = pBalancingState->substate;
75  } else if (pBalancingState->lastSubstate != pBalancingState->substate) {
76  pBalancingState->lastSubstate = pBalancingState->substate;
77  } else {
78  /* Do not set new substate as nothing changed */
79  ;
80  }
81 }
82 
83 #pragma WEAK(BAL_CheckReEntrance)
84 extern uint8_t BAL_CheckReEntrance(BAL_STATE_s *currentState) {
85  FAS_ASSERT(currentState != NULL_PTR);
86  uint8_t retval = 0;
87 
89  if (!currentState->triggerEntry) {
90  currentState->triggerEntry++;
91  } else {
92  retval = 0xFF; /* multiple calls of function */
93  }
95 
96  return retval;
97 }
98 
99 #pragma WEAK(BAL_TransferStateRequest)
101  FAS_ASSERT(currentState != NULL_PTR);
103 
105  retval = currentState->stateRequest;
106  currentState->stateRequest = BAL_STATE_NO_REQUEST;
108 
109  return retval;
110 }
111 
112 #pragma WEAK(BAL_CheckStateRequest)
114  FAS_ASSERT(pCurrentState != NULL_PTR);
115  if (stateRequest == BAL_STATE_ERROR_REQUEST) {
116  return BAL_OK;
117  }
118  if (stateRequest == BAL_STATE_GLOBAL_ENABLE_REQUEST) {
119  pCurrentState->balancingGlobalAllowed = true;
120  return BAL_OK;
121  }
122  if (stateRequest == BAL_STATE_GLOBAL_DISABLE_REQUEST) {
123  pCurrentState->balancingGlobalAllowed = false;
124  return BAL_OK;
125  }
126  if ((stateRequest == BAL_STATE_NO_BALANCING_REQUEST) || (stateRequest == BAL_STATE_ALLOWBALANCING_REQUEST)) {
127  return BAL_OK;
128  }
129 
130  if (pCurrentState->stateRequest == BAL_STATE_NO_REQUEST) {
131  /* init only allowed from the uninitialized state */
132  if (stateRequest == BAL_STATE_INIT_REQUEST) {
133  if (pCurrentState->state == BAL_STATEMACH_UNINITIALIZED) {
134  return BAL_OK;
135  } else {
137  }
138  /* request to forbid balancing */
139  } else {
140  return BAL_ILLEGAL_REQUEST;
141  }
142  } else {
143  return BAL_REQUEST_PENDING;
144  }
145 }
146 
147 #pragma WEAK(BAL_Init)
149  FAS_ASSERT(pControl != NULL_PTR);
150  DATA_READ_DATA(pControl);
151  pControl->enableBalancing = 0;
152  DATA_WRITE_DATA(pControl);
153  return STD_OK;
154 }
155 
156 #pragma WEAK(BAL_ProcessStateUninitalized)
157 extern void BAL_ProcessStateUninitalized(BAL_STATE_s *pCurrentState, BAL_STATE_REQUEST_e stateRequest) {
158  FAS_ASSERT(pCurrentState != NULL_PTR);
159  if (stateRequest == BAL_STATE_INIT_REQUEST) {
160  pCurrentState->timer = BAL_STATEMACH_SHORTTIME_100ms;
161  pCurrentState->state = BAL_STATEMACH_INITIALIZATION;
162  pCurrentState->substate = BAL_ENTRY;
163  } else if (stateRequest == BAL_STATE_NO_REQUEST) {
164  /* no actual request pending */
165  } else {
166  pCurrentState->errorRequestCounter++; /* illegal request pending */
167  }
168 }
169 
170 #pragma WEAK(BAL_ProcessStateInitialization)
171 extern void BAL_ProcessStateInitialization(BAL_STATE_s *currentState) {
172  FAS_ASSERT(currentState != NULL_PTR);
173  currentState->timer = BAL_STATEMACH_SHORTTIME_100ms;
174  currentState->state = BAL_STATEMACH_INITIALIZED;
175  currentState->substate = BAL_ENTRY;
176 }
177 
178 #pragma WEAK(BAL_ProcessStateInitialized)
179 extern void BAL_ProcessStateInitialized(BAL_STATE_s *currentState) {
180  FAS_ASSERT(currentState != NULL_PTR);
181  currentState->initializationFinished = STD_OK;
182  currentState->timer = BAL_STATEMACH_SHORTTIME_100ms;
183  currentState->state = BAL_STATEMACH_CHECK_BALANCING;
184  currentState->substate = BAL_ENTRY;
185 }
186 
187 /*========== Externalized Static Function Implementations (Unit Test) =======*/
188 
189 /*========== Getter for static Variables (Unit Test) ========================*/
STD_RETURN_TYPE_e BAL_Init(DATA_BLOCK_BALANCING_CONTROL_s *pControl)
Generic initialization function for the balancing module.
Definition: bal.c:148
void BAL_SaveLastStates(BAL_STATE_s *pBalancingState)
Saves the last state and the last substate.
Definition: bal.c:70
void BAL_ProcessStateInitialization(BAL_STATE_s *currentState)
State machine subfunction to initialize the balancing state machine.
Definition: bal.c:171
void BAL_ProcessStateUninitalized(BAL_STATE_s *pCurrentState, BAL_STATE_REQUEST_e stateRequest)
Substate handling function for BAL_Trigger()
Definition: bal.c:157
BAL_STATE_REQUEST_e BAL_TransferStateRequest(BAL_STATE_s *currentState)
transfers the current state request to the state machine.
Definition: bal.c:100
void BAL_ProcessStateInitialized(BAL_STATE_s *currentState)
State machine subfunction to transfer from an initalized state to "running" states of th state machin...
Definition: bal.c:179
uint8_t BAL_CheckReEntrance(BAL_STATE_s *currentState)
re-entrance check of BAL state machine trigger function
Definition: bal.c:84
BAL_RETURN_TYPE_e BAL_CheckStateRequest(BAL_STATE_s *pCurrentState, BAL_STATE_REQUEST_e stateRequest)
checks the state requests that are made.
Definition: bal.c:113
Header for the driver for balancing.
BAL_RETURN_TYPE_e
Definition: bal.h:113
@ BAL_ALREADY_INITIALIZED
Definition: bal.h:121
@ BAL_OK
Definition: bal.h:114
@ BAL_ILLEGAL_REQUEST
Definition: bal.h:117
@ BAL_REQUEST_PENDING
Definition: bal.h:116
BAL_STATE_REQUEST_e
Definition: bal.h:100
@ BAL_STATE_GLOBAL_ENABLE_REQUEST
Definition: bal.h:106
@ BAL_STATE_ERROR_REQUEST
Definition: bal.h:102
@ BAL_STATE_NO_REQUEST
Definition: bal.h:107
@ BAL_STATE_ALLOWBALANCING_REQUEST
Definition: bal.h:104
@ BAL_STATE_NO_BALANCING_REQUEST
Definition: bal.h:103
@ BAL_STATE_INIT_REQUEST
Definition: bal.h:101
@ BAL_STATE_GLOBAL_DISABLE_REQUEST
Definition: bal.h:105
@ BAL_STATEMACH_UNINITIALIZED
Definition: bal.h:71
@ BAL_STATEMACH_INITIALIZATION
Definition: bal.h:72
@ BAL_STATEMACH_INITIALIZED
Definition: bal.h:73
@ BAL_STATEMACH_CHECK_BALANCING
Definition: bal.h:74
@ BAL_ENTRY
Definition: bal.h:89
#define BAL_STATEMACH_SHORTTIME_100ms
Definition: bal_cfg.h:64
#define DATA_READ_DATA(...)
Definition: database.h:83
#define DATA_WRITE_DATA(...)
Definition: database.h:93
#define FAS_ASSERT(x)
Assertion macro that asserts that x is true.
Definition: fassert.h:248
STD_RETURN_TYPE_e
Definition: fstd_types.h:81
@ STD_OK
Definition: fstd_types.h:82
#define NULL_PTR
Null pointer.
Definition: fstd_types.h:76
void OS_ExitTaskCritical(void)
Exit Critical interface function for use in FreeRTOS-Tasks and FreeRTOS-ISR.
Definition: os_freertos.c:135
void OS_EnterTaskCritical(void)
Enter Critical interface function for use in FreeRTOS-Tasks and FreeRTOS-ISR.
Definition: os_freertos.c:131
uint32_t errorRequestCounter
Definition: bal.h:137
BAL_STATE_REQUEST_e stateRequest
Definition: bal.h:131
STD_RETURN_TYPE_e initializationFinished
Definition: bal.h:138
uint8_t lastSubstate
Definition: bal.h:135
uint8_t triggerEntry
Definition: bal.h:136
BAL_STATEMACH_e lastState
Definition: bal.h:134
bool balancingGlobalAllowed
Definition: bal.h:142
BAL_STATEMACH_SUB_e substate
Definition: bal.h:133
uint16_t timer
Definition: bal.h:130
BAL_STATEMACH_e state
Definition: bal.h:132