1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
// Copyright (c) FIRST and other WPILib contributors.
// Open Source Software; you can modify and/or share it under the terms of
// the WPILib BSD license file in the root directory of this project.
#pragma once
#include <stdint.h>
#include "hal/AnalogTrigger.h"
#include "hal/SPITypes.h"
#include "hal/Types.h"
/**
* @defgroup hal_spi SPI Functions
* @ingroup hal_capi
* @{
*/
#ifdef __cplusplus
extern "C" {
#endif
/**
* Initializes the SPI port. Opens the port if necessary and saves the handle.
*
* If opening the MXP port, also sets up the channel functions appropriately.
*
* @param[in] port The number of the port to use. 0-3 for Onboard CS0-CS3, 4
* for MXP
* @param[out] status the error code, or 0 for success
*/
void HAL_InitializeSPI(HAL_SPIPort port, int32_t* status);
/**
* Performs an SPI send/receive transaction.
*
* This is a lower-level interface to the spi hardware giving you more control
* over each transaction.
*
* @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4
* for MXP
* @param dataToSend Buffer of data to send as part of the transaction.
* @param dataReceived Buffer to read data into.
* @param size Number of bytes to transfer. [0..7]
* @return Number of bytes transferred, -1 for error
*/
int32_t HAL_TransactionSPI(HAL_SPIPort port, const uint8_t* dataToSend,
uint8_t* dataReceived, int32_t size);
/**
* Executes a write transaction with the device.
*
* Writes to a device and wait until the transaction is complete.
*
* @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4
* for MXP
* @param dataToSend The data to write to the register on the device.
* @param sendSize The number of bytes to be written
* @return The number of bytes written. -1 for an error
*/
int32_t HAL_WriteSPI(HAL_SPIPort port, const uint8_t* dataToSend,
int32_t sendSize);
/**
* Executes a read from the device.
*
* This method does not write any data out to the device.
*
* Most spi devices will require a register address to be written before they
* begin returning data.
*
* @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for
* MXP
* @param buffer A pointer to the array of bytes to store the data read from the
* device.
* @param count The number of bytes to read in the transaction. [1..7]
* @return Number of bytes read. -1 for error.
*/
int32_t HAL_ReadSPI(HAL_SPIPort port, uint8_t* buffer, int32_t count);
/**
* Closes the SPI port.
*
* @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP
*/
void HAL_CloseSPI(HAL_SPIPort port);
/**
* Sets the clock speed for the SPI bus.
*
* @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for
* MXP
* @param speed The speed in Hz (500KHz-10MHz)
*/
void HAL_SetSPISpeed(HAL_SPIPort port, int32_t speed);
/**
* Sets the SPI Mode.
*
* @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for
* MXP
* @param mode The SPI mode to use
*/
void HAL_SetSPIMode(HAL_SPIPort port, HAL_SPIMode mode);
/**
* Gets the SPI Mode.
*
* @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for
* MXP
* @return The SPI mode currently set
*/
HAL_SPIMode HAL_GetSPIMode(HAL_SPIPort port);
/**
* Sets the CS Active high for a SPI port.
*
* @param[in] port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for
* MXP
* @param[out] status the error code, or 0 for success
*/
void HAL_SetSPIChipSelectActiveHigh(HAL_SPIPort port, int32_t* status);
/**
* Sets the CS Active low for a SPI port.
*
* @param[in] port The number of the port to use. 0-3 for Onboard CS0-CS2, 4
* for MXP
* @param[out] status the error code, or 0 for success
*/
void HAL_SetSPIChipSelectActiveLow(HAL_SPIPort port, int32_t* status);
/**
* Gets the stored handle for a SPI port.
*
* @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP
* @return The stored handle for the SPI port. 0 represents no stored
* handle.
*/
int32_t HAL_GetSPIHandle(HAL_SPIPort port);
/**
* Sets the stored handle for a SPI port.
*
* @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for
* MXP.
* @param handle The value of the handle for the port.
*/
void HAL_SetSPIHandle(HAL_SPIPort port, int32_t handle);
/**
* Initializes the SPI automatic accumulator.
*
* @param[in] port The number of the port to use. 0-3 for Onboard CS0-CS2,
* 4 for MXP.
* @param[in] bufferSize The accumulator buffer size.
* @param[out] status the error code, or 0 for success
*/
void HAL_InitSPIAuto(HAL_SPIPort port, int32_t bufferSize, int32_t* status);
/**
* Frees an SPI automatic accumulator.
*
* @param[in] port The number of the port to use. 0-3 for Onboard CS0-CS2, 4
* for MXP.
* @param[out] status the error code, or 0 for success
*/
void HAL_FreeSPIAuto(HAL_SPIPort port, int32_t* status);
/**
* Sets the period for automatic SPI accumulation.
*
* @param[in] port The number of the port to use. 0-3 for Onboard CS0-CS2, 4
* for MXP.
* @param[in] period The accumulation period (seconds).
* @param[out] status the error code, or 0 for success
*/
void HAL_StartSPIAutoRate(HAL_SPIPort port, double period, int32_t* status);
/**
* Starts the auto SPI accumulator on a specific trigger.
*
* Note that triggering on both rising and falling edges is a valid
* configuration.
*
* @param[in] port The number of the port to use. 0-3 for Onboard
* CS0-CS2, 4 for MXP.
* @param[in] digitalSourceHandle The trigger source to use (Either
* HAL_AnalogTriggerHandle or HAL_DigitalHandle).
* @param[in] analogTriggerType The analog trigger type, if the source is an
* analog trigger.
* @param[in] triggerRising Trigger on the rising edge if true.
* @param[in] triggerFalling Trigger on the falling edge if true.
* @param[out] status the error code, or 0 for success
*/
void HAL_StartSPIAutoTrigger(HAL_SPIPort port, HAL_Handle digitalSourceHandle,
HAL_AnalogTriggerType analogTriggerType,
HAL_Bool triggerRising, HAL_Bool triggerFalling,
int32_t* status);
/**
* Stops an automatic SPI accumulation.
*
* @param[in] port The number of the port to use. 0-3 for Onboard CS0-CS2, 4
* for MXP.
* @param[out] status the error code, or 0 for success
*/
void HAL_StopSPIAuto(HAL_SPIPort port, int32_t* status);
/**
* Sets the data to be transmitted to the device to initiate a read.
*
* @param[in] port The number of the port to use. 0-3 for Onboard CS0-CS2,
* 4 for MXP.
* @param[in] dataToSend Pointer to the data to send (Gets copied for continue
* use, so no need to keep alive).
* @param[in] dataSize The length of the data to send.
* @param[in] zeroSize The number of zeros to send after the data.
* @param[out] status the error code, or 0 for success
*/
void HAL_SetSPIAutoTransmitData(HAL_SPIPort port, const uint8_t* dataToSend,
int32_t dataSize, int32_t zeroSize,
int32_t* status);
/**
* Immediately forces an SPI read to happen.
*
* @param[in] port The number of the port to use. 0-3 for Onboard CS0-CS2, 4
* for MXP.
* @param[out] status the error code, or 0 for success
*/
void HAL_ForceSPIAutoRead(HAL_SPIPort port, int32_t* status);
/**
* Reads data received by the SPI accumulator. Each received data sequence
* consists of a timestamp followed by the received data bytes, one byte per
* word (in the least significant byte). The length of each received data
* sequence is the same as the combined dataSize + zeroSize set in
* HAL_SetSPIAutoTransmitData.
*
* @param[in] port The number of the port to use. 0-3 for Onboard CS0-CS2,
* 4 for MXP.
* @param[out] buffer The buffer to store the data into.
* @param[in] numToRead The number of words to read.
* @param[in] timeout The read timeout (in seconds).
* @param[out] status the error code, or 0 for success
* @return The number of words actually read.
*/
int32_t HAL_ReadSPIAutoReceivedData(HAL_SPIPort port, uint32_t* buffer,
int32_t numToRead, double timeout,
int32_t* status);
/**
* Gets the count of how many SPI accumulations have been missed.
*
* @param[in] port The number of the port to use. 0-3 for Onboard CS0-CS2, 4
* for MXP.
* @param[out] status the error code, or 0 for success
* @return The number of missed accumulations.
*/
int32_t HAL_GetSPIAutoDroppedCount(HAL_SPIPort port, int32_t* status);
/**
* Configure the Auto SPI Stall time between reads.
*
* @param[in] port The number of the port to use. 0-3 for Onboard
* CS0-CS2, 4 for MXP.
* @param[in] csToSclkTicks the number of ticks to wait before asserting the
* cs pin
* @param[in] stallTicks the number of ticks to stall for
* @param[in] pow2BytesPerRead the number of bytes to read before stalling
* @param[out] status the error code, or 0 for success
*/
void HAL_ConfigureSPIAutoStall(HAL_SPIPort port, int32_t csToSclkTicks,
int32_t stallTicks, int32_t pow2BytesPerRead,
int32_t* status);
#ifdef __cplusplus
} // extern "C"
#endif
/** @} */