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