foxBMS  1.3.0
The foxBMS Battery Management System API Documentation
spi.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 spi.h
44  * @author foxBMS Team
45  * @date 2019-12-12 (date of creation)
46  * @updated 2022-05-30 (date of last update)
47  * @version v1.3.0
48  * @ingroup DRIVERS
49  * @prefix SPI
50  *
51  * @brief Headers for the driver for the SPI module.
52  *
53  */
54 
55 #ifndef FOXBMS__SPI_H_
56 #define FOXBMS__SPI_H_
57 
58 /*========== Includes =======================================================*/
59 #include "spi_cfg.h"
60 
61 /*========== Macros and Definitions =========================================*/
62 
63 /*========== Extern Constant and Variable Declarations ======================*/
64 
65 /*========== Extern Function Prototypes =====================================*/
66 
67 /* INCLUDE MARKER FOR THE DOCUMENTATION; DO NOT MOVE spi-documentation-dummy-start-include */
68 /**
69  * @brief Sends a dummy byte to wake up the SPI interface.
70  *
71  * @param pSpiInterface pointer to SPI interface configuration
72  * @param delay delay to wait after dummy byte transfer
73  *
74  * @return status of the SPI transfer
75  */
76 extern STD_RETURN_TYPE_e SPI_TransmitDummyByte(SPI_INTERFACE_CONFIG_s *pSpiInterface, uint32_t delay);
77 /* INCLUDE MARKER FOR THE DOCUMENTATION; DO NOT MOVE spi-documentation-dummy-stop-include */
78 
79 /* INCLUDE MARKER FOR THE DOCUMENTATION; DO NOT MOVE spi-documentation-transmit-start-include */
80 /**
81  * @brief Transmits data on SPI without DMA.
82  * @details This function can be used to send and receive data via SPI. SPI
83  * communication is performed in blocking mode and chip select is
84  * set/reset automatically.
85  * @param pSpiInterface pointer to SPI interface configuration
86  * @param pTxBuff pointer to data that is transmitted by the SPI interface
87  * @param frameLength number of bytes to be transmitted by the SPI interface
88  * @return status of the SPI transfer
89  */
90 extern STD_RETURN_TYPE_e SPI_TransmitData(SPI_INTERFACE_CONFIG_s *pSpiInterface, uint16 *pTxBuff, uint32 frameLength);
91 /* INCLUDE MARKER FOR THE DOCUMENTATION; DO NOT MOVE spi-documentation-transmit-stop-include */
92 
93 /* INCLUDE MARKER FOR THE DOCUMENTATION; DO NOT MOVE spi-documentation-transmit-receive-start-include */
94 /**
95  * @brief Transmits and receives data on SPI without DMA.
96  * @details This function can be used to send and receive data via SPI. SPI
97  * communication is performed in blocking mode and chip select is
98  * set/reset automatically.
99  * @param pSpiInterface pointer to SPI interface configuration
100  * @param pTxBuff pointer to data that is transmitted by the SPI interface
101  * @param pRxBuff pointer to data that is received by the SPI interface
102  * @param frameLength number of bytes to be transmitted by the SPI interface
103  * @return status of the SPI transfer
104  */
106  SPI_INTERFACE_CONFIG_s *pSpiInterface,
107  uint16 *pTxBuff,
108  uint16 *pRxBuff,
109  uint32 frameLength);
110 /* INCLUDE MARKER FOR THE DOCUMENTATION; DO NOT MOVE spi-documentation-transmit-receive-stop-include */
111 
112 /* INCLUDE MARKER FOR THE DOCUMENTATION; DO NOT MOVE spi-documentation-fram-start-include */
113 /**
114  * @brief Transmits and receives data on SPI without DMA, wrappe for FRAM
115  * @details This function can be used to send and receive data via SPI. SPI
116  * communication is performed in blocking mode and chip select is
117  * set/reset automatically.
118  * It does not drive the Chip Select (neither hardware nor software)
119  * as this is done directly in the FRAM functions.
120  * @param pSpiInterface pointer to SPI interface configuration
121  * @param pTxBuff pointer to data that is transmitted by the SPI interface
122  * @param pRxBuff pointer to data that is received by the SPI interface
123  * @param frameLength number of bytes to be transmitted by the SPI interface
124  * @return status of the SPI transfer
125  */
126 extern void SPI_FramTransmitReceiveData(
127  SPI_INTERFACE_CONFIG_s *pSpiInterface,
128  uint16 *pTxBuff,
129  uint16 *pRxBuff,
130  uint32 frameLength);
131 /* INCLUDE MARKER FOR THE DOCUMENTATION; DO NOT MOVE spi-documentation-fram-stop-include */
132 
133 /* INCLUDE MARKER FOR THE DOCUMENTATION; DO NOT MOVE spi-documentation-transmit-receive-dma-start-include */
134 /**
135  * @brief Transmits and receives data on SPI with DMA.
136  * @details This function can be used to send and receive data via SPI. SPI
137  * communication is performed in blocking mode and chip select is
138  * set/reset automatically..
139  * @param pSpiInterface pointer to SPI interface configuration
140  * @param pTxBuff pointer to data that is transmitted by the SPI interface
141  * @param pRxBuff pointer to data that is received by the SPI interface
142  * @param frameLength number of bytes to be transmitted by the SPI interface
143  * @return status of the SPI transfer
144  */
146  SPI_INTERFACE_CONFIG_s *pSpiInterface,
147  uint16_t *pTxBuff,
148  uint16_t *pRxBuff,
149  uint32_t frameLength);
150 /* INCLUDE MARKER FOR THE DOCUMENTATION; DO NOT MOVE spi-documentation-transmit-receive-dma-stop-include */
151 
152 /* INCLUDE MARKER FOR THE DOCUMENTATION; DO NOT MOVE spi-documentation-slave-receive-dma-start-include */
153 /**
154  * @brief Transmits and receives data on SPI with DMA.
155  * @details This function can be used to send and receive data via SPI. SPI
156  * communication is performed in blocking mode and chip select is
157  * set/reset automatically..
158  * @param pSpiInterface pointer to SPI interface configuration
159  * @param pTxBuff pointer to data that is transmitted by the SPI interface
160  * @param pRxBuff pointer to data that is received by the SPI interface
161  * @param frameLength number of bytes to be transmitted by the SPI interface
162  * @return status of the SPI transfer
163  */
165  SPI_INTERFACE_CONFIG_s *pSpiInterface,
166  uint16_t *pTxBuff,
167  uint16_t *pRxBuff,
168  uint32_t frameLength);
169 /* INCLUDE MARKER FOR THE DOCUMENTATION; DO NOT MOVE spi-documentation-slave-receive-dma-stop-include */
170 
171 /**
172  * @brief Locks SPI interfaces.
173  * @details This function is used to change the state of the SPI_busy_flags
174  * variable to "locked".
175  * @param spi SPI interface to be locked (0-4 on the TMS570LC4357)
176  * @return #STD_OK if SPI interface could be locked, #STD_NOT_OK otherwise
177  */
178 extern STD_RETURN_TYPE_e SPI_Lock(uint8_t spi);
179 
180 /**
181  * @brief Unlocks SPI interfaces.
182  * @details This function is used to change the state of the SPI_busy_flags
183  * variable to "unlocked".
184  * @param spi SPI interface to be unlocked (0-4 on the TMS570LC4357)
185  */
186 extern void SPI_Unlock(uint8_t spi);
187 
188 /**
189  * @brief Sets the functional of a SPI pin
190  * @details SPI pins in this HAL can have functional state SPI (for when it is
191  * controlled by the SPI hardware) and functional state GIO (for when
192  * it is controlled as a GIO pin).
193  * @param[in,out] pNode handle of the SPI node that should be configured
194  * @param[in] bit bit that should be manipulated, other pins remain
195  * unchanged
196  * @param[in] hardwareControlled Whether the bit should be hardware
197  * controlled (true) or not (false)
198  */
199 extern void SPI_SetFunctional(spiBASE_t *pNode, enum spiPinSelect bit, bool hardwareControlled);
200 
201 /**
202  * @brief Used to send last byte per SPI.
203  * @details This function is called in the DMA Tx callback. It is used
204  * to send the last byte with CSHOLD = 0.
205  * @param spiIndex SPI node in use
206  */
207 extern void SPI_DmaSendLastByte(uint8_t spiIndex);
208 
209 /**
210  * @brief Returns #STD_OK if the SPI interface can be used again
211  * @details This function just checks for SPI_PENDING and groups SPI_READY and
212  * SPI_...
213  * @param[in] pNode handle of the SPI node that should be checked
214  * @returns #STD_RETURN_TYPE_e indicating wether the interface is ok to be used.
215  */
216 extern STD_RETURN_TYPE_e SPI_CheckInterfaceAvailable(spiBASE_t *pNode);
217 
218 /**
219  * @brief Returns index of SPI node
220  * @param[in] pNode handle of the SPI node that should be checked
221  * @returns index of SPI node
222  */
223 extern uint8_t SPI_GetSpiIndex(spiBASE_t *pNode);
224 
225 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
226 
227 #endif /* FOXBMS__SPI_H_ */
STD_RETURN_TYPE_e
Definition: fstd_types.h:81
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:216
void SPI_SetFunctional(spiBASE_t *pNode, enum spiPinSelect bit, bool hardwareControlled)
Sets the functional of a SPI pin.
Definition: spi.c:353
STD_RETURN_TYPE_e SPI_CheckInterfaceAvailable(spiBASE_t *pNode)
Returns STD_OK if the SPI interface can be used again.
Definition: spi.c:460
void SPI_DmaSendLastByte(uint8_t spiIndex)
Used to send last byte per SPI.
Definition: spi.c:451
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:83
void SPI_FramTransmitReceiveData(SPI_INTERFACE_CONFIG_s *pSpiInterface, uint16 *pTxBuff, uint16 *pRxBuff, uint32 frameLength)
Transmits and receives data on SPI without DMA, wrappe for FRAM.
Definition: spi.c:203
STD_RETURN_TYPE_e SPI_Lock(uint8_t spi)
Locks SPI interfaces.
Definition: spi.c:326
STD_RETURN_TYPE_e SPI_SlaveSetReceiveDataDma(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:387
void SPI_Unlock(uint8_t spi)
Unlocks SPI interfaces.
Definition: spi.c:343
STD_RETURN_TYPE_e SPI_TransmitData(SPI_INTERFACE_CONFIG_s *pSpiInterface, uint16 *pTxBuff, uint32 frameLength)
Transmits data on SPI without DMA.
Definition: spi.c:93
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:145
uint8_t SPI_GetSpiIndex(spiBASE_t *pNode)
Returns index of SPI node.
Definition: spi.c:470
Headers for the configuration for the SPI module.