foxBMS  1.2.0
The foxBMS Battery Management System API Documentation
sbc_fs8x_common.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2016 - 2018, NXP Semiconductors, Inc.
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without modification,
6  * are permitted provided that the following conditions are met:
7  *
8  * o Redistributions of source code must retain the above copyright notice, this list
9  * of conditions and the following disclaimer.
10  *
11  * o Redistributions in binary form must reproduce the above copyright notice, this
12  * list of conditions and the following disclaimer in the documentation and/or
13  * other materials provided with the distribution.
14  *
15  * o Neither the name of the copyright holder nor the names of its
16  * contributors may be used to endorse or promote products derived from this
17  * software without specific prior written permission.
18  *
19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
20  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
21  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
22  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
23  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
24  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
25  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
26  * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
28  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29  */
30 
31 /** @file sbc_fs8x_common.h
32  * @brief Driver common structures, enums, macros and configuration values.
33  *
34  * This header file contains settings for following driver functionalities:
35  * - Watchdog type selection.
36  * - Communication type selection (SPI/I2C).
37  *
38  * @author nxf44615
39  * @version 1.1
40  * @date 9-Oct-2018
41  * @copyright Copyright (c) 2016 - 2018, NXP Semiconductors, Inc.
42  *
43  * @updated 2020-03-18 (date of last update)
44  * Adapted driver to pass interface configuration as parameter into the
45  * functions to enable the usage of multiple ICs in the system.
46  */
47 
48 #ifndef SBC_FS8X_COMMON_H_
49 #define SBC_FS8X_COMMON_H_
50 
51 /*******************************************************************************
52  * Includes
53  ******************************************************************************/
54 
55 #include "spi.h"
56 #include <stdint.h>
57 #include <stdbool.h>
58 
59 /*******************************************************************************
60  * Definitions
61  ******************************************************************************/
62 
63 /** @defgroup WdTypes Watchdog types
64  *
65  * Note that periodic call of function @ref FS8x_WD_Refresh() is up to the application.
66  * @{ */
67 #define FS8x_WD_DISABLE 0 /**< Watchdog refresh disabled. */
68 #define FS8x_WD_SIMPLE 1 /**< Simple Watchdog refresh. */
69 #define FS8x_WD_CHALLENGER 2 /**< Challenger watchdog refresh. */
70 /** @} */
71 
72 /** @brief Define Watchdog type (see @ref WdTypes). */
73 #define FS8x_WD_TYPE FS8x_WD_SIMPLE
74 
75 /** @defgroup CommTypes Allowed communication types
76  *
77  * If SPI or I2C communication is selected, the other implementation will not be compiled.
78  * Actual communication type can be selected in @ref fs8x_drv_data_t::communicationMode.
79  * @{ */
80 #define FS8x_COMM_SPI 0 /**< SPI communication implementation will be compiled. */
81 #define FS8x_COMM_I2C 1 /**< I2C communication implementation will be compiled. */
82 #define FS8x_COMM_BOTH 2 /**< SPI and I2C communication implementation will be compiled. */
83 /** @} */
84 
85 /** @brief Define communication type (see @ref CommTypes). */
86 #define FS8x_COMM_TYPE FS8x_COMM_SPI
87 
88 /** @defgroup EnumsDefs Enums definition
89  * @{ */
90 /** @brief Status return codes. */
91 typedef enum
92 {
93  fs8xStatusOk = 0U, /**< No error. */
94  fs8xStatusError = 1U /**< Error. */
96 
97 /** @brief Actually selected communication type (SPI or I2C).
98  *
99  * Note that the value of #FS8x_COMM_TYPE define should match selected value. */
100 typedef enum
101 {
102  fs8xSPI = 0, /**< SPI */
103  fs8xI2C = 1 /**< I2C */
105 
106 /** @brief Command type. */
107 typedef enum {
108  fs8xRegRead, /**< Register Read */
109  fs8xRegWrite /**< Register Write */
111 /** @} */
112 
113 /** @defgroup StructDefs Struct definitions
114  * @{ */
115 /** @brief Structure representing transmit data frame. */
116 typedef struct
117 {
118  /** @brief Main/Fail Safe register selection. */
120 
121  /** @brief Register address. */
123 
124  /** @brief Command type (R/W). */
126 
127  /** @brief Data to be written to the register.
128  *
129  * If commandType is "read", this value will be ignored. */
130  uint16_t writeData;
131 
133 
134 /** @brief Structure representing received data frame. */
135 typedef struct
136 {
137  /** @brief A device status is returned into this byte after a successful transfer.
138  *
139  * Valid just for the SPI communication. Status byte is not returned if
140  * I2C communication is selected. */
141  uint8_t deviceStatus;
142 
143  /** @brief Content of a read register. */
144  uint16_t readData;
145 
147 
148 /** @brief This data structure is used by the FS8x driver (this is the first
149 * parameter of most the FS8x functions). It contains a configuration of the
150 * FS8x device. */
151 typedef struct
152 {
153  /** @brief Actual watchdog seed value. See @ref FS8x_WD_ChangeSeed() for details. */
154  uint16_t watchdogSeed;
155 
156  /** @brief Actual communication mode (SPI or I2C). See @ref fs8x_commType_t for details. */
158 
159  /** @brief SBC I2C address.
160  *
161  * This is not the full I2C address but just a value of the OTP register
162  * OTP_CFG_I2C - I2CDEVADDR[3:0]. */
163  uint8_t i2cAddressOtp;
164 
166 /** @} */
167 
168 /** @name Bitwise operations used by this driver. */
169 /** @{ */
170 /** @brief This macro updates value of bits specified by the mask. It is assumed that
171  * value is already shifted. */
172 #define FS8x_BO_SETVAL(data, val, mask) (((data) & ~(mask)) | (val))
173 
174 /** @brief This macro updates value of bits specified by the mask. Additionally range
175  * check on the value is performed. It is assumed that value is not shifted. */
176 #define FS8x_BO_SETVAL_EXT(data, value, mask, shift) \
177  (((data) & ~(mask << shift)) | (((value) & (mask)) << (shift)))
178 
179 /** @brief This macro returns value specified by the mask. */
180 #define FS8x_BO_GETVAL(data, mask, shift) ((data) & (mask) << (shift))
181 
182 /** @brief Macro for getting value from register.
183  *
184  * @param value Value read from register.
185  * @param mask Bit selection.
186  * @param shift Bit shift.
187  * @returns Masked and r-shifted value. */
188 #define FS8x_BO_GET_REG_VALUE(value, mask, shift) (((value) & (mask)) >> (shift))
189 /** @} */
190 
191 /*******************************************************************************
192  * Global Variables
193  ******************************************************************************/
194 
195 /*******************************************************************************
196  * API
197  ******************************************************************************/
198 
199 #endif /* SBC_FS8X_COMMON_H_ */
fs8x_command_type_t
Command type.
fs8x_commType_t
Actually selected communication type (SPI or I2C).
fs8x_status_t
Status return codes.
@ fs8xRegWrite
@ fs8xRegRead
@ fs8xI2C
@ fs8xSPI
@ fs8xStatusOk
@ fs8xStatusError
Headers for the driver for the SPI module.
This data structure is used by the FS8x driver (this is the first parameter of most the FS8x function...
fs8x_commType_t communicationMode
Actual communication mode (SPI or I2C). See fs8x_commType_t for details.
uint8_t i2cAddressOtp
SBC I2C address.
uint16_t watchdogSeed
Actual watchdog seed value. See FS8x_WD_ChangeSeed() for details.
Structure representing received data frame.
uint16_t readData
Content of a read register.
uint8_t deviceStatus
A device status is returned into this byte after a successful transfer.
Structure representing transmit data frame.
fs8x_command_type_t commandType
Command type (R/W).
uint8_t registerAddress
Register address.
bool isFailSafe
Main/Fail Safe register selection.
uint16_t writeData
Data to be written to the register.