Merge pull request #4132 from hdiethelm/halcmd_getrt

Proper and safe evaluation of realtime capability

Author: grandixximo

docs/po4a.cfg

@@ -51,6 +51,7 @@
 [type: AsciiDoc_def] src/config/moveoff.adoc $lang:build/adoc/$lang/config/moveoff.adoc
 [type: AsciiDoc_def] src/config/pncconf.adoc $lang:build/adoc/$lang/config/pncconf.adoc
 [type: AsciiDoc_def] src/config/python-hal-interface.adoc $lang:build/adoc/$lang/config/python-hal-interface.adoc
+[type: AsciiDoc_def] src/config/python-lcnc_realtime.adoc $lang:build/adoc/$lang/config/python-lcnc_realtime.adoc
 [type: AsciiDoc_def] src/config/python-interface.adoc $lang:build/adoc/$lang/config/python-interface.adoc
 [type: AsciiDoc_def] src/config/stepconf.adoc $lang:build/adoc/$lang/config/stepconf.adoc
 [type: AsciiDoc_def] src/config/stepper.adoc $lang:build/adoc/$lang/config/stepper.adoc

docs/src/Master_Documentation.adoc

@@ -300,6 +300,8 @@ include::config/python-interface.adoc[]
 
 include::config/python-hal-interface.adoc[]
 
+include::config/python-lcnc_realtime.adoc[]
+
 include::gui/gstat.adoc[]
 
 include::gui/vismach.adoc[]

docs/src/Submakefile

@@ -141,6 +141,7 @@ DOC_SRCS_EN := \
 	config/moveoff.adoc \
 	config/pncconf.adoc \
 	config/python-hal-interface.adoc \
+	config/python-lcnc_realtime.adoc \
 	config/python-interface.adoc \
 	config/stepconf.adoc \
 	config/stepper-diagnostics.adoc \

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

@@ -48,23 +48,63 @@ 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_UNKNOWN` - Only used when LINUXCNC_FORCE_REALTIME=1 is set. Unknown, no PREEMPT_DYNAMIC but SCHED_FIFO is available. Not recommended.
+* `hal.REALTIME_TYPE_PREEMPT_DYNAMIC` - Preempt dynamic: available in vanilla kernel. Only used when LINUXCNC_FORCE_REALTIME=1 is set. Not recommended.
+* `hal.REALTIME_TYPE_PREEMPT_RT` - Preempt RT
+* `hal.REALTIME_TYPE_RTAI` - RTAI kernel mode
+* `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)
 * `hal.is_userspace` - Inverted `hal.is_kernelspace`
 * `hal.kernel_version` - A string specifying the real-time kernel version if `hal.is_kernelspace` is one.
   Otherwise it specifies `"Not Available"`.
-* `hal.is_rt` - One (1) if the system runs in real-time, otherwise zero (0)
-* `hal.is_sim` - Inverted `hal.is_rt`
+* `hal.is_rt` - One (1) if the system runs in real-time, otherwise zero (0) *DEPRECATED*: Use `lcnc_realtime.verify()`
+* `hal.is_sim` - Inverted `hal.is_rt` *DEPRECATED*: Use `lcnc_realtime.verify()`
 
 === 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 throw
+a `RuntimeError` exception: `Cannot call before creating component`
+
+.Example:
+[source,python]
+----
+#The hal must be initialized to use many of the hal functions
+#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]. +
+Throws a `RuntimeError` exception if HAL is not initialized.
+
 hal.component_exists(_name_:string)::
-Returns a boolean to indicate whether or not the specified component exist at this time.
+Returns a boolean to indicate whether or not the specified component exist at this time. +
+Throws a `RuntimeError` exception if HAL is not initialized.
 
 hal.component_is_ready(_name_:string)::
 Returns a boolean to indicate whether or not the specified component is in the ready state.
-Also returns False if the component does not exist.
+Also returns False if the component does not exist. +
+Throws a `RuntimeError` exception if HAL is not initialized.
 
 .Example:
 [source,python]
@@ -86,7 +126,8 @@ See 'hal.set_msg_level()' and xref:_hal_constants[message constants] for list of
 hal.new_sig(_name_:string, _type_:enum)::
 Create a new signal (net) called _name_.
 The signal can carry information of _type_ content.
-Returns `True` on success.
+Returns `True` on success. +
+Throws a `RuntimeError` exception if HAL is not initialized.
 
 .Example:
 [source,python]
@@ -98,7 +139,8 @@ if not hal.new_sig("signalname", hal.HAL_BIT):
 hal.connect(_pinname_:string, _signame_:string)::
 Connect the pin _pinname_ to signal _signame_.
 Both signal and pin must exist and both pin and signal must be of the same type.
-Returns `True` on success.
+Returns `True` on success. +
+Throws a `RuntimeError` exception if HAL is not initialized.
 
 .Example:
 [source,python]
@@ -110,7 +152,8 @@ if not hal.connect("mycomp.pinname", "signalname"):
 hal.disconnect(_pinname_:string, _signame_:string)::
 Disconnect the pin _pinname_ from signal _signame_.
 Both signal and pin must exist.
-Returns `True` on success.
+Returns `True` on success. +
+Throws a `RuntimeError` exception if HAL is not initialized.
 
 .Example:
 [source,python]
@@ -121,7 +164,8 @@ if not hal.disconnect("mycomp.pinname"):
 
 hal.pin_has_writer(_pinname_:string)::
 Returns `True` if pin with name _pinname_ is attached to a signal and there is at least one writer.
-Otherwise, `False` is returned.
+Otherwise, `False` is returned. +
+Throws a `RuntimeError` exception if HAL is not initialized.
 
 .Example:
 [source,python]
