foxBMS  1.1.0
The foxBMS Battery Management System API Documentation
spi.h
Go to the documentation of this file.
1 /**
2  *
3  * @copyright © 2010 - 2021, 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 spi.h
44  * @author foxBMS Team
45  * @date 2019-12-12 (date of creation)
46  * @updated 2021-06-16 (date of last update)
47  * @ingroup DRIVERS
48  * @prefix SPI
49  *
50  * @brief Headers for the driver for the SPI module.
51  *
52  */
53 
54 #ifndef FOXBMS__SPI_H_
55 #define FOXBMS__SPI_H_
56 
57 /*========== Includes =======================================================*/
58 #include "spi_cfg.h"
59 
60 /*========== Macros and Definitions =========================================*/
61 
62 /*========== Extern Constant and Variable Declarations ======================*/
63 
64 /*========== Extern Function Prototypes =====================================*/
65 
66 /**
67  * @brief Sends a dummy byte to wake up the SPI interface.
68  *
69  * @param pSpiInterface pointer to SPI interface configuration
70  * @param delay delay to wait after dummy byte transfer
71  *
72  * @return status of the SPI transfer
73  */
74 extern STD_RETURN_TYPE_e SPI_TransmitDummyByte(SPI_INTERFACE_CONFIG_s *pSpiInterface, uint32_t delay);
75 
76 /**
77  * @brief Sends data on SPI without DMA, with wake-up byte.
78  *
79  * It calls SPI_SendDummyByte() to wake-up the SPI interface.
80  *
81  * @param pSpiInterface pointer to SPI interface configuration
82  * @param delay delay to wait after dummy byte transfer
83  * @param pTxBuff pointer to data that is transmitted by the SPI interface
84  * @param frameLength number of bytes to be transmitted by the SPI interface
85  *
86  * @return status of the SPI transfer
87  */
89  SPI_INTERFACE_CONFIG_s *pSpiInterface,
90  uint32_t delay,
91  uint16_t *pTxBuff,
92  uint32_t frameLength);
93 
94 /**
95  * @brief Sends data on SPI without DMA.
96  *
97  * @param pSpiInterface pointer to SPI interface configuration
98  * @param pTxBuff pointer to data that is transmitted by the SPI interface
99  * @param frameLength number of bytes to be transmitted by the SPI interface
100  *
101  * @return status of the SPI transfer
102  */
104  SPI_INTERFACE_CONFIG_s *pSpiInterface,
105  uint16_t *pTxBuff,
106  uint32_t frameLength);
107 
108 /**
109  * @brief Transmits and receives data on SPI without DMA.
110  * @details This function can be used to send and receive data via SPI. SPI
111  * communication is performed in blocking mode and chip select is
112  * set/reset automatically.
113  * @param pSpiInterface pointer to SPI interface configuration
114  * @param pTxBuff pointer to data that is transmitted by the SPI interface
115  * @param pRxBuff pointer to data that is received by the SPI interface
116  * @param frameLength number of bytes to be transmitted by the SPI interface
117  * @return status of the SPI transfer
118  */
120  SPI_INTERFACE_CONFIG_s *pSpiInterface,
121  uint16 *pTxBuff,
122  uint16 *pRxBuff,
123  uint32 frameLength);
124 
125 /**
126  * @brief Transmits and receives data on SPI without DMA.
127  *
128  * @details This function can be used to send and receive data via SPI. SPI
129  * communication is performed in blocking mode but setting/resetting
130  * chip select and locking of the peripheral is not handled by this
131  * function. This must be ensured by the caller.
132  *
133  * @param pSpiInterface pointer to SPI interface configuration
134  * @param pTxBuff pointer to data that is transmitted by the SPI interface
135  * @param pRxBuff pointer to data that is received by the SPI interface
136  * @param frameLength number of bytes to be transmitted by the SPI interface
137  *
138  * @return status of the SPI transfer
139  */
141  SPI_INTERFACE_CONFIG_s *pSpiInterface,
142  uint16 *pTxBuff,
143  uint16 *pRxBuff,
144  uint32 frameLength);
145 
146 /**
147  * @brief Transmits and receives data on SPI with DMA.
148  * @details This function can be used to send and receive data via SPI. SPI
149  * communication is performed in blocking mode and chip select is
150  * set/reset automatically..
151  * @param pSpiInterface pointer to SPI interface configuration
152  * @param pTxBuff pointer to data that is transmitted by the SPI interface
153  * @param pRxBuff pointer to data that is received by the SPI interface
154  * @param frameLength number of bytes to be transmitted by the SPI interface
155  * @return status of the SPI transfer
156  */
158  SPI_INTERFACE_CONFIG_s *pSpiInterface,
159  uint16_t *pTxBuff,
160  uint16_t *pRxBuff,
161  uint32_t frameLength);
162 
163 /**
164  * @brief Transmits and receives data on SPI with DMA.
165  * @details This function can be used to send and receive data via SPI. SPI
166  * communication is performed in blocking mode and chip select is
167  * set/reset automatically. A dummy is sent first.
168  * @param pSpiInterface pointer to SPI interface configuration
169  * @param delay delay to wait after dummy byte transfer
170  * @param pTxBuff pointer to data that is transmitted by the SPI interface
171  * @param pRxBuff pointer to data that is received by the SPI interface
172  * @param frameLength number of bytes to be transmitted by the SPI interface
173  *
174  * @return status of the SPI transfer
175  */
177  SPI_INTERFACE_CONFIG_s *pSpiInterface,
178  uint32_t delay,
179  uint16_t *pTxBuff,
180  uint16_t *pRxBuff,
181  uint32_t frameLength);
182 
183 /**
184  * @brief Locks SPI interfaces.
185  * @details This function is used to change the state of the SPI_busy_flags
186  * variable to "locked".
187  * @param spi SPI interface to be locked (0-4 on the TMS570LC4357)
188  * @return #STD_OK if SPI interface could be locked, #STD_NOT_OK otherwise
189  */
190 extern STD_RETURN_TYPE_e SPI_Lock(uint8_t spi);
191 
192 /**
193  * @brief Unlocks SPI interfaces.
194  * @details This function is used to change the state of the SPI_busy_flags
195  * variable to "unlocked".
196  * @param spi SPI interface to be unlocked (0-4 on the TMS570LC4357)
197  */
198 extern void SPI_Unlock(uint8_t spi);
199 
200 /**
201  * @brief Sets the functional of a SPI pin
202  * @details SPI pins in this HAL can have functional state SPI (for when it is
203  * controlled by the SPI hardware) and functional state GIO (for when
204  * it is controlled as a GIO pin).
205  * @param[in,out] pNode handle of the SPI node that should be configured
206  * @param[in] bit bit that should be manipulated, other pins remain
207  * unchanged
208  * @param[in] hardwareControlled Whether the bit should be hardware
209  * controlled (true) or not (false)
210  */
211 extern void SPI_SetFunctional(spiBASE_t *pNode, enum spiPinSelect bit, bool hardwareControlled);
212 
213 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
214 
215 #endif /* FOXBMS__SPI_H_ */
enum STD_RETURN_TYPE STD_RETURN_TYPE_e
STD_RETURN_TYPE_e SPI_TransmitReceiveDataDma(SPI_INTERFACE_CONFIG_s *pSpiInterface, uint16_t *pTxBuff, uint16_t *pRxBuff, uint32_t frameLength)
Transmits and receives data on SPI with DMA.
Definition: spi.c:183
void SPI_SetFunctional(spiBASE_t *pNode, enum spiPinSelect bit, bool hardwareControlled)
Sets the functional of a SPI pin.
Definition: spi.c:430
STD_RETURN_TYPE_e SPI_DirectlyTransmitReceiveData(SPI_INTERFACE_CONFIG_s *pSpiInterface, uint16 *pTxBuff, uint16 *pRxBuff, uint32 frameLength)
Transmits and receives data on SPI without DMA.
Definition: spi.c:166
STD_RETURN_TYPE_e SPI_TransmitDummyByte(SPI_INTERFACE_CONFIG_s *pSpiInterface, uint32_t delay)
Sends a dummy byte to wake up the SPI interface.
Definition: spi.c:81
STD_RETURN_TYPE_e SPI_TransmitData(SPI_INTERFACE_CONFIG_s *pSpiInterface, uint16_t *pTxBuff, uint32_t frameLength)
Sends data on SPI without DMA.
Definition: spi.c:104
STD_RETURN_TYPE_e SPI_Lock(uint8_t spi)
Locks SPI interfaces.
Definition: spi.c:407
STD_RETURN_TYPE_e SPI_TransmitReceiveDataWithDummyDma(SPI_INTERFACE_CONFIG_s *pSpiInterface, uint32_t delay, uint16_t *pTxBuff, uint16_t *pRxBuff, uint32_t frameLength)
Transmits and receives data on SPI with DMA.
Definition: spi.c:291
void SPI_Unlock(uint8_t spi)
Unlocks SPI interfaces.
Definition: spi.c:422
STD_RETURN_TYPE_e SPI_TransmitReceiveData(SPI_INTERFACE_CONFIG_s *pSpiInterface, uint16 *pTxBuff, uint16 *pRxBuff, uint32 frameLength)
Transmits and receives data on SPI without DMA.
Definition: spi.c:142
STD_RETURN_TYPE_e SPI_TransmitDataWithDummy(SPI_INTERFACE_CONFIG_s *pSpiInterface, uint32_t delay, uint16_t *pTxBuff, uint32_t frameLength)
Sends data on SPI without DMA, with wake-up byte.
Definition: spi.c:125
Headers for the configuration for the SPI module.