Add hal_get_realtime_type() and deprecate rtapi_is_realtimei()

rtapi_is_realtime() was always unrelaiable. hal_get_realtime_type()
returns now the true running realtime type trought the HAL for user and
realtime components.

This function is also exposed trought python hal.

Author: hdiethelm

docs/src/config/python-hal-interface.adoc

@@ -48,6 +48,17 @@ Message level constants:
 * `hal.MSG_DBG` - Additionally include debugging information
 * `hal.MSG_ALL` - Print all messages encountered, disregarding level
 
+Realtime type constants:
+
+* `hal.REALTIME_TYPE_UNINITIALIZED` - Real time module not running
+* `hal.REALTIME_TYPE_NONE` - No realtime available
+* `hal.REALTIME_TYPE_RTAI` - RTAI kernel mode
+* `hal.REALTIME_TYPE_PREEMPT_DYNAMIC` - Preempt dynamic: avaliable in vanilla kernel, not recommended
+* `hal.REALTIME_TYPE_PREEMPT_RT` - Preempt RT
+* `hal.REALTIME_TYPE_LXRT` - LXRT, userspace implementation for RTAI
+* `hal.REALTIME_TYPE_XENOMAI` - Xenomai 3
+* `hal.REALTIME_TYPE_XENOMAI_EVL` - Xenomai 4 aka Xenomai EVL
+
 System information:
 
 * `hal.is_kernelspace` - One (1) if RTAPI runs in the kernel, otherwise zero (0)
@@ -76,9 +87,14 @@ comp_name = f"halpy{os.getpid()}"
 if not hal.is_initialized():
     comp = hal.component(comp_name)
 
-ret = hal.component_exists("passthrough")
+type = hal.get_realtime_type()
 ----
 
+hal.get_realtime_type()::
+Returns the type of the running realtime system.
+Might return `hal.REALTIME_TYPE_UNINITIALIZED` if `rtapi_app` is not running.
+See xref:_hal_constants[realtime type constants].
+
 hal.component_exists(_name_:string)::
 Returns a boolean to indicate whether or not the specified component exist at this time.
 

docs/src/man/man3/hal_get_realtime_type.3.adoc

@@ -0,0 +1,21 @@
+:manvolnum: 3
+
+= hal_get_realtime_type(3)
+
+== NAME
+
+hal_get_realtime_type - Get the type of the running realtime
+
+== SYNTAX
+
+hal_realtime_type_t hal_get_realtime_type()
+
+== RETURN VALUE
+
+*hal_get_realtime_type* returns the type of the running realtime system.
+
+For uspace, this returns *REALTIME_TYPE_UNINITIALIZED* if *rtapi_all* is not running. It is save to assume
+this never happens in realtime components. But userspace components can be loaded withouth *rtapi_all* being
+started.
+
+For rtai, this always returns *REALTIME_TYPE_RTAI*.

docs/src/man/man3/rtapi_is.3.adoc

@@ -9,7 +9,7 @@ rtapi_is - details of rtapi configuration
 [source,c]
 ----
 int rtapi_is_kernelspace();
-int rtapi_is_realtime();
+int rtapi_is_realtime(); (DEPRECATED)
 ----
 
 == DESCRIPTION
@@ -18,15 +18,18 @@ int rtapi_is_realtime();
 and zero when they run in userspace (e.g., under uspace).
 
 *rtapi_is_realtime()* returns nonzero when capable of running with realtime guarantees.
+
+(DEPRECATED) use *hal_get_realtime_type()* instead. *rtapi_is_realtime()* works only in realtime context.
+
 For rtai, this always returns nonzero (but actually loading realtime modules will fail if not running under the appropriate kernel).
-For uspace, this returns nonzero when the running kernel indicates it is capable of realtime performance.
-If *rtapi_app* is not setuid root,
-this returns nonzero even though *rtapi_app* will not be able to obtain realtime scheduling or hardware access,
-so e.g., attempting to *loadrt* a hardware driver will fail.
+For uspace, this returns nonzero when the running kernel indicates it is capable of realtime performance and *rtapi_app* has the
+required capabilities or is setuid root.
+If *rtapi_app* is not setuid root or setcap with the proper capabilities,
+this returns zero.
 
 == REALTIME CONSIDERATIONS
 
