foxBMS-UnitTests  1.0.0
The foxBMS Unit Tests API Documentation
mxm_1785x_tools.c
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 mxm_1785x_tools.c
44  * @author foxBMS Team
45  * @date 2020-07-15 (date of creation)
46  * @updated 2020-07-15 (date of last update)
47  * @ingroup DRIVERS
48  * @prefix MXM
49  *
50  * @brief This is a collection of helper functions for the MAX1785x ICs
51  *
52  * @details This collection of helper functions for the MAX1785x ICs helps to
53  * calculate the lsb and msb for register values and similar tasks.
54  *
55  */
56 
57 /*========== Includes =======================================================*/
58 #include "mxm_1785x_tools.h"
59 
60 #include "mxm_register_map.h"
61 
62 /*========== Macros and Definitions =========================================*/
63 
64 /*========== Static Constant and Variable Definitions =======================*/
65 
66 /*========== Extern Constant and Variable Definitions =======================*/
67 
68 /*========== Static Function Prototypes =====================================*/
69 
70 /*========== Static Function Implementations ================================*/
71 
72 /*========== Extern Function Implementations ================================*/
73 extern uint8_t MXM_FirstSetBit(uint16_t bitmask) {
74  uint8_t retval = 0;
75  while (((bitmask >> retval) & 1u) == 0u) {
76  retval++;
77  /* exit if every entry is zero */
78  if (retval >= 16u) {
79  break;
80  }
81  }
82  return retval;
83 }
84 
85 extern STD_RETURN_TYPE_e must_check_return MXM_FirstSetBitTest() {
86  /* bitmasks containing only zeros should return first bit set 16 */
87  FAS_ASSERT(MXM_FirstSetBit(MXM_BM_NULL) == 16u);
88 
89  FAS_ASSERT(MXM_FirstSetBit(MXM_BM_LSB) == 0u);
90 
91  FAS_ASSERT(MXM_FirstSetBit(MXM_BM_MSB) == 8u);
92 
93  FAS_ASSERT(MXM_FirstSetBit(MXM_REG_VERSION_MOD) == 4u);
94 
95  return STD_OK;
96 }
97 
98 extern void MXM_Convert(
99  uint8_t lsb,
100  uint8_t msb,
101  uint16_t *pTarget,
102  MXM_CONVERSION_TYPE_e convType,
103  uint32_t fullScaleReference_mV) {
104  uint16_t temporaryVoltage = 0;
105  MXM_ExtractValueFromRegister(lsb, msb, MXM_REG_ADC_14BIT_VALUE, &temporaryVoltage);
106 
107  temporaryVoltage = temporaryVoltage + 1u;
108 
109  switch (convType) {
110  case MXM_CONVERSION_BIPOLAR:
111  /* not yet supported */
112  FAS_ASSERT(FAS_TRAP);
113  break;
114  case MXM_CONVERSION_BLOCK_VOLTAGE:
115  case MXM_CONVERSION_UNIPOLAR:
116  *pTarget = ((temporaryVoltage * fullScaleReference_mV) / 0x3FFFu);
117  break;
118  default:
119  /* we should not be here */
120  FAS_ASSERT(FAS_TRAP);
121  break;
122  }
123 
124  return;
125 }
126 
127 extern STD_RETURN_TYPE_e must_check_return MXM_ConvertTest() {
128  uint16_t voltage = 0u;
129  uint8_t msb = 0u;
130  uint8_t lsb = 0u;
131  MXM_CONVERSION_TYPE_e conversionType = MXM_CONVERSION_UNIPOLAR;
132 
133  /* low scale */
134  msb = 0x00u;
135  lsb = 0x00u;
136  voltage = 1;
137  MXM_Convert(lsb, msb, &voltage, conversionType, 5000);
138  FAS_ASSERT(voltage == 0u);
139 
140  /* half scale */
141  msb = 0x80u;
142  lsb = 0x00u;
143  voltage = 0;
144  MXM_Convert(lsb, msb, &voltage, conversionType, 5000);
145  FAS_ASSERT(voltage == 2500u);
146 
147  /* full scale */
148  msb = 0xFFu;
149  lsb = 0xFCu;
150  voltage = 0;
151  MXM_Convert(lsb, msb, &voltage, conversionType, 5000);
152  FAS_ASSERT(voltage == 5000u);
153 
154  return STD_OK;
155 }
156 
157 extern void MXM_ExtractValueFromRegister(uint8_t lsb, uint8_t msb, MXM_REG_BM bitmask, uint16_t *pValue) {
158  /* input sanitation */
159  FAS_ASSERT(pValue != NULL_PTR);
160 
161  /* find lowest bit that is 1 in bitmask */
162  uint8_t start = MXM_FirstSetBit(bitmask);
163 
164  /* apply bitmask to LSB and MSB */
165  uint8_t lsbMasked = lsb & ((uint8_t)(bitmask & MXM_BM_LSB));
166  uint16_t msbBitmask = (bitmask & MXM_BM_MSB);
167  uint8_t msbMasked = msb & ((uint8_t)(msbBitmask >> 8u));
168 
169  /* shift LSB into right position and or over into value */
170  *pValue = 0u | (lsbMasked >> start);
171 
172  /* add MSB at right position */
173  *pValue = (((uint16_t)msbMasked << (8u - start)) | *pValue);
174 }
175 
176 extern STD_RETURN_TYPE_e must_check_return MXM_ExtractValueFromRegisterTest() {
177  uint8_t lsb = 0x00u;
178  uint8_t msb = 0x00u;
179  uint16_t value = 0x00u;
180 
181  lsb = 0x31u;
182  msb = 0x85u;
183  value = 0x00u;
184  MXM_ExtractValueFromRegister(lsb, msb, MXM_REG_VERSION_MOD, &value);
185  FAS_ASSERT(value == 0x853u);
186 
187  MXM_ExtractValueFromRegister(lsb, msb, MXM_REG_VERSION_VER, &value);
188  FAS_ASSERT(value == 0x01u);
189 
190  lsb = 0xFCu;
191  msb = 0xFFu;
192  value = 0x00u;
193  MXM_ExtractValueFromRegister(lsb, msb, MXM_REG_ADC_14BIT_VALUE, &value);
194  FAS_ASSERT(value == 0x3FFFu);
195 
196  lsb = 0xFEu;
197  msb = 0x7Fu;
198  value = 0x00u;
199  MXM_ExtractValueFromRegister(lsb, msb, MXM_REG_ADC_14BIT_VALUE, &value);
200  FAS_ASSERT(value == 0x1FFFu);
201 
202  return STD_OK;
203 }
204 
205 extern void MXM_Unipolar14BitInto16Bit(uint16_t inputValue, uint8_t *lsb, uint8_t *msb) {
206  uint16_t workingCopy = inputValue;
207  /* left shift into 16bit position */
208  workingCopy = workingCopy << 2u;
209 
210  /* bitmask LSB */
211  *lsb = workingCopy & MXM_BM_LSB;
212  /* shift MSB into lower byte (workingCopy is 16bit) */
213  *msb = workingCopy >> 8u;
214 }
215 
216 extern uint16_t MXM_VoltageIntoUnipolar14Bit(uint16_t voltage_mV, uint16_t fullscaleReference_mV) {
217  uint32_t temporaryVoltage = voltage_mV;
218  /* multiply by the 14bit fullscale */
219  temporaryVoltage = temporaryVoltage * 0x3FFFu;
220  /* return divided by fullscale_reference */
221  return (uint16_t)(temporaryVoltage / fullscaleReference_mV);
222 }
223 
224 extern void MXM_ConvertModuleToString(
225  const uint16_t moduleNumber,
226  uint8_t *pStringNumber,
227  uint16_t *pModuleNumberInString) {
228  FAS_ASSERT(pStringNumber != NULL_PTR);
229  FAS_ASSERT(pModuleNumberInString != NULL_PTR);
230  /* the module number cannot be higher than the highest module in the daisy-chain */
231  FAS_ASSERT(moduleNumber < MXM_MAXIMUM_NR_OF_MODULES);
232  /* the module number cannot be higher than number of maximum modules in the string */
233  FAS_ASSERT(moduleNumber < (BS_NR_OF_STRINGS * BS_NR_OF_MODULES));
234 
235  /* calculate string number */
236  *pStringNumber = moduleNumber / BS_NR_OF_MODULES;
237  /* calculate module number and handle edge-case BS_NR_OF_MODULES == 1 */
238  if (1u == BS_NR_OF_MODULES) {
239  *pModuleNumberInString = 0u;
240  } else {
241  *pModuleNumberInString = moduleNumber % BS_NR_OF_MODULES;
242  }
243 }
244 
245 /*========== Externalized Static Function Implementations (Unit Test) =======*/
MXM_CONVERSION_BLOCK_VOLTAGE
@ MXM_CONVERSION_BLOCK_VOLTAGE
Definition: mxm_basic_defines.h:133
MXM_ExtractValueFromRegisterTest
STD_RETURN_TYPE_e must_check_return MXM_ExtractValueFromRegisterTest()
Test MXM_ExtractValueFromRegister().
Definition: mxm_1785x_tools.c:176
MXM_BM_LSB
#define MXM_BM_LSB
Monitoring Register LSB.
Definition: mxm_register_map.h:715
MXM_CONVERSION_TYPE_e
enum MXM_CONVERSION_TYPE MXM_CONVERSION_TYPE_e
BS_NR_OF_MODULES
#define BS_NR_OF_MODULES
number of modules in battery pack
Definition: battery_system_cfg.h:96
MXM_ConvertModuleToString
void MXM_ConvertModuleToString(const uint16_t moduleNumber, uint8_t *pStringNumber, uint16_t *pModuleNumberInString)
Get the string and module number from a global module number.
Definition: mxm_1785x_tools.c:224
STD_RETURN_TYPE_e
enum STD_RETURN_TYPE STD_RETURN_TYPE_e
MXM_Convert
void MXM_Convert(uint8_t lsb, uint8_t msb, uint16_t *pTarget, MXM_CONVERSION_TYPE_e convType, uint32_t fullScaleReference_mV)
Convert a measurement value to a voltage value.
Definition: mxm_1785x_tools.c:98
mxm_register_map.h
Register map of the MAX1785x monitoring IC.
MXM_ConvertTest
STD_RETURN_TYPE_e must_check_return MXM_ConvertTest()
Test the MXM_Convert()-function.
Definition: mxm_1785x_tools.c:127
MXM_REG_VERSION_VER
#define MXM_REG_VERSION_VER
Monitoring Register Version/Silicon Version.
Definition: mxm_register_map.h:731
MXM_MAXIMUM_NR_OF_MODULES
#define MXM_MAXIMUM_NR_OF_MODULES
Maximum number of modules.
Definition: mxm_basic_defines.h:73
MXM_FirstSetBitTest
STD_RETURN_TYPE_e must_check_return MXM_FirstSetBitTest()
Test MXM_FirstSetBit().
Definition: mxm_1785x_tools.c:85
MXM_BM_MSB
#define MXM_BM_MSB
Monitoring Register MSB.
Definition: mxm_register_map.h:719
mxm_1785x_tools.h
This is a collection of helper functions for the MAX1785x ICs.
MXM_CONVERSION_UNIPOLAR
@ MXM_CONVERSION_UNIPOLAR
Definition: mxm_basic_defines.h:131
FAS_ASSERT
#define FAS_ASSERT(x)
Assertion macro that asserts that x is true.
Definition: fassert.h:233
MXM_CONVERSION_BIPOLAR
@ MXM_CONVERSION_BIPOLAR
Definition: mxm_basic_defines.h:132
must_check_return
#define must_check_return
Allows functions to generate warnings in GCC for unused returns.
Definition: general.h:95
STD_OK
@ STD_OK
Definition: fstd_types.h:72
MXM_BM_NULL
#define MXM_BM_NULL
Monitoring Register Null byte.
Definition: mxm_register_map.h:711
MXM_FirstSetBit
uint8_t MXM_FirstSetBit(uint16_t bitmask)
Find Position of first set bit in bitmask.
Definition: mxm_1785x_tools.c:73
MXM_REG_BM
uint16_t MXM_REG_BM
Type for register access for monitoring ICs.
Definition: mxm_register_map.h:702
MXM_REG_ADC_14BIT_VALUE
#define MXM_REG_ADC_14BIT_VALUE
Monitoring Register 14bit ADC value.
Definition: mxm_register_map.h:735
MXM_VoltageIntoUnipolar14Bit
uint16_t MXM_VoltageIntoUnipolar14Bit(uint16_t voltage_mV, uint16_t fullscaleReference_mV)
convert a voltage value into a unipolar 14bit value
Definition: mxm_1785x_tools.c:216
MXM_Unipolar14BitInto16Bit
void MXM_Unipolar14BitInto16Bit(uint16_t inputValue, uint8_t *lsb, uint8_t *msb)
convert a unipolar 14bit-value and shifts it into the 16bit-format
Definition: mxm_1785x_tools.c:205
NULL_PTR
#define NULL_PTR
Null pointer.
Definition: fstd_types.h:66
MXM_REG_VERSION_MOD
#define MXM_REG_VERSION_MOD
Monitoring Register Version/Model.
Definition: mxm_register_map.h:727
MXM_ExtractValueFromRegister
void MXM_ExtractValueFromRegister(uint8_t lsb, uint8_t msb, MXM_REG_BM bitmask, uint16_t *pValue)
Extract a value from a single register.
Definition: mxm_1785x_tools.c:157
FAS_TRAP
#define FAS_TRAP
Define that evaluates to essential boolean false thus tripping an assert.
Definition: fassert.h:108
BS_NR_OF_STRINGS
#define BS_NR_OF_STRINGS
Definition: battery_system_cfg.h:89