Fix RT priority docs (NFC) (#3098)

The ranges and which value was specified as highest were incorrect on
some of them. On Linux, the range is 1 to 99 with 99 being highest.

From `man 7 sched`:
```
Processes scheduled under one of the real-time policies (SCHED_FIFO,
SCHED_RR) have a sched_priority value in the range 1 (low) to 99 (high).
```

Also clean up the relevant javadoc and doxygen comments.

hal/src/main/native/athena/Threads.cpp

@@ -32,8 +32,8 @@ int32_t HAL_GetThreadPriority(NativeThreadHandle handle, HAL_Bool* isRealTime,
     return sch.sched_priority;
   } else {
     *isRealTime = false;
-    // 0 is the only suppored priority for non-realtime, so scale to 1
-    return 1;
+    // 0 is the only supported priority for non-real-time
+    return 0;
   }
 }
 

hal/src/main/native/include/hal/Threads.h

@@ -21,11 +21,13 @@ extern "C" {
 /**
  * Gets the thread priority for the specified thread.
  *
- * @param handle     Native handle pointer to the thread to get the priority for
- * @param isRealTime Set to true if thread is realtime, otherwise false
- * @param status     Error status variable. 0 on success
- * @return           The current thread priority. Scaled 1-99, with 1 being
- * highest.
+ * @param handle     Native handle pointer to the thread to get the priority
+ *                   for.
+ * @param isRealTime Set to true if thread is real-time, otherwise false.
+ * @param status     Error status variable. 0 on success.
+ * @return           The current thread priority. For real-time, this is 1-99
+ *                   with 99 being highest. For non-real-time, this is 0. See
+ *                   "man 7 sched" for details.
  */
 int32_t HAL_GetThreadPriority(NativeThreadHandle handle, HAL_Bool* isRealTime,
                               int32_t* status);
@@ -34,23 +36,25 @@ int32_t HAL_GetThreadPriority(NativeThreadHandle handle, HAL_Bool* isRealTime,
  * Gets the thread priority for the current thread.
  *
  * @param handle     Native handle pointer to the thread to get the priority for
- * @param isRealTime Set to true if thread is realtime, otherwise false
- * @param status     Error status variable. 0 on success
- * @return           The current thread priority. Scaled 1-99, with 1 being
- * highest.
+ * @param isRealTime Set to true if thread is real-time, otherwise false.
+ * @param status     Error status variable. 0 on success.
+ * @return           The current thread priority. For real-time, this is 1-99
+ *                   with 99 being highest. For non-real-time, this is 0. See
+ *                   "man 7 sched" for details.
  */
 int32_t HAL_GetCurrentThreadPriority(HAL_Bool* isRealTime, int32_t* status);
 
 /**
  * Sets the thread priority for the specified thread.
  *
- * @param thread   Reference to the thread to set the priority of
- * @param realTime Set to true to set a realtime priority, false for standard
- * priority
- * @param priority Priority to set the thread to. Scaled 1-99, with 1 being
- * highest
- * @param status   Error status variable. 0 on success
- * @return         The success state of setting the priority
+ * @param thread   Reference to the thread to set the priority of.
+ * @param realTime Set to true to set a real-time priority, false for standard
+ *                 priority.
+ * @param priority Priority to set the thread to. For real-time, this is 1-99
+ *                 with 99 being highest. For non-real-time, this is forced to
+ *                 0. See "man 7 sched" for more details.
+ * @param status   Error status variable. 0 on success.
+ * @return         True on success.
  */
 HAL_Bool HAL_SetThreadPriority(NativeThreadHandle handle, HAL_Bool realTime,
                                int32_t priority, int32_t* status);
@@ -58,13 +62,14 @@ HAL_Bool HAL_SetThreadPriority(NativeThreadHandle handle, HAL_Bool realTime,
 /**
  * Sets the thread priority for the current thread.
  *
- * @param thread   Reference to the thread to set the priority of
- * @param realTime Set to true to set a realtime priority, false for standard
- * priority
- * @param priority Priority to set the thread to. Scaled 1-99, with 1 being
- * highest
- * @param status   Error status variable. 0 on success
- * @return         The success state of setting the priority
+ * @param thread   Reference to the thread to set the priority of.
+ * @param realTime Set to true to set a real-time priority, false for standard
+ *                 priority.
+ * @param priority Priority to set the thread to. For real-time, this is 1-99
+ *                 with 99 being highest. For non-real-time, this is forced to
+ *                 0. See "man 7 sched" for more details.
+ * @param status   Error status variable. 0 on success.
+ * @return         True on success.
  */
 HAL_Bool HAL_SetCurrentThreadPriority(HAL_Bool realTime, int32_t priority,
                                       int32_t* status);

wpilibc/src/main/native/include/frc/Notifier.h

@@ -46,8 +46,9 @@ class Notifier : public ErrorBase {
    * This is useful for reducing scheduling jitter on processes which are
    * sensitive to timing variance, like model-based control.
    *
-   * @param priority The FIFO real-time scheduler priority ([0..100] where a
-   *                 lower number represents higher priority).
+   * @param priority The FIFO real-time scheduler priority ([1..99] where a
+   *                 higher number represents higher priority). See "man 7
+   *                 sched" for more details.
    * @param handler  The handler is called at the notification time which is set
    *                 using StartSingle or StartPeriodic.
    */

wpilibc/src/main/native/include/frc/Threads.h

@@ -12,16 +12,20 @@ namespace frc {
  * Get the thread priority for the specified thread.
  *
  * @param thread     Reference to the thread to get the priority for.
- * @param isRealTime Set to true if thread is realtime, otherwise false.
- * @return The current thread priority. Scaled 1-99, with 1 being highest.
+ * @param isRealTime Set to true if thread is real-time, otherwise false.
+ * @return           The current thread priority. For real-time, this is 1-99
+ *                   with 99 being highest. For non-real-time, this is 0. See
+ *                   "man 7 sched" for details.
  */
 int GetThreadPriority(std::thread& thread, bool* isRealTime);
 
 /**
  * Get the thread priority for the current thread
  *
- * @param isRealTime Set to true if thread is realtime, otherwise false.
- * @return The current thread priority. Scaled 1-99.
+ * @param isRealTime Set to true if thread is real-time, otherwise false.
+ * @return           The current thread priority. For real-time, this is 1-99
+ *                   with 99 being highest. For non-real-time, this is 0. See
+ *                   "man 7 sched" for details.
  */
 int GetCurrentThreadPriority(bool* isRealTime);
 
@@ -29,26 +33,24 @@ int GetCurrentThreadPriority(bool* isRealTime);
  * Sets the thread priority for the specified thread
  *
  * @param thread   Reference to the thread to set the priority of.
- * @param realTime Set to true to set a realtime priority, false for standard
+ * @param realTime Set to true to set a real-time priority, false for standard
  *                 priority.
- * @param priority Priority to set the thread to. Scaled 1-99, with 1 being
- *                 highest. On RoboRIO, priority is ignored for non realtime
- *                 setting.
- *
- * @return The success state of setting the priority
+ * @param priority Priority to set the thread to. For real-time, this is 1-99
+ *                 with 99 being highest. For non-real-time, this is forced to
+ *                 0. See "man 7 sched" for more details.
+ * @return         True on success.
  */
 bool SetThreadPriority(std::thread& thread, bool realTime, int priority);
 
 /**
  * Sets the thread priority for the current thread
  *
- * @param realTime Set to true to set a realtime priority, false for standard
+ * @param realTime Set to true to set a real-time priority, false for standard
  *                 priority.
- * @param priority Priority to set the thread to. Scaled 1-99, with 1 being
- *                 highest. On RoboRIO, priority is ignored for non realtime
- *                 setting.
- *
- * @return The success state of setting the priority
+ * @param priority Priority to set the thread to. For real-time, this is 1-99
+ *                 with 99 being highest. For non-real-time, this is forced to
+ *                 0. See "man 7 sched" for more details.
+ * @return         True on success.
  */
 bool SetCurrentThreadPriority(bool realTime, int priority);
 

wpilibj/src/main/java/edu/wpi/first/wpilibj/Threads.java

@@ -10,16 +10,17 @@ public final class Threads {
   /**
    * Get the thread priority for the current thread.
    *
-   * @return The current thread priority. Scaled 1-99.
+   * @return The current thread priority. For real-time, this is 1-99 with 99 being highest. For
+   *     non-real-time, this is 0. See "man 7 sched" for details.
    */
   public static int getCurrentThreadPriority() {
     return ThreadsJNI.getCurrentThreadPriority();
   }
 
   /**
-   * Get if the current thread is realtime.
+   * Get if the current thread is real-time.
    *
-   * @return If the current thread is realtime
+   * @return If the current thread is real-time.
    */
   public static boolean getCurrentThreadIsRealTime() {
     return ThreadsJNI.getCurrentThreadIsRealTime();
@@ -28,10 +29,10 @@ public final class Threads {
   /**
    * Sets the thread priority for the current thread.
    *
-   * @param realTime Set to true to set a realtime priority, false for standard priority
-   * @param priority Priority to set the thread to. Scaled 1-99, with 1 being highest. On RoboRIO,
-   *     priority is ignored for non realtime setting
-   * @return The success state of setting the priority
+   * @param realTime Set to true to set a real-time priority, false for standard priority.
+   * @param priority Priority to set the thread to. For real-time, this is 1-99 with 99 being
+   *     highest. For non-real-time, this is forced to 0. See "man 7 sched" for details.
+   * @return True on success.
    */
   public static boolean setCurrentThreadPriority(boolean realTime, int priority) {
     return ThreadsJNI.setCurrentThreadPriority(realTime, priority);

wpiutil/src/test/native/cpp/priority_mutex_test.cpp

@@ -55,7 +55,7 @@ void SetProcessorAffinity(int32_t core_id) {
 
 void SetThreadRealtimePriorityOrDie(int32_t priority) {
   struct sched_param param;
-  // Set realtime priority for this thread
+  // Set real-time priority for this thread
   param.sched_priority = priority + sched_get_priority_min(SCHED_RR);
   ASSERT_EQ(pthread_setschedparam(pthread_self(), SCHED_RR, &param), 0)
       << ": Failed to set scheduler priority.";