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 * The NotifierJNI class directly wraps the C++ HAL Notifier.
009 *
010 * <p>This class is not meant for direct use by teams. Instead, the edu.wpi.first.wpilibj.Notifier
011 * class, which corresponds to the C++ Notifier class, should be used.
012 *
013 * @see "hal/Notifier.h"
014 */
015public class NotifierJNI extends JNIWrapper {
016  /**
017   * Initializes a notifier.
018   *
019   * <p>A notifier is an FPGA controller timer that triggers at requested intervals based on the
020   * FPGA time. This can be used to make precise control loops.
021   *
022   * @return the created notifier
023   * @see "HAL_InitializeNotifier"
024   */
025  public static native int initializeNotifier();
026
027  /**
028   * Sets the HAL notifier thread priority.
029   *
030   * <p>The HAL notifier thread is responsible for managing the FPGA's notifier interrupt and waking
031   * up user's Notifiers when it's their time to run. Giving the HAL notifier thread real-time
032   * priority helps ensure the user's real-time Notifiers, if any, are notified to run in a timely
033   * manner.
034   *
035   * @param realTime Set to true to set a real-time priority, false for standard priority.
036   * @param priority Priority to set the thread to. For real-time, this is 1-99 with 99 being
037   *     highest. For non-real-time, this is forced to 0. See "man 7 sched" for more details.
038   * @return True on success.
039   * @see "HAL_SetNotifierThreadPriority"
040   */
041  public static native boolean setHALThreadPriority(boolean realTime, int priority);
042
043  /**
044   * Sets the name of the notifier.
045   *
046   * @param notifierHandle Notifier handle.
047   * @param name Notifier name.
048   * @see "HAL_SetNotifierName"
049   */
050  public static native void setNotifierName(int notifierHandle, String name);
051
052  /**
053   * Stops a notifier from running.
054   *
055   * <p>This will cause any call into waitForNotifierAlarm to return with time = 0.
056   *
057   * @param notifierHandle the notifier handle
058   * @see "HAL_StopNotifier"
059   */
060  public static native void stopNotifier(int notifierHandle);
061
062  /**
063   * Cleans a notifier.
064   *
065   * <p>Note this also stops a notifier if it is already running.
066   *
067   * @param notifierHandle the notifier handle
068   * @see "HAL_CleanNotifier"
069   */
070  public static native void cleanNotifier(int notifierHandle);
071
072  /**
073   * Updates the trigger time for a notifier.
074   *
075   * <p>Note that this time is an absolute time relative to getFPGATime()
076   *
077   * @param notifierHandle the notifier handle
078   * @param triggerTime the updated trigger time
079   * @see "HAL_UpdateNotifierAlarm"
080   */
081  public static native void updateNotifierAlarm(int notifierHandle, long triggerTime);
082
083  /**
084   * Cancels the next notifier alarm.
085   *
086   * <p>This does not cause waitForNotifierAlarm to return.
087   *
088   * @param notifierHandle the notifier handle
089   * @see "HAL_CancelNotifierAlarm"
090   */
091  public static native void cancelNotifierAlarm(int notifierHandle);
092
093  /**
094   * Waits for the next alarm for the specific notifier.
095   *
096   * <p>This is a blocking call until either the time elapses or stopNotifier gets called. If the
097   * latter occurs, this function will return zero and any loops using this function should exit.
098   * Failing to do so can lead to use-after-frees.
099   *
100   * @param notifierHandle the notifier handle
101   * @return the FPGA time the notifier returned
102   */
103  public static native long waitForNotifierAlarm(int notifierHandle);
104
105  /** Utility class. */
106  private NotifierJNI() {}
107}