Cleanup and doc

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)
@@ -59,6 +70,31 @@ System information:
 
 === hal methods
 
+hal.is_initialized()::
+Returns a boolean to indicate whether hal is initialized. The hal is initialized when there is
+at least one component. If this is not the case, many of the following functions will
+fail with the error: `Cannot call before creating component`
+
+.Example:
+[source,python]
+----
+#The hal must be initialized to use get_realtime_type()
+#If it is not initialized, create a component which will initialize it
+#The component will be cleaned up after comp goes out of scope
+#Use pid as component identifier, so it is unlikely to collide
+#with existing components
+comp_name = f"halpy{os.getpid()}"
+if not hal.is_initialized():
+    comp = hal.component(comp_name);
+
+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
+
+rtapi_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_lib.c

@@ -539,9 +539,9 @@ char *hal_comp_name(int comp_id)
 
 int 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;
+        rtapi_print_msg(RTAPI_MSG_ERR,
+            "HAL: ERROR: hal_get_realtime_type called before init\n");
+        return -EINVAL;
     }
     return hal_data->realtime_type;
 }

src/hal/hal_priv.h

@@ -275,7 +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 realtime type */
+    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/rtapi/rtapi.h

@@ -1001,7 +1001,7 @@ typedef enum{
 
 #ifdef RTAPI
 //Only available in real time context
-//In userspace context, use hal_realtime_type()
+//In userspace context, use hal_get_realtime_type()
 extern int rtapi_is_realtime(void);
 extern rtapi_realtime_type_t rtapi_get_realtime_type(void);
 #endif

src/rtapi/uspace_common.h

@@ -342,6 +342,7 @@ int rtapi_is_kernelspace() { return 0; }
 
 #ifndef RTAPI
 //For RTAPI, this function is implemented in uspace_rtapi_main.cc
+//Keep it in for now with a warning to avoid link issues
 int rtapi_is_realtime() {
     rtapi_print_msg(RTAPI_MSG_ERR, "rtapi_is_realtime() only allowed in real time context");
     return 0;