-May be called from non-realtime or from realtime setup code.
+May only be called from realtime setup code.
 *rtapi_is_realtime()* may perform filesystem I/O.
 
 == RETURN VALUE

src/hal/hal.h

@@ -237,6 +237,11 @@ extern int hal_unready(int comp_id);
 */
 extern char* hal_comp_name(int comp_id);
 
+/** hal_get_realtime_type() returns the type of the running real time
+*/
+typedef rtapi_realtime_type_t hal_realtime_type_t;
+extern hal_realtime_type_t hal_get_realtime_type(void);
+
 /** The HAL maintains lists of variables, functions, and so on in
     a central database, located in shared memory so all components
     can access it.  To prevent contention, functions that may

src/hal/hal_lib.c

@@ -53,6 +53,7 @@
 
 */
 
+#define RTAPI_HAL_PRIV  /* Use rtapi/hal private functions */
 #include <rtapi.h>		/* RTAPI realtime OS API */
 #include "hal.h"		/* HAL public API decls */
 #include "hal_priv.h"		/* HAL private decls */
@@ -537,6 +538,15 @@ char *hal_comp_name(int comp_id)
     return result;
 }
 
+hal_realtime_type_t hal_get_realtime_type() {
+    if (hal_data == 0) {
+        rtapi_print_msg(RTAPI_MSG_ERR,
+            "HAL: ERROR: hal_get_realtime_type called before init\n");
+        return -EINVAL;
+    }
+    return hal_data->realtime_type;
+}
+
 /***********************************************************************
 *                      "LOCKING" FUNCTIONS                             *
 ************************************************************************/
@@ -3111,13 +3121,18 @@ int rtapi_app_main(void)
     /* done */
     rtapi_print_msg(RTAPI_MSG_DBG,
 	"HAL_LIB: kernel lib installed successfully\n");
