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
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
// 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 "hal/AnalogTrigger.h"
#include "hal/Types.h"
/**
* @defgroup hal_dma DMA Functions
* @ingroup hal_capi
* @{
*/
/**
* The DMA Read Status.
*/
HAL_ENUM(HAL_DMAReadStatus) {
HAL_DMA_OK = 1,
HAL_DMA_TIMEOUT = 2,
HAL_DMA_ERROR = 3,
};
/**
* Buffer for containing all DMA data for a specific sample.
*/
struct HAL_DMASample {
uint32_t readBuffer[74];
int32_t channelOffsets[22];
uint64_t timeStamp;
uint32_t captureSize;
uint8_t triggerChannels;
};
#ifdef __cplusplus
extern "C" {
#endif
/**
* Initializes an object for performing DMA transfers.
*
* @param[out] status Error status variable. 0 on success.
* @return the created dma handle
*/
HAL_DMAHandle HAL_InitializeDMA(int32_t* status);
/**
* Frees a DMA object.
*
* @param handle the dma handle
*/
void HAL_FreeDMA(HAL_DMAHandle handle);
/**
* Pauses or unpauses a DMA transfer.
*
* This can only be called while DMA is running.
*
* @param[in] handle the dma handle
* @param[in] pause true to pause transfers, false to resume.
* @param[out] status Error status variable. 0 on success.
*/
void HAL_SetDMAPause(HAL_DMAHandle handle, HAL_Bool pause, int32_t* status);
/**
* Sets DMA transfers to occur at a specific timed interval.
*
* This will remove any external triggers. Only timed or external is supported.
*
* Only 1 timed period is supported.
*
* This can only be called if DMA is not started.
*
* @param[in] handle the dma handle
* @param[in] periodSeconds the period to trigger in seconds
* @param[out] status Error status variable. 0 on success.
*/
void HAL_SetDMATimedTrigger(HAL_DMAHandle handle, double periodSeconds,
int32_t* status);
/**
* Sets DMA transfers to occur at a specific timed interval in FPGA cycles.
*
* This will remove any external triggers. Only timed or external is supported.
*
* Only 1 timed period is supported
*
* The FPGA currently runs at 40 MHz, but this can change.
* HAL_GetSystemClockTicksPerMicrosecond can be used to get a computable value
* for this.
*
* This can only be called if DMA is not started.
*
* @param[in] handle the dma handle
* @param[in] cycles the period to trigger in FPGA cycles
* @param[out] status Error status variable. 0 on success.
*/
void HAL_SetDMATimedTriggerCycles(HAL_DMAHandle handle, uint32_t cycles,
int32_t* status);
/**
* Adds position data for an encoder to be collected by DMA.
*
* This can only be called if DMA is not started.
*
* @param[in] handle the dma handle
* @param[in] encoderHandle the encoder to add
* @param[out] status Error status variable. 0 on success.
*/
void HAL_AddDMAEncoder(HAL_DMAHandle handle, HAL_EncoderHandle encoderHandle,
int32_t* status);
/**
* Adds timer data for an encoder to be collected by DMA.
*
* This can only be called if DMA is not started.
*
* @param[in] handle the dma handle
* @param[in] encoderHandle the encoder to add
* @param[out] status Error status variable. 0 on success.
*/
void HAL_AddDMAEncoderPeriod(HAL_DMAHandle handle,
HAL_EncoderHandle encoderHandle, int32_t* status);
/**
* Adds position data for an counter to be collected by DMA.
*
* This can only be called if DMA is not started.
*
* @param[in] handle the dma handle
* @param[in] counterHandle the counter to add
* @param[out] status Error status variable. 0 on success.
*/
void HAL_AddDMACounter(HAL_DMAHandle handle, HAL_CounterHandle counterHandle,
int32_t* status);
/**
* Adds timer data for an counter to be collected by DMA.
*
* This can only be called if DMA is not started.
*
* @param[in] handle the dma handle
* @param[in] counterHandle the counter to add
* @param[out] status Error status variable. 0 on success.
*/
void HAL_AddDMACounterPeriod(HAL_DMAHandle handle,
HAL_CounterHandle counterHandle, int32_t* status);
/**
* Adds a digital source to be collected by DMA.
*
* This can only be called if DMA is not started.
*
* @param[in] handle the dma handle
* @param[in] digitalSourceHandle the digital source to add
* @param[out] status Error status variable. 0 on success.
*/
void HAL_AddDMADigitalSource(HAL_DMAHandle handle,
HAL_Handle digitalSourceHandle, int32_t* status);
/**
* Adds an analog input to be collected by DMA.
*
* This can only be called if DMA is not started.
*
* @param[in] handle the dma handle
* @param[in] aInHandle the analog input to add
* @param[out] status Error status variable. 0 on success.
*/
void HAL_AddDMAAnalogInput(HAL_DMAHandle handle,
HAL_AnalogInputHandle aInHandle, int32_t* status);
/**
* Adds averaged data of an analog input to be collected by DMA.
*
* This can only be called if DMA is not started.
*
* @param[in] handle the dma handle
* @param[in] aInHandle the analog input to add
* @param[out] status Error status variable. 0 on success.
*/
void HAL_AddDMAAveragedAnalogInput(HAL_DMAHandle handle,
HAL_AnalogInputHandle aInHandle,
int32_t* status);
/**
* Adds accumulator data of an analog input to be collected by DMA.
*
* This can only be called if DMA is not started.
*
* @param[in] handle the dma handle
* @param[in] aInHandle the analog input to add
* @param[out] status Error status variable. 0 on success.
*/
void HAL_AddDMAAnalogAccumulator(HAL_DMAHandle handle,
HAL_AnalogInputHandle aInHandle,
int32_t* status);
/**
* Adds a duty cycle input to be collected by DMA.
*
* This can only be called if DMA is not started.
*
* @param[in] handle the dma handle
* @param[in] dutyCycleHandle the duty cycle input to add
* @param[out] status Error status variable. 0 on success.
*/
void HAL_AddDMADutyCycle(HAL_DMAHandle handle,
HAL_DutyCycleHandle dutyCycleHandle, int32_t* status);
/**
* Sets DMA transfers to occur on an external trigger.
*
* This will remove any timed trigger set. Only timed or external is supported.
*
* Up to 8 external triggers are currently supported.
*
* This can only be called if DMA is not started.
*
* @param[in] handle the dma handle
* @param[in] digitalSourceHandle the digital source handle (either a
* HAL_AnalogTriggerHandle or a
* HAL_DigitalHandle)
* @param[in] analogTriggerType the analog trigger type if the source is an
* analog trigger
* @param[in] rising true to trigger on rising edge
* @param[in] falling true to trigger on falling edge
* @param[out] status Error status variable. 0 on success.
* @return the index of the trigger
*/
int32_t HAL_SetDMAExternalTrigger(HAL_DMAHandle handle,
HAL_Handle digitalSourceHandle,
HAL_AnalogTriggerType analogTriggerType,
HAL_Bool rising, HAL_Bool falling,
int32_t* status);
/**
* Clear all sensors from the DMA collection list.
*
* This can only be called if DMA is not started.
*
* @param[in] handle the dma handle
* @param[out] status Error status variable. 0 on success.
*/
void HAL_ClearDMASensors(HAL_DMAHandle handle, int32_t* status);
/**
* Clear all external triggers from the DMA trigger list.
*
* This can only be called if DMA is not started.
*
* @param[in] handle the dma handle
* @param[out] status Error status variable. 0 on success.
*/
void HAL_ClearDMAExternalTriggers(HAL_DMAHandle handle, int32_t* status);
/**
* Starts DMA Collection.
*
* @param[in] handle the dma handle
* @param[in] queueDepth the number of objects to be able to queue
* @param[out] status Error status variable. 0 on success.
*/
void HAL_StartDMA(HAL_DMAHandle handle, int32_t queueDepth, int32_t* status);
/**
* Stops DMA Collection.
*
* @param[in] handle the dma handle
* @param[out] status Error status variable. 0 on success.
*/
void HAL_StopDMA(HAL_DMAHandle handle, int32_t* status);
/**
* Gets the direct pointer to the DMA object.
*
* This is only to be used if absolute maximum performance is required. This
* will only be valid until the handle is freed.
*
* @param handle the dma handle
*/
void* HAL_GetDMADirectPointer(HAL_DMAHandle handle);
/**
* Reads a DMA sample using a direct DMA pointer.
*
* See HAL_ReadDMA for full documentation.
*
* @param[in] dmaPointer direct DMA pointer
* @param[in] dmaSample the sample object to place data into
* @param[in] timeoutSeconds the time to wait for data to be queued before
* timing out
* @param[in] remainingOut the number of samples remaining in the queue
* @param[out] status Error status variable. 0 on success.
*/
enum HAL_DMAReadStatus HAL_ReadDMADirect(void* dmaPointer,
HAL_DMASample* dmaSample,
double timeoutSeconds,
int32_t* remainingOut,
int32_t* status);
/**
* Reads a DMA sample from the queue.
*
*
* @param[in] handle the dma handle
* @param[in] dmaSample the sample object to place data into
* @param[in] timeoutSeconds the time to wait for data to be queued before
* timing out
* @param[in] remainingOut the number of samples remaining in the queue
* @param[out] status Error status variable. 0 on success.
* @return the success result of the sample read
*/
enum HAL_DMAReadStatus HAL_ReadDMA(HAL_DMAHandle handle,
HAL_DMASample* dmaSample,
double timeoutSeconds, int32_t* remainingOut,
int32_t* status);
// The following are helper functions for reading data from samples
/**
* Returns the timestamp of the sample.
* This is in the same time domain as HAL_GetFPGATime().
*
* @param[in] dmaSample the sample to read from
* @param[out] status Error status variable. 0 on success.
* @return timestamp in microseconds since FPGA Initialization
*/
uint64_t HAL_GetDMASampleTime(const HAL_DMASample* dmaSample, int32_t* status);
/**
* Returns the raw distance data for an encoder from the sample.
*
* This can be scaled with DistancePerPulse and DecodingScaleFactor to match the
* result of GetDistance()
*
* @param[in] dmaSample the sample to read from
* @param[in] encoderHandle the encoder handle
* @param[out] status Error status variable. 0 on success.
* @return raw encoder ticks
*/
int32_t HAL_GetDMASampleEncoderRaw(const HAL_DMASample* dmaSample,
HAL_EncoderHandle encoderHandle,
int32_t* status);
/**
* Returns the distance data for an counter from the sample.
*
* @param[in] dmaSample the sample to read from
* @param[in] counterHandle the counter handle
* @param[out] status Error status variable. 0 on success.
* @return counter ticks
*/
int32_t HAL_GetDMASampleCounter(const HAL_DMASample* dmaSample,
HAL_CounterHandle counterHandle,
int32_t* status);
/**
* Returns the raw period data for an encoder from the sample.
*
* This can be scaled with DistancePerPulse and DecodingScaleFactor to match the
* result of GetRate()
*
* @param[in] dmaSample the sample to read from
* @param[in] encoderHandle the encoder handle
* @param[out] status Error status variable. 0 on success.
* @return raw encoder period
*/
int32_t HAL_GetDMASampleEncoderPeriodRaw(const HAL_DMASample* dmaSample,
HAL_EncoderHandle encoderHandle,
int32_t* status);
/**
* Returns the period data for an counter from the sample.
*
* @param[in] dmaSample the sample to read from
* @param[in] counterHandle the counter handle
* @param[out] status Error status variable. 0 on success.
* @return counter period
*/
int32_t HAL_GetDMASampleCounterPeriod(const HAL_DMASample* dmaSample,
HAL_CounterHandle counterHandle,
int32_t* status);
/**
* Returns the state of a digital source from the sample.
*
* @param[in] dmaSample the sample to read from
* @param[in] dSourceHandle the digital source handle
* @param[out] status Error status variable. 0 on success.
* @return digital source state
*/
HAL_Bool HAL_GetDMASampleDigitalSource(const HAL_DMASample* dmaSample,
HAL_Handle dSourceHandle,
int32_t* status);
/**
* Returns the raw analog data for an analog input from the sample.
*
* This can be scaled with HAL_GetAnalogValueToVolts to match GetVoltage().
*
* @param[in] dmaSample the sample to read from
* @param[in] aInHandle the analog input handle
* @param[out] status Error status variable. 0 on success.
* @return raw analog data
*/
int32_t HAL_GetDMASampleAnalogInputRaw(const HAL_DMASample* dmaSample,
HAL_AnalogInputHandle aInHandle,
int32_t* status);
/**
* Returns the raw averaged analog data for an analog input from the sample.
*
* This can be scaled with HAL_GetAnalogValueToVolts to match
* GetAveragedVoltage().
*
* @param[in] dmaSample the sample to read from
* @param[in] aInHandle the analog input handle
* @param[out] status Error status variable. 0 on success.
* @return raw averaged analog data
*/
int32_t HAL_GetDMASampleAveragedAnalogInputRaw(const HAL_DMASample* dmaSample,
HAL_AnalogInputHandle aInHandle,
int32_t* status);
/**
* Returns the analog accumulator data for an analog input from the sample.
*
* @param[in] dmaSample the sample to read from
* @param[in] aInHandle the analog input handle
* @param[in] count the accumulator count
* @param[in] value the accumulator value
* @param[out] status Error status variable. 0 on success.
*/
void HAL_GetDMASampleAnalogAccumulator(const HAL_DMASample* dmaSample,
HAL_AnalogInputHandle aInHandle,
int64_t* count, int64_t* value,
int32_t* status);
/**
* Returns the raw duty cycle input ratio data from the sample.
*
* Use HAL_GetDutyCycleOutputScaleFactor to scale this to a percentage.
*
* @param[in] dmaSample the sample to read from
* @param[in] dutyCycleHandle the duty cycle handle
* @param[out] status Error status variable. 0 on success.
* @return raw duty cycle input data
*/
int32_t HAL_GetDMASampleDutyCycleOutputRaw(const HAL_DMASample* dmaSample,
HAL_DutyCycleHandle dutyCycleHandle,
int32_t* status);
#ifdef __cplusplus
} // extern "C"
#endif
/** @} */