@@ -135,8 +179,9 @@ else:
 hal.set_p(_name_:string, _value_:mixed)::
 Sets the pin or param called _name_ to _value_.
 The _name_ is the full name of the pin or param.
-The search order is pin names first, then parameter names.
+The search order is pin names first, then parameter names. +
 Throws a `RuntimeError` exception if the _name_ is not found. +
+Throws a `RuntimeError` exception if HAL is not initialized. +
 The type of _value_ depends on the type of the pin or param.
 Integer scalar types may use integers or a textual representation of an integer to set the value.
 Floating point type may use both integer, floating point and textual representation thereof to set the value.
@@ -158,14 +203,16 @@ The same rules for _value_ apply to 'set_s()' as to 'set_p()'. +
  +
 The 'set_s()' method has one special case when the signal is of type `hal.HAL_PORT` and it is fully connected.
 In that case, the call uses the _value_ to set the port's queue size and it must be a positive integer.
-See below xref:_hal_port_pipes[on configuring a port].
+See below xref:_hal_port_pipes[on configuring a port]. +
+Throws a `RuntimeError` exception if HAL is not initialized.
 
 hal.get_value(_name_:string)::
 Returns the value of the pin, param or signal with _name_, searched in that order.
 Boolean types return `True` or `False`.
 Integer scalar types return an integer.
 Floating point types return a float.
-A `RuntimeError` exception is thrown if no pin, param or signal is found by that name.
+A `RuntimeError` exception is thrown if no pin, param or signal is found by that name. +
+Throws a `RuntimeError` exception if HAL is not initialized.
 
 .Example:
 [source,python]
@@ -174,13 +221,16 @@ value = hal.get_value("iocontrol.0.emc-enable-in")
 ----
 
 hal.get_info_pins()::
-Returns a list of dictionary tuples as in `{"NAME":"pinname", "VALUE":<bool|int|float>, "TYPE":<int>, "DIRECTION":<int>}`.
+Returns a list of dictionary tuples as in `{"NAME":"pinname", "VALUE":<bool|int|float>, "TYPE":<int>, "DIRECTION":<int>}`. +
+Throws a `RuntimeError` exception if HAL is not initialized.
 
 hal.get_info_params()::
-Returns a list of dictionary tuples as in `{"NAME":"paramname", "VALUE":<bool|int|float>, "TYPE":<int>, "DIRECTION":<int>}`.
+Returns a list of dictionary tuples as in `{"NAME":"paramname", "VALUE":<bool|int|float>, "TYPE":<int>, "DIRECTION":<int>}`. +
+Throws a `RuntimeError` exception if HAL is not initialized.
 
 hal.get_info_signals()::
-Returns a list of dictionary tuples as in `{"NAME":"signame", "VALUE":<bool|int|float>, "TYPE":<int>, "DRIVER":"name"|None}`.
+Returns a list of dictionary tuples as in `{"NAME":"signame", "VALUE":<bool|int|float>, "TYPE":<int>, "DRIVER":"name"|None}`. +
+Throws a `RuntimeError` exception if HAL is not initialized.
 
 .Example:
 [source,python]

docs/src/config/python-lcnc_realtime.adoc

@@ -0,0 +1,29 @@
+:lang: en
+:toc:
+
+[[cha:python-lcnc_realtime]]
+= Python module for managing the realtime backend
+
+This documentation describes the `lcnc_realtime` Python module, which provides
+a Python API for managing the realtime backend.
+
+This is a Python wrapper of the realtime script.
+
+== Basic usage
+
+.Verify realtime capability and check if the realtime backend is running
+[source,python]
+----
+import lcnc_realtime
+
+print("lcnc_realtime.verify " + str(lcnc_realtime.verify()))
+print("lcnc_realtime.status " + str(lcnc_realtime.status()))
+----
+
+== methods
+
+hal.verify()::
+Returns a boolean to indicate whether the system is realtime capable.
+
+hal.status()::
+Returns a boolean to indicate whether the realtime backend is running.

docs/src/hal/halmodule.adoc

@@ -199,9 +199,9 @@ Use these to specify details rather then the value they hold.
 
 Read these to acquire information about the realtime system.
 
+* `lcnc_realtime`: See <<cha:python-lcnc_realtime, Python module for managing the realtime backend>>.
 * `is_kernelspace`
-* `is_rt`
-* `is_sim`
 * `is_userspace`
+* `get_realtime_type()`
 
 // vim: set syntax=asciidoc:

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 or a HAL status code on failure.
+
+For uspace, this returns *REALTIME_TYPE_UNINITIALIZED* if *rtapi_app* is not running. It is safe to assume
+this never happens in realtime components. But userspace components can be loaded without *rtapi_app* being
+started.
+
+For rtai, this always returns *REALTIME_TYPE_RTAI*.

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

@@ -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.
+
+Always use *hal_get_realtime_type()* instead. *rtapi_is_realtime()* is only available 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

lib/python/.gitignore

@@ -1,4 +1,5 @@
 nf.py
+lcnc_realtime.py
 gscreen
 gmoccapy/
 stepconf/

lib/python/hal.py

@@ -29,6 +29,19 @@
 
 import _hal
 from _hal import *
+import warnings
+import lcnc_realtime
+
+def __getattr__(name):
+    if name == 'is_rt':
+        warnings.warn(f"{name} is deprecated, use lcnc_realtime.verify() instead", FutureWarning, stacklevel=2)
+        return lcnc_realtime.verify()
+
+    if name == 'is_sim':
+        warnings.warn(f"{name} is deprecated, use lcnc_realtime.verify() instead", FutureWarning, stacklevel=2)
+        return not lcnc_realtime.verify()
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 class _ItemWrap(object):
     def __new__(cls, item):