[hal] Add HAL_GetLastError to enable better error messages from HAL calls (#3320)

This uses thread local storage so a full error string can be provided, not just an error code.

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

@@ -233,6 +233,8 @@ const char* HAL_GetErrorMessage(int32_t code) {
       return HAL_CAN_BUFFER_OVERRUN_MESSAGE;
     case HAL_LED_CHANNEL_ERROR:
       return HAL_LED_CHANNEL_ERROR_MESSAGE;
+    case HAL_USE_LAST_ERROR:
+      return HAL_USE_LAST_ERROR_MESSAGE;
     default:
       return "Unknown error status";
   }

hal/src/main/native/athena/HALInternal.h

@@ -6,7 +6,9 @@
 
 #include <stdint.h>
 
+#include <wpi/Twine.h>
+
 namespace hal {
 void ReleaseFPGAInterrupt(int32_t interruptNumber);
-
+void SetLastError(int32_t status, const wpi::Twine& value);
 }  // namespace hal

hal/src/main/native/cpp/ErrorHandling.cpp

@@ -0,0 +1,41 @@
+// 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.
+
+#include <wpi/SmallString.h>
+#include <wpi/Twine.h>
+
+#include "hal/Errors.h"
+#include "hal/HALBase.h"
+
+namespace {
+struct LastErrorStorage {
+  int32_t status;
+  wpi::SmallString<512> message;
+};
+}  // namespace
+
+static LastErrorStorage& GetThreadLastError() {
+  thread_local LastErrorStorage lastError;
+  return lastError;
+}
+
+namespace hal {
+void SetLastError(int32_t status, const wpi::Twine& value) {
+  LastErrorStorage& lastError = GetThreadLastError();
+  lastError.message.clear();
+  value.toVector(lastError.message);
+  lastError.status = status;
+}
+}  // namespace hal
+
+extern "C" {
+const char* HAL_GetLastError(int32_t* status) {
+  if (*status == HAL_USE_LAST_ERROR) {
+    LastErrorStorage& lastError = GetThreadLastError();
+    *status = lastError.status;
+    return lastError.message.c_str();
+  }
+  return HAL_GetErrorMessage(*status);
+}
+}  // extern "C"

hal/src/main/native/cpp/jni/HALUtil.cpp

@@ -85,7 +85,7 @@ void ThrowUncleanStatusException(JNIEnv* env, wpi::StringRef msg,
 
 void ThrowAllocationException(JNIEnv* env, int32_t minRange, int32_t maxRange,
                               int32_t requestedValue, int32_t status) {
-  const char* message = HAL_GetErrorMessage(status);
+  const char* message = HAL_GetLastError(&status);
   wpi::SmallString<1024> buf;
   wpi::raw_svector_ostream oss(buf);
   oss << " Code: " << status << ". " << message
@@ -96,7 +96,7 @@ void ThrowAllocationException(JNIEnv* env, int32_t minRange, int32_t maxRange,
 }
 
 void ThrowHalHandleException(JNIEnv* env, int32_t status) {
-  const char* message = HAL_GetErrorMessage(status);
+  const char* message = HAL_GetLastError(&status);
   wpi::SmallString<1024> buf;
   wpi::raw_svector_ostream oss(buf);
   oss << " Code: " << status << ". " << message;
@@ -110,7 +110,7 @@ void ReportError(JNIEnv* env, int32_t status, bool doThrow) {
   if (status == HAL_HANDLE_ERROR) {
     ThrowHalHandleException(env, status);
   }
-  const char* message = HAL_GetErrorMessage(status);
+  const char* message = HAL_GetLastError(&status);
   if (doThrow && status < 0) {
     wpi::SmallString<1024> buf;
     wpi::raw_svector_ostream oss(buf);
@@ -119,7 +119,11 @@ void ReportError(JNIEnv* env, int32_t status, bool doThrow) {
   } else {
     std::string func;
     auto stack = GetJavaStackTrace(env, &func, "edu.wpi.first");
-    HAL_SendError(1, status, 0, message, func.c_str(), stack.c_str(), 1);
+    // Make a copy of message for safety, calling back into the HAL might
+    // invalidate the string.
+    wpi::SmallString<256> lastMessage{wpi::StringRef{message}};
+    HAL_SendError(1, status, 0, lastMessage.c_str(), func.c_str(),
+                  stack.c_str(), 1);
   }
 }
 

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

@@ -125,6 +125,10 @@
 #define HAL_SIM_NOT_SUPPORTED -1155
 #define HAL_SIM_NOT_SUPPORTED_MESSAGE "HAL: Method not supported in sim"
 
+#define HAL_USE_LAST_ERROR -1156
+#define HAL_USE_LAST_ERROR_MESSAGE \
+  "HAL: Use HAL_GetLastError(status) to get last error"
+
 #define HAL_CAN_BUFFER_OVERRUN -35007
 #define HAL_CAN_BUFFER_OVERRUN_MESSAGE \
   "HAL: CAN Output Buffer Full. Ensure a device is attached"

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

@@ -22,6 +22,19 @@ HAL_ENUM(HAL_RuntimeType) { HAL_Athena, HAL_Mock };
 extern "C" {
 #endif
 
+/**
+ * Gets the last error set on this thread, or the message for the status code.
+ *
+ * If passed HAL_USE_LAST_ERROR, the last error set on the thread will be
+ * returned.
+ *
+ * @param code  the status code, set to the error status code if input is
+ * HAL_USE_LAST_ERROR
+ * @return      the error message for the code. This does not need to be freed,
+ * but can be overwritten by another hal call on the same thread.
+ */
+const char* HAL_GetLastError(int32_t* status);
+
 /**
  * Gets the error message for a specific status code.
  *

hal/src/main/native/sim/HAL.cpp

@@ -250,6 +250,8 @@ const char* HAL_GetErrorMessage(int32_t code) {
       return HAL_CAN_BUFFER_OVERRUN_MESSAGE;
     case HAL_LED_CHANNEL_ERROR:
       return HAL_LED_CHANNEL_ERROR_MESSAGE;
+    case HAL_USE_LAST_ERROR:
+      return HAL_USE_LAST_ERROR_MESSAGE;
     default:
       return "Unknown error status";
   }