foxBMS - Unit Tests  1.5.0
The foxBMS Unit Tests API Documentation
mxm_17841b.h
Go to the documentation of this file.
1 /**
2  *
3  * @copyright © 2010 - 2023, 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 mxm_17841b.h
44  * @author foxBMS Team
45  * @date 2018-12-14 (date of creation)
46  * @updated 2023-02-03 (date of last update)
47  * @version v1.5.0
48  * @ingroup DRIVERS
49  * @prefix MXM
50  *
51  * @brief Headers for the driver for the MAX17841B ASCI and
52  * MAX1785x analog front-end
53  *
54  * @details def
55  *
56  */
57 
58 #ifndef FOXBMS__MXM_17841B_H_
59 #define FOXBMS__MXM_17841B_H_
60 
61 /*========== Includes =======================================================*/
62 #include "mxm_cfg.h"
63 
64 #include "fstd_types.h"
65 #include "mxm_bitextract.h"
66 
67 #include <stdint.h>
68 
69 /*========== Macros and Definitions =========================================*/
70 
71 /**
72  * @brief SPI TX buffer length
73  *
74  * This define defines the length of the SPI TX buffer.
75  * This TX buffer is declared in #MXM_41B_INSTANCE_s::spiTXBuffer.
76  * The buffer has to be large enough to accommodate every
77  * relevant SPI transaction.
78  */
79 #define MXM_SPI_TX_BUFFER_LENGTH (10u)
80 
81 /** SPI RX buffer length */
82 #define MXM_SPI_RX_BUFFER_LENGTH (100u)
83 
84 /**
85  * @brief States of the MAX17841B state-machine
86  */
87 typedef enum {
88  MXM_STATEMACH_41B_UNINITIALIZED, /*!< Uninitialized state that the state-machine starts in */
89  MXM_STATEMACH_41B_INIT, /*!< Initialization sequence, afterwards transition into idle state */
90  MXM_STATEMACH_41B_IDLE, /*!< Idle state, transition into other states is available here */
91  MXM_STATEMACH_41B_CHECK_FMEA, /*!< Checks the FMEA register of MAX17841B. */
92  MXM_STATEMACH_41B_GET_VERSION, /*!< Retrieves the version of the connected ASCI. */
93  MXM_STATEMACH_41B_WRITE_CONF_AND_INT_REGISTER, /*!< Writes the copy of configuration and interrupt register to the MAX17841B. */
94  MXM_STATEMACH_41B_READ_STATUS_REGISTER, /*!< Reads the status registers of MAX17841B. */
95  MXM_STATEMACH_41B_UART_TRANSACTION, /*!< Sends a complete UART transaction. */
96  MXM_STATEMACH_41B_CLEAR_RECEIVE_BUFFER, /*!< Clears the receive buffer. */
97  MXM_STATEMACH_41B_CLEAR_TRANSMIT_BUFFER, /*!< Clears the transmit buffer */
98  MXM_STATEMACH_41B_MAXSTATE, /*!< Highest state */
100 
101 /**
102  * @brief Substates of the MAX17841B state-machine
103  */
104 typedef enum {
115  /* MXM_41B_UART_CLEAR_TRANSMIT_BUFFER, */
127 
128 /**
129  * @brief Request status of MAX17841B states.
130  *
131  * This enum describes the states that a state in the
132  * #MXM_41BStateMachine() can have.
133  */
134 typedef enum {
135  MXM_41B_STATE_UNSENT, /*!< The request has not been sent to the state-machine yet. */
136  MXM_41B_STATE_UNPROCESSED, /*!< The request has been received by the state-machine, but not been processed yet. */
137  MXM_41B_STATE_PROCESSED, /*!< The request has been process successfully */
138  MXM_41B_STATE_ERROR, /*!< An error has occurred during processing of the request. */
140 
141 /**
142  * @brief Register functions
143  */
144 typedef enum {
145  MXM_41B_REG_FUNCTION_RX_BUSY_STATUS, /*!< read the rx busy bit from rx status register */
146  MXM_41B_REG_FUNCTION_RX_OVERFLOW_STATUS, /*!< read the rx overflow bit from rx status register */
147  MXM_41B_REG_FUNCTION_RX_STOP_STATUS, /*!< read the rx stop bit from rx status register */
148  MXM_41B_REG_FUNCTION_RX_EMPTY_STATUS, /*!< read the rx empty bit from rx status register */
149  MXM_41B_REG_FUNCTION_TX_PREAMBLES, /*!< set the tx preambles bit */
150  MXM_41B_REG_FUNCTION_KEEP_ALIVE, /*!< set the keep alive bits */
151  MXM_41B_REG_FUNCTION_RX_ERROR_INT, /*!< read the rx error bit */
154 
155 /**
156  * @brief Struct for the state-variable of state-machine
157  *
158  * This struct defines the state-variable of
159  * the #MXM_41BStateMachine().
160  */
161 typedef struct {
162  MXM_STATEMACH_41B_e state; /*!< state of Driver State Machine */
163  MXM_41B_SUBSTATES_e substate; /*!< substate of current Driver State */
164  uint16_t *pPayload; /*!< payload that is processed by the state-machine */
165  uint8_t payloadLength; /*!< length of the payload array */
166  uint16_t *pRxBuffer; /*!< pointer to an RX-buffer that will be filled by the state-machine */
167  uint16_t rxBufferLength; /*!< length of the RX-buffer-array */
168  MXM_41B_STATE_REQUEST_STATUS_e *processed; /*!< status-indicator of the state-machine */
169  uint8_t extendMessageBytes; /*!< pass on number of bytes by which the TX-message shall be extended */
170  uint8_t waitCounter; /*!< general error counter, will be reset in funtions */
171  uint8_t regRXIntEnable; /*!< local storage for the RX Interrupt Enable register */
172  uint8_t regTXIntEnable; /*!< local storage for the TX Interrupt Enable register */
173  uint8_t regRXStatus; /*!< local storage for the RX Status register */
174  uint8_t regTXStatus; /*!< local storage for the TX status register */
175  uint8_t regConfig1; /*!< local storage for the Config 1 register */
176  uint8_t regConfig2; /*!< local storage for the Config 2 register */
177  uint8_t regConfig3; /*!< local storage for the Config 3 register */
178  uint8_t regRxSpace; /*!< RX space register (shows the left space in RX buffer) */
179  uint8_t regFmea; /*!< FMEA register */
180  uint16_t hwModel; /*!< model number of the connected IC */
181  uint8_t hwMaskRevision; /*!< mask revision of the connected IC */
182  uint32_t shutdownTimeStamp; /*!< timestamp of the last shutdown (or startup) action */
183  uint16_t spiRXBuffer[MXM_SPI_RX_BUFFER_LENGTH]; /*!< rx buffer for SPI */
184  uint16_t spiTXBuffer[MXM_SPI_TX_BUFFER_LENGTH]; /*!< tx buffer for SPI */
186 
187 /*========== Extern Constant and Variable Declarations ======================*/
188 
189 /*========== Extern Function Prototypes =====================================*/
190 /**
191  * @brief Write a register function
192  *
193  * Functions of the ASCI are mapped onto parts of the register.
194  * This function is used to write the proper values into the register copy
195  * of the ASCI that is inside the driver.
196  * In order to use the function, provide the name of the ASCI function that you
197  * want to write (#MXM_41B_REG_FUNCTION_e) and the value that
198  * should be written (#MXM_41B_REG_BIT_VALUE).
199  * Currently, only a relevant subset of the ASCI features is implemented.
200  *
201  * After updating the register copy, it has to be written to the ASCI memory.
202  * For the configuration registers this is done with the function
203  * MXM_41BConfigRegisterWrite(). This function is for example called
204  * in state #MXM_STATEMACH_41B_WRITE_CONF_AND_INT_REGISTER.
205  *
206  * @param[in,out] pInstance pointer to the state of the
207  * MAX17841B-state-machine
208  * @param[in] registerFunction name of the function that shall be
209  * written
210  * @param[in] value value of the bits that shall be written
211  * @return #STD_NOT_OK for unknown or unimplemented register
212  * functions, otherwise #STD_OK
213  */
215  MXM_41B_INSTANCE_s *pInstance,
216  MXM_41B_REG_FUNCTION_e registerFunction,
217  MXM_41B_REG_BIT_VALUE value);
218 
219 /**
220  * @brief Read the value of a register function
221  *
222  * Corresponding read-function to MXM_41BWriteRegisterFunction().
223  * This function reads a value from the register-copy of MAX17841B and writes
224  * it into a supplied pointer.
225  * The register function is specified by the
226  * corresponding #MXM_41B_REG_FUNCTION_e value.
227  *
228  * This function implements only the needed subset of register functions.
229  *
230  * @param[in,out] kpkInstance pointer to the state of the
231  * MAX17841B-state-machine
232  * @param[in] registerFunction name of the function that shall be
233  * written
234  * @param[out] pValue pointer to a variable in which the bits
235  * shall be written
236  * @return #STD_NOT_OK for unknown or unimplemented register function,
237  * otherwise #STD_OK
238  */
240  const MXM_41B_INSTANCE_s *const kpkInstance,
241  MXM_41B_REG_FUNCTION_e registerFunction,
242  MXM_41B_REG_BIT_VALUE *pValue);
243 
244 /**
245  * @brief Execute state-machine for the MAX17841B.
246  *
247  * This function executes the state-machine that communicates
248  * with the MAX17841B over SPI.
249  */
250 extern void MXM_41BStateMachine(MXM_41B_INSTANCE_s *pInstance);
251 
252 /**
253  * @brief Set state transition for MAX17841B-state-machine.
254  *
255  * This function is used to transition into another state of the
256  * state-machine which is handled in MXM_41BStateMachine().
257  * The user sets a state that should be transitioned into.
258  * For most states a payload and a payload-length can be supplied.
259  * The payload-length has to be consistent with the length in payload.
260  * Typically, this supplied payload describes the byte-sequence that
261  * should be written into the load-queue.
262  *
263  * For the case of a e.g. READALL-command the message-length has to
264  * be stretched by the number of connected monitoring ICs times two.
265  * This is achieved by passing on extendMessageBytes.
266  *
267  * In case that the state generates data that has to be handled in the
268  * higher layers, the pointer pRxBuffer will be used. Please make sure that
269  * the length of pRxBuffer is also consistent.
270  *
271  * In order to determine success or failure of the requested state,
272  * the higher layer supplies a pointer into which the current status
273  * of the requested state will be written.
274  *
275  * @param[in,out] pInstance pointer to the state of the
276  * MAX17841B-state-machine
277  * @param[in] state state into which the state-machine
278  * shall transition
279  * @param[in] pPayload pointer to an array with data that will
280  * be processed in the requested state
281  * @param[in] payloadLength length of the payload-array
282  * @param[in] extendMessageBytes number of bytes that shall be appended
283  * by the ASCI
284  * @param[out] pRxBuffer pointer to an array that will be filled
285  * by the requested state with data that
286  * has to be processed in higher layers
287  * @param[in] rxBufferLength length of the RX buffer array
288  * @param[out] processed pointer of the status of the requested
289  * state
290  * @return #STD_NOT_OK for inconsistent input or forbidden state
291  * transitions, otherwise #STD_OK
292  */
294  MXM_41B_INSTANCE_s *pInstance,
295  MXM_STATEMACH_41B_e state,
296  uint16_t *pPayload,
297  uint8_t payloadLength,
298  uint8_t extendMessageBytes,
299  uint16_t *pRxBuffer,
300  uint16_t rxBufferLength,
301  MXM_41B_STATE_REQUEST_STATUS_e *processed);
302 
303 /**
304  * @brief Initializes the state struct with default values
305  * @details This function is called through the startup of the driver in order
306  * to ensure proper default values.
307  * @param[out] pInstance instance of the state struct that shall be initialized
308  */
309 extern void MXM_41BInitializeStateStruct(MXM_41B_INSTANCE_s *pInstance);
310 
311 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
312 #ifdef UNITY_UNIT_TEST
313 #endif
314 
315 #endif /* FOXBMS__MXM_17841B_H_ */
Definition of foxBMS standard types.
STD_RETURN_TYPE_e
Definition: fstd_types.h:82
STD_RETURN_TYPE_e MXM_41BSetStateRequest(MXM_41B_INSTANCE_s *pInstance, MXM_STATEMACH_41B_e state, uint16_t *pPayload, uint8_t payloadLength, uint8_t extendMessageBytes, uint16_t *pRxBuffer, uint16_t rxBufferLength, MXM_41B_STATE_REQUEST_STATUS_e *processed)
Set state transition for MAX17841B-state-machine.
Definition: mxm_17841b.c:788
void MXM_41BStateMachine(MXM_41B_INSTANCE_s *pInstance)
Execute state-machine for the MAX17841B.
Definition: mxm_17841b.c:931
#define MXM_SPI_TX_BUFFER_LENGTH
SPI TX buffer length.
Definition: mxm_17841b.h:79
STD_RETURN_TYPE_e MXM_41BWriteRegisterFunction(MXM_41B_INSTANCE_s *pInstance, MXM_41B_REG_FUNCTION_e registerFunction, MXM_41B_REG_BIT_VALUE value)
Write a register function.
Definition: mxm_17841b.c:850
MXM_STATEMACH_41B_e
States of the MAX17841B state-machine.
Definition: mxm_17841b.h:87
@ MXM_STATEMACH_41B_MAXSTATE
Definition: mxm_17841b.h:98
@ MXM_STATEMACH_41B_GET_VERSION
Definition: mxm_17841b.h:92
@ MXM_STATEMACH_41B_CLEAR_RECEIVE_BUFFER
Definition: mxm_17841b.h:96
@ MXM_STATEMACH_41B_CLEAR_TRANSMIT_BUFFER
Definition: mxm_17841b.h:97
@ MXM_STATEMACH_41B_UNINITIALIZED
Definition: mxm_17841b.h:88
@ MXM_STATEMACH_41B_INIT
Definition: mxm_17841b.h:89
@ MXM_STATEMACH_41B_WRITE_CONF_AND_INT_REGISTER
Definition: mxm_17841b.h:93
@ MXM_STATEMACH_41B_CHECK_FMEA
Definition: mxm_17841b.h:91
@ MXM_STATEMACH_41B_READ_STATUS_REGISTER
Definition: mxm_17841b.h:94
@ MXM_STATEMACH_41B_IDLE
Definition: mxm_17841b.h:90
@ MXM_STATEMACH_41B_UART_TRANSACTION
Definition: mxm_17841b.h:95
MXM_41B_SUBSTATES_e
Substates of the MAX17841B state-machine.
Definition: mxm_17841b.h:104
@ MXM_41B_FMEA_REQUEST_REGISTER
Definition: mxm_17841b.h:111
@ MXM_41B_INIT_RESET_BRIDGE_IC
Definition: mxm_17841b.h:106
@ MXM_41B_UART_WAIT_FOR_RX_STATUS_CHANGE_WRITE
Definition: mxm_17841b.h:121
@ MXM_41B_VERSION_VERIFY
Definition: mxm_17841b.h:114
@ MXM_41B_UART_READ_RX_SPACE
Definition: mxm_17841b.h:116
@ MXM_41B_INIT_CHECK_INITIALIZATION
Definition: mxm_17841b.h:110
@ MXM_41B_FMEA_VERIFY
Definition: mxm_17841b.h:112
@ MXM_41B_UART_READ_BACK_RECEIVE_BUFFER_SAVE
Definition: mxm_17841b.h:123
@ MXM_41B_VERSION_REQUEST_REGISTER
Definition: mxm_17841b.h:113
@ MXM_41B_ENTRY_SUBSTATE
Definition: mxm_17841b.h:105
@ MXM_41B_UART_WRITE_LOAD_QUEUE
Definition: mxm_17841b.h:118
@ MXM_41B_UART_READ_LOAD_QUEUE
Definition: mxm_17841b.h:119
@ MXM_41B_INIT_START_BRIDGE_IC
Definition: mxm_17841b.h:107
@ MXM_41B_UART_READ_RX_SPACE_PARSE
Definition: mxm_17841b.h:117
@ MXM_41B_INIT_READ_CONFIG_REGISTERS
Definition: mxm_17841b.h:109
@ MXM_41B_UART_VERIFY_LOAD_QUEUE_AND_TRANSMIT
Definition: mxm_17841b.h:120
@ MXM_41B_READ_STATUS_REGISTER_SEND
Definition: mxm_17841b.h:124
@ MXM_41B_READ_STATUS_REGISTER_PROCESS
Definition: mxm_17841b.h:125
@ MXM_41B_INIT_WRITE_DEFAULT_VALUES
Definition: mxm_17841b.h:108
@ MXM_41B_UART_WAIT_FOR_RX_STATUS_CHANGE_READ_AND_READ_BACK_RCV_BUF
Definition: mxm_17841b.h:122
#define MXM_SPI_RX_BUFFER_LENGTH
Definition: mxm_17841b.h:82
void MXM_41BInitializeStateStruct(MXM_41B_INSTANCE_s *pInstance)
Initializes the state struct with default values.
Definition: mxm_17841b.c:977
STD_RETURN_TYPE_e MXM_41BReadRegisterFunction(const MXM_41B_INSTANCE_s *const kpkInstance, MXM_41B_REG_FUNCTION_e registerFunction, MXM_41B_REG_BIT_VALUE *pValue)
Read the value of a register function.
Definition: mxm_17841b.c:896
MXM_41B_REG_FUNCTION_e
Register functions.
Definition: mxm_17841b.h:144
@ MXM_41B_REG_FUNCTION_RX_BUSY_STATUS
Definition: mxm_17841b.h:145
@ MXM_41B_REG_FUNCTION_RX_EMPTY_STATUS
Definition: mxm_17841b.h:148
@ MXM_41B_REG_FUNCTION_RX_STOP_STATUS
Definition: mxm_17841b.h:147
@ MXM_41B_REG_FUNCTION_RX_OVERFLOW_STATUS
Definition: mxm_17841b.h:146
@ MXM_41B_REG_FUNCTION_TX_PREAMBLES
Definition: mxm_17841b.h:149
@ MXM_41B_REG_FUNCTION_RX_ERROR_INT
Definition: mxm_17841b.h:151
@ MXM_41B_REG_FUNCTION_KEEP_ALIVE
Definition: mxm_17841b.h:150
@ MXM_41B_REG_FUNCTION_RX_OVERFLOW_INT
Definition: mxm_17841b.h:152
MXM_41B_STATE_REQUEST_STATUS_e
Request status of MAX17841B states.
Definition: mxm_17841b.h:134
@ MXM_41B_STATE_UNSENT
Definition: mxm_17841b.h:135
@ MXM_41B_STATE_ERROR
Definition: mxm_17841b.h:138
@ MXM_41B_STATE_UNPROCESSED
Definition: mxm_17841b.h:136
@ MXM_41B_STATE_PROCESSED
Definition: mxm_17841b.h:137
Bit extraction function for MXM_17841b.
uint8_t MXM_41B_REG_BIT_VALUE
Bit-values for registers.
Header for the configuration for the Maxim analog front-end.
Struct for the state-variable of state-machine.
Definition: mxm_17841b.h:161
uint8_t regRXIntEnable
Definition: mxm_17841b.h:171
uint16_t * pRxBuffer
Definition: mxm_17841b.h:166
uint16_t * pPayload
Definition: mxm_17841b.h:164
uint8_t regTXIntEnable
Definition: mxm_17841b.h:172
uint8_t hwMaskRevision
Definition: mxm_17841b.h:181
uint16_t rxBufferLength
Definition: mxm_17841b.h:167
MXM_41B_STATE_REQUEST_STATUS_e * processed
Definition: mxm_17841b.h:168
uint32_t shutdownTimeStamp
Definition: mxm_17841b.h:182
MXM_41B_SUBSTATES_e substate
Definition: mxm_17841b.h:163
MXM_STATEMACH_41B_e state
Definition: mxm_17841b.h:162
uint8_t extendMessageBytes
Definition: mxm_17841b.h:169
uint8_t payloadLength
Definition: mxm_17841b.h:165