foxBMS-UnitTests  1.0.0
The foxBMS Unit Tests API Documentation
spi.h
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 spi.h
44  * @author foxBMS Team
45  * @date 2019-12-12 (date of creation)
46  * @updated 2019-12-12 (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  */
88 extern STD_RETURN_TYPE_e SPI_TransmitDataWithDummy(
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  */
103 extern STD_RETURN_TYPE_e SPI_TransmitData(
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  */
119 extern STD_RETURN_TYPE_e SPI_TransmitReceiveData(
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  */
140 extern STD_RETURN_TYPE_e SPI_DirectlyTransmitReceiveData(
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  */
157 extern STD_RETURN_TYPE_e SPI_TransmitReceiveDataDma(
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  */
176 extern STD_RETURN_TYPE_e SPI_TransmitReceiveDataWithDummyDma(
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 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
201 
202 #endif /* FOXBMS__SPI_H_ */
SPI_TransmitDummyByte
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:77
SPI_Unlock
void SPI_Unlock(uint8_t spi)
Unlocks SPI interfaces.
Definition: spi.c:418
SPI_TransmitDataWithDummy
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:121
STD_RETURN_TYPE_e
enum STD_RETURN_TYPE STD_RETURN_TYPE_e
SPI_TransmitReceiveData
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:138
SPI_TransmitData
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:100
SPI_INTERFACE_CONFIG
Definition: spi_cfg.h:107
SPI_DirectlyTransmitReceiveData
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:162
spi_cfg.h
Headers for the configuration for the SPI module.
SPI_TransmitReceiveDataDma
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:179
SPI_TransmitReceiveDataWithDummyDma
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:287
SPI_Lock
STD_RETURN_TYPE_e SPI_Lock(uint8_t spi)
Locks SPI interfaces.
Definition: spi.c:403