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