001// Copyright (c) FIRST and other WPILib contributors.
002// Open Source Software; you can modify and/or share it under the terms of
003// the WPILib BSD license file in the root directory of this project.
004
005package edu.wpi.first.hal;
006
007/**
008 * DMA HAL JNI functions.
009 *
010 * @see "hal/DHA.h"
011 */
012public class DMAJNI extends JNIWrapper {
013  /**
014   * Initializes an object for performing DMA transfers.
015   *
016   * @return the created dma handle
017   * @see "HAL_InitializeDMA"
018   */
019  public static native int initialize();
020
021  /**
022   * Frees a DMA object.
023   *
024   * @param handle the dma handle
025   * @see "HAL_FreeDMA"
026   */
027  public static native void free(int handle);
028
029  /**
030   * Pauses or unpauses a DMA transfer.
031   *
032   * <p>This can only be called while DMA is running.
033   *
034   * @param handle the dma handle
035   * @param pause true to pause transfers, false to resume.
036   * @see "HAL_SetDMAPause"
037   */
038  public static native void setPause(int handle, boolean pause);
039
040  /**
041   * Sets DMA transfers to occur at a specific timed interval.
042   *
043   * <p>This will remove any external triggers. Only timed or external is supported.
044   *
045   * <p>Only 1 timed period is supported.
046   *
047   * <p>This can only be called if DMA is not started.
048   *
049   * @param handle the dma handle
050   * @param periodSeconds the period to trigger in seconds
051   * @see "HAL_SetDMATimedTrigger"
052   */
053  public static native void setTimedTrigger(int handle, double periodSeconds);
054
055  /**
056   * Sets DMA transfers to occur at a specific timed interval in FPGA cycles.
057   *
058   * <p>This will remove any external triggers. Only timed or external is supported.
059   *
060   * <p>Only 1 timed period is supported
061   *
062   * <p>The FPGA currently runs at 40 MHz, but this can change.
063   * HAL_GetSystemClockTicksPerMicrosecond can be used to get a computable value for this.
064   *
065   * <p>This can only be called if DMA is not started.
066   *
067   * @param handle the dma handle
068   * @param cycles the period to trigger in FPGA cycles
069   * @see "HAL_SetDMATimedTriggerCycles"
070   */
071  public static native void setTimedTriggerCycles(int handle, int cycles);
072
073  /**
074   * Adds position data for an encoder to be collected by DMA.
075   *
076   * <p>This can only be called if DMA is not started.
077   *
078   * @param handle the dma handle
079   * @param encoderHandle the encoder to add
080   * @see "HAL_AddDMAEncoder"
081   */
082  public static native void addEncoder(int handle, int encoderHandle);
083
084  /**
085   * Adds timer data for an encoder to be collected by DMA.
086   *
087   * <p>This can only be called if DMA is not started.
088   *
089   * @param handle the dma handle
090   * @param encoderHandle the encoder to add
091   * @see "HAL_AddDMAEncoderPeriod"
092   */
093  public static native void addEncoderPeriod(int handle, int encoderHandle);
094
095  /**
096   * Adds position data for an counter to be collected by DMA.
097   *
098   * <p>This can only be called if DMA is not started.
099   *
100   * @param handle the dma handle
101   * @param counterHandle the counter to add
102   * @see "HAL_AddDMACounter"
103   */
104  public static native void addCounter(int handle, int counterHandle);
105
106  /**
107   * Adds timer data for an counter to be collected by DMA.
108   *
109   * @param handle the dma handle
110   * @param counterHandle the counter to add
111   * @see "HAL_AddDMACounterPeriod"
112   */
113  public static native void addCounterPeriod(int handle, int counterHandle);
114
115  /**
116   * Adds a digital source to be collected by DMA.
117   *
118   * <p>This can only be called if DMA is not started.
119   *
120   * @param handle the dma handle
121   * @param digitalSourceHandle the digital source to add
122   * @see "HAL_AddDMADigitalSource"
123   */
124  public static native void addDigitalSource(int handle, int digitalSourceHandle);
125
126  /**
127   * Adds a duty cycle input to be collected by DMA.
128   *
129   * <p>This can only be called if DMA is not started.
130   *
131   * @param handle the dma handle
132   * @param dutyCycleHandle the duty cycle input to add
133   * @see "HAL_AddDMADutyCycle"
134   */
135  public static native void addDutyCycle(int handle, int dutyCycleHandle);
136
137  /**
138   * Adds an analog input to be collected by DMA.
139   *
140   * <p>This can only be called if DMA is not started.
141   *
142   * @param handle the dma handle
143   * @param analogInputHandle the analog input to add
144   * @see "HAL_AddDMAAnalogInput"
145   */
146  public static native void addAnalogInput(int handle, int analogInputHandle);
147
148  /**
149   * Adds averaged data of an analog input to be collected by DMA.
150   *
151   * <p>This can only be called if DMA is not started.
152   *
153   * @param handle the dma handle
154   * @param analogInputHandle the analog input to add
155   * @see "HAL_AddDMAAveragedAnalogInput"
156   */
157  public static native void addAveragedAnalogInput(int handle, int analogInputHandle);
158
159  /**
160   * Adds accumulator data of an analog input to be collected by DMA.
161   *
162   * <p>This can only be called if DMA is not started.
163   *
164   * @param handle the dma handle
165   * @param analogInputHandle the analog input to add
166   * @see "HAL_AddDMAAnalogAccumulator"
167   */
168  public static native void addAnalogAccumulator(int handle, int analogInputHandle);
169
170  /**
171   * Sets DMA transfers to occur on an external trigger.
172   *
173   * <p>This will remove any timed trigger set. Only timed or external is supported.
174   *
175   * <p>Up to 8 external triggers are currently supported.
176   *
177   * <p>This can only be called if DMA is not started.
178   *
179   * @param handle the dma handle
180   * @param digitalSourceHandle the digital source handle (either a HAL_AnalogTriggerHandle or a
181   *     HAL_DigitalHandle)
182   * @param analogTriggerType the analog trigger type if the source is an analog trigger
183   * @param rising true to trigger on rising edge
184   * @param falling true to trigger on falling edge
185   * @return the index of the trigger
186   * @see "HAL_SetDMAExternalTrigger"
187   */
188  public static native int setExternalTrigger(
189      int handle, int digitalSourceHandle, int analogTriggerType, boolean rising, boolean falling);
190
191  /**
192   * Clear all sensors from the DMA collection list.
193   *
194   * <p>This can only be called if DMA is not started.
195   *
196   * @param handle the dma handle
197   * @see "HAL_ClearDMASensors"
198   */
199  public static native void clearSensors(int handle);
200
201  /**
202   * Clear all external triggers from the DMA trigger list.
203   *
204   * <p>This can only be called if DMA is not started.
205   *
206   * @param handle the dma handle
207   * @see "HAL_ClearDMAExternalTriggers"
208   */
209  public static native void clearExternalTriggers(int handle);
210
211  /**
212   * Starts DMA Collection.
213   *
214   * @param handle the dma handle
215   * @param queueDepth the number of objects to be able to queue
216   * @see "HAL_StartDMA"
217   */
218  public static native void startDMA(int handle, int queueDepth);
219
220  /**
221   * Stops DMA Collection.
222   *
223   * @param handle the dma handle
224   * @see "HAL_StopDMA"
225   */
226  public static native void stopDMA(int handle);
227
228  /**
229   * Reads a DMA sample from the queue.
230   *
231   * @param handle the dma handle
232   * @param timeoutSeconds the time to wait for data to be queued before timing out
233   * @param buffer the sample object to place data into
234   * @param sampleStore index 0-21 channelOffsets, index 22: capture size, index 23: triggerChannels
235   *     (bitflags), index 24: remaining, index 25: read status
236   * @return timestamp of the DMA Sample
237   */
238  public static native long readDMA(
239      int handle, double timeoutSeconds, int[] buffer, int[] sampleStore);
240
241  /**
242   * Get the sensor DMA sample.
243   *
244   * @param handle the dma handle
245   * @return The DMA sample
246   */
247  public static native DMAJNISample.BaseStore getSensorReadData(int handle);
248
249  /** Utility class. */
250  private DMAJNI() {}
251}