+
+    hal_data->realtime_type = rtapi_get_realtime_type();
+
     return 0;
 }
 
 void rtapi_app_exit(void)
 {
     hal_thread_t *thread;
 
+    hal_data->realtime_type = REALTIME_TYPE_UNINITIALIZED;
+
     rtapi_print_msg(RTAPI_MSG_DBG, "HAL_LIB: removing kernel lib\n");
     hal_proc_clean();
     /* grab mutex before manipulating list */
@@ -3275,6 +3290,7 @@ static int init_hal_data(void)
     list_init_entry(&(hal_data->funct_entry_free));
     hal_data->thread_free_ptr = 0;
     hal_data->exact_base_period = 0;
+    hal_data->realtime_type = REALTIME_TYPE_UNINITIALIZED;
     /* set up for shmalloc_xx() */
     hal_data->shmem_bot = sizeof(hal_data_t);
     hal_data->shmem_top = HAL_SIZE;

src/hal/hal_priv.h

@@ -118,7 +118,7 @@
 */
 
 #define HAL_KEY   0x48414C32	/* key used to open HAL shared memory */
-#define HAL_VER   0x00000010	/* version code */
+#define HAL_VER   0x00000011	/* version code */
 #define HAL_SIZE  (256*4096)
 #define HAL_PSEUDO_COMP_PREFIX "__" /* prefix to identify a pseudo component */
 
@@ -275,6 +275,7 @@ typedef struct hal_data_t {
     SHMFIELD(hal_thread_t) thread_free_ptr;	/* list of free thread structs */
     int exact_base_period;      /* if set, pretend that rtapi satisfied our
 				   period request exactly */
+    rtapi_realtime_type_t realtime_type;	/* reflects the running realtime type */
     unsigned char lock;         /* hal locking, can be one of the HAL_LOCK_* types */
 } hal_data_t;
 

src/hal/halmodule.cc

@@ -1830,6 +1830,12 @@ PyObject *get_info_params(PyObject * /*self*/, PyObject * /*args*/) {
     return python_list;
 }
 
+static PyObject *pyhal_get_realtime_type(PyObject * /*self*/, PyObject * /*o*/) {
+    TEST_HAL_SHMEM_BASE(__FUNCTION__);
+    int res = hal_get_realtime_type();
+    return PyLong_FromLong(res);
+}
+
 static PyObject *pyhal_is_initialized(PyObject * /*self*/, PyObject * /*o*/) {
     return PyBool_FromLong(hal_shmem_base != NULL);
 }
@@ -2304,6 +2310,8 @@ static PyMethodDef module_methods[] = {
 	".get_info_signals(): Get a list of dicts for all the signals; {NAME:, VALUE:}"},
     {"get_info_params", get_info_params, METH_VARARGS,
 	".get_info_params(): Get a list of dicts for all the parameters; {NAME:, VALUE:}"},
+    {"get_realtime_type", pyhal_get_realtime_type, METH_NOARGS,
+        ".get_realtime_type(): Return the type of the running realtime"},
     {"is_initialized", pyhal_is_initialized, METH_NOARGS,
         ".is_initialized(): Return true if hal is initialized, false otherwhise"},
     {},
@@ -2385,6 +2393,14 @@ PyMODINIT_FUNC PyInit__hal(void)
     PyModule_AddIntConstant(m, "HAL_OUT", HAL_OUT);
     PyModule_AddIntConstant(m, "HAL_IO", HAL_IO);
 
+    PyModule_AddIntConstant(m, "REALTIME_TYPE_UNINITIALIZED", REALTIME_TYPE_UNINITIALIZED);
+    PyModule_AddIntConstant(m, "REALTIME_TYPE_NONE", REALTIME_TYPE_NONE);
+    PyModule_AddIntConstant(m, "REALTIME_TYPE_RTAI", REALTIME_TYPE_RTAI);
+    PyModule_AddIntConstant(m, "REALTIME_TYPE_PREEMPT_DYNAMIC", REALTIME_TYPE_PREEMPT_DYNAMIC);
+    PyModule_AddIntConstant(m, "REALTIME_TYPE_PREEMPT_RT", REALTIME_TYPE_PREEMPT_RT);
+    PyModule_AddIntConstant(m, "REALTIME_TYPE_LXRT", REALTIME_TYPE_LXRT);
+    PyModule_AddIntConstant(m, "REALTIME_TYPE_XENOMAI", REALTIME_TYPE_XENOMAI);
+    PyModule_AddIntConstant(m, "REALTIME_TYPE_XENOMAI_EVL", REALTIME_TYPE_XENOMAI_EVL);
 
     //Call realtime verify to gather realtime status
     //Most probably we don't have realtime running yet

src/rtapi/rtai_rtapi.c

@@ -83,6 +83,7 @@
 #include <rtai_shm.h>
 #include <rtai_fifos.h>
 
+#define RTAPI_HAL_PRIV  /* Use rtapi/hal private functions */
 #include "rtapi.h"		/* public RTAPI decls */
 #include <rtapi_mutex.h>
 #include "rtapi_common.h"	/* shared realtime/nonrealtime stuff */

src/rtapi/rtapi.h

@@ -986,6 +986,8 @@ int rtapi_spawnp_as_root(pid_t *pid, const char *path,
 
 extern int rtapi_is_kernelspace(void);
 
+//If changing anything here:
+//Update also halmodule.cc PyInit__hal()
 //You can use type > REALTIME_TYPE_NONE to check if you have realtime at all
 typedef enum{
     REALTIME_TYPE_UNINITIALIZED = -1, //Realtime not running, type unknown
@@ -998,8 +1000,10 @@ typedef enum{
     REALTIME_TYPE_XENOMAI_EVL = 6,
 } rtapi_realtime_type_t;
 
+#if defined(RTAPI) && defined(RTAPI_HAL_PRIV)
+//Only available in real time context, private use between hal and rtapi
+//Always use hal_get_realtime_type()
 extern int rtapi_is_realtime(void);
-#ifdef RTAPI
 extern rtapi_realtime_type_t rtapi_get_realtime_type(void);
 #endif
 

src/rtapi/uspace_rtapi_main.cc

@@ -55,6 +55,7 @@
 #include <fmt/format.h>
 #include <boost/lockfree/queue.hpp>
 
+#define RTAPI_HAL_PRIV //Use rtapi/hal private functions
 #include "rtapi.h"
 #include <hal.h>
 #include "hal/hal_priv.h"
@@ -862,6 +863,7 @@ static int master(int fd, const std::vector<std::string> &args) {
     //Process commands as long as master should not exit
     while(master_process_socket_command(fd));
 out:
+    do_unload_cmd("hal_lib");
     pthread_cancel(queue_thread);
     pthread_join(queue_thread, nullptr);
     rtapi_msg_queue.consume_all([](const message_t &m) {