rtapi: explain why realtime scheduling is unavailable

The fallback-to-POSIX warning said only "SCHED_FIFO not permitted"
which left users guessing among missing caps, stock kernel, or
rlimits. Now print the sched_setscheduler errno, the effective
cap_sys_nice and cap_ipc_lock state via libcap, and mention
LINUXCNC_FORCE_REALTIME as a testing-only override. Addresses the
diagnostic-output request in issue #3928.

While here, switch detect_preempt_rt and has_setuid_root from
__attribute__((unused)) to static inline so the unused-function
suppression matches the wider codebase style.

Author: grandixximo

src/rtapi/Submakefile

@@ -44,7 +44,7 @@ $(call TOOBJSDEPS, $(RTAPI_APP_SRCS)): EXTRAFLAGS += -DSIM \
 	-UULAPI -DRTAPI -pthread
 ../bin/rtapi_app: $(call TOOBJS, $(RTAPI_APP_SRCS))
 	$(ECHO) Linking $(notdir $@)
-	$(Q)$(CXX) -rdynamic -o $@ $^ $(LIBDL) -pthread -lrt -lfmt $(LIBUDEV_LIBS) -ldl $(LDFLAGS)
+	$(Q)$(CXX) -rdynamic -o $@ $^ $(LIBDL) -pthread -lrt -lfmt $(LIBUDEV_LIBS) -ldl -lcap $(LDFLAGS)
 TARGETS += ../bin/rtapi_app
 endif
 

src/rtapi/uspace_common.h

@@ -359,18 +359,14 @@ int rtapi_is_kernelspace() { return 0; }
 // for diagnostic warning at startup; callers must not gate behavior on
 // the kernel string, since SCHED_FIFO on a PREEMPT_DYNAMIC kernel is still
 // useful (better than SCHED_OTHER, worse than PREEMPT_RT).
-// Marked unused because uspace_common.h is also included from ULAPI TUs
-// that do not reference it.
-__attribute__((unused))
-static int detect_preempt_rt() {
+static inline int detect_preempt_rt() {
     struct utsname u;
     if(uname(&u) < 0) return 0;
     return strcasestr(u.version, "PREEMPT RT") != 0
         || strcasestr(u.version, "PREEMPT_RT") != 0;
 }
 #else
-__attribute__((unused))
-static int detect_preempt_rt() {
+static inline int detect_preempt_rt() {
     return 0;
 }
 #endif
@@ -382,11 +378,7 @@ static int detect_preempt_rt() {
 // with udev rules + a 'xenomai'/'evl' group; @hdiethelm has a follow-up
 // planned.  Until then, an unprivileged user on a Xenomai kernel cannot
 // claim the Xenomai backend, and falls back to the SCHED_FIFO probe.
-// Marked unused because the helper is called only when one of the
-// USPACE_RTAI / USPACE_XENOMAI / USPACE_XENOMAI_EVL macros is defined,
-// and the header is included from ULAPI TUs that define none of them.
-__attribute__((unused))
-static int has_setuid_root() {
+static inline int has_setuid_root() {
     return geteuid() == 0;
 }
 
@@ -427,6 +419,11 @@ static int detect_xenomai_evl() {
 }
 #endif
 
+// errno from the most recent sched_setscheduler(SCHED_FIFO) probe.  Zero
+// when the probe succeeded or has not run yet.  Read via
+// rtapi_sched_fifo_errno() from diagnostic code.
+static int rtapi_sched_fifo_last_errno = 0;
+
 // Success-probe for realtime scheduling: briefly try to set SCHED_FIFO on
 // the calling thread and restore the previous policy.  Succeeds when the
 // process holds CAP_SYS_NICE (file caps or setuid root) or has a matching
@@ -436,20 +433,31 @@ static int detect_xenomai_evl() {
 static int can_set_sched_fifo(void) {
     struct sched_param old_param, probe_param;
     int old_policy = sched_getscheduler(0);
-    if(old_policy < 0) return 0;
-    if(sched_getparam(0, &old_param) < 0) return 0;
+    if(old_policy < 0) {
+        rtapi_sched_fifo_last_errno = errno;
+        return 0;
+    }
+    if(sched_getparam(0, &old_param) < 0) {
+        rtapi_sched_fifo_last_errno = errno;
+        return 0;
+    }
 
     memset(&probe_param, 0, sizeof(probe_param));
     probe_param.sched_priority = sched_get_priority_min(SCHED_FIFO);
-    if(sched_setscheduler(0, SCHED_FIFO, &probe_param) < 0)
+    if(sched_setscheduler(0, SCHED_FIFO, &probe_param) < 0) {
+        rtapi_sched_fifo_last_errno = errno;
         return 0;
+    }
 
     // Best-effort restore; if this fails we are still on SCHED_FIFO at
     // minimum priority, which is no worse than where we started.
     sched_setscheduler(0, old_policy, &old_param);
+    rtapi_sched_fifo_last_errno = 0;
     return 1;
 }
 
+static inline int rtapi_sched_fifo_errno(void) { return rtapi_sched_fifo_last_errno; }
+
 // rtapi_is_realtime() reports whether this process can actually run
 // realtime code.  This matches the convention used by JACK, PipeWire,
 // rtkit, Xenomai, and Klipper: surface the observed capability, not

src/rtapi/uspace_rtapi_main.cc

@@ -46,6 +46,7 @@
 #ifdef __linux__
 #include <malloc.h>
 #include <sys/prctl.h>
+#include <sys/capability.h>
 #endif
 #ifdef __FreeBSD__
 #include <pthread_np.h>
@@ -974,15 +975,47 @@ static RtapiApp *makeDllApp(const std::string &dllName, int policy) {
     return result;
 }
 
+// Diagnostic helper: report cap_effective state for a single capability.
+// Returns "yes", "no", or "unknown" if libcap could not introspect.
+#ifdef __linux__
+static const char *cap_effective_str(cap_t caps, cap_value_t cap) {
+    if (!caps) return "unknown";
+    cap_flag_value_t v;
+    if (cap_get_flag(caps, cap, CAP_EFFECTIVE, &v) != 0) return "unknown";
+    return v == CAP_SET ? "yes" : "no";
+}
+#endif
+
 static RtapiApp *makeApp() {
     RtapiApp *app;
     bool rt_ok = rtapi_is_realtime();
     if (!rt_ok) {
+        // Surface the actual reason so the user does not have to guess
+        // between "no caps", "stock kernel", or "wrong rlimits" (issue
+        // #3928).  errno comes from the SCHED_FIFO probe in
+        // can_set_sched_fifo(); cap state comes from libcap.
+        int sched_err = rtapi_sched_fifo_errno();
+#ifdef __linux__
+        cap_t caps = cap_get_proc();
+        const char *nice_s = cap_effective_str(caps, CAP_SYS_NICE);
+        const char *lock_s = cap_effective_str(caps, CAP_IPC_LOCK);
+#else
+        const char *nice_s = "unknown";
+        const char *lock_s = "unknown";
+#endif
         rtapi_print_msg(RTAPI_MSG_ERR,
-            "Note: SCHED_FIFO not permitted for this process, "
-            "falling back to POSIX non-realtime.  "
-            "Run 'sudo make setcap' (preferred) or 'sudo make setuid' "
-            "on rtapi_app to enable realtime scheduling.\n");
+            "Note: realtime scheduling unavailable "
+            "(sched_setscheduler SCHED_FIFO: %s).\n"
+            "  Process capabilities: cap_sys_nice=%s cap_ipc_lock=%s.\n"
+            "  Falling back to POSIX non-realtime.\n"
+            "  Fix: 'sudo make setcap' (preferred) or 'sudo make setuid' "
+            "on rtapi_app.\n"
+            "  Override (testing only): set LINUXCNC_FORCE_REALTIME=1.\n",
+            sched_err ? strerror(sched_err) : "denied",
+            nice_s, lock_s);
+#ifdef __linux__
+        if (caps) cap_free(caps);
+#endif
     }
     if (!rt_ok || harden_rt() < 0) {
         app = makeDllApp("liblinuxcnc-uspace-posix.so.0", SCHED_OTHER);