Draft - HAL types update and HAL isolation

src/hal/hal.h

@@ -58,6 +58,10 @@
     information, go to www.linuxcnc.org.
 */
 
+#if defined(HAL_PRIV_H) || defined(__HAL_LIBRARY_INTERNAL_ONLY)
+#error "Including hal.h after hal_priv.h"
+#endif
+
 /***********************************************************************
 *                   GENERAL NOTES AND DOCUMENTATION                    *
 ************************************************************************/
@@ -123,6 +127,24 @@
 
 */
 
+//
+// The HAL_API_VERSION define can be used to determine what features are
+// available in the HAL library API. It can be used to make code build on both
+// old and new LinuxCNC versions if you need to keep everything in one
+// source-tree.
+// Currently only two versions are possible:
+//  a) No define present
+//     The HAL API is for LinuxCNC up to and including version 2.9. The integer
+//     pins and params are 32-bit only.
+//
+//  b) HAL_API_VERSION == 1
+//     The HAL API if for LinuxCNC 2.10 and later. It supports the getter,
+//     setter and query API. Any access to the underlying data or HAL's private
+//     inners is not allowed. HAL pins and params are opaque structures. The
+//     underlying data size of integers is 64-bit.
+//
+#define HAL_API_VERSION 1
+
 #include "rtapi.h"
 RTAPI_BEGIN_DECLS
 
@@ -278,7 +300,7 @@ const char *hal_strerror(int err);
 /** hal_comp_name() returns the name of the given component, or NULL
     if comp_id is not a loaded component
 */
-extern char* hal_comp_name(int comp_id);
+extern const char *hal_comp_name(int comp_id);
 
 /** hal_get_realtime_type() returns the type of the running real time
 */
@@ -396,15 +418,15 @@ static inline __HAL_ALWAYS_INLINE bool hal_pdir_is_neither(hal_pdir_t v) {
 // compiler.
 // ==> Remove when we get rid of old hal_*_t typedefs. <==
 typedef rtapi_real real_t;
-typedef rtapi_u64 ireal_t __attribute__((aligned(8))); // integral type as wide as real_t / hal_float_t
+typedef rtapi_u64 ireal_t __attribute__((aligned(8))) __attribute__((deprecated)); // integral type as wide as real_t / hal_float_t
 
 typedef volatile bool hal_bit_t;
 typedef volatile rtapi_u32 hal_u32_t;
 typedef volatile rtapi_s32 hal_s32_t;
 typedef volatile rtapi_u64 hal_u64_t;
 typedef volatile rtapi_s64 hal_s64_t;
-typedef volatile real_t hal_float_t;
-typedef volatile int hal_port_t;
+typedef volatile rtapi_real hal_float_t;
+typedef volatile rtapi_port hal_port_t;
 
 /** HAL "data union" structure
  ** This structure may hold any type of hal data
@@ -889,12 +911,12 @@ extern int hal_param_new(const char *name, hal_type_t type, hal_param_dir_t dir,
     On success, the hal_param_xxx_set() functions return 0,
     and on failure they return a negative error code.
 */
-extern int hal_param_bit_set(const char *name, int value);
-extern int hal_param_float_set(const char *name, double value);
-extern int hal_param_u32_set(const char *name, unsigned long value);
-extern int hal_param_s32_set(const char *name, signed long value);
-extern int hal_param_u64_set(const char *name, unsigned long value);
-extern int hal_param_s64_set(const char *name, signed long value);
+int hal_param_bit_set(const char *name, int value) __attribute__((deprecated("Use hal_set_p()")));
+int hal_param_float_set(const char *name, double value) __attribute__((deprecated("Use hal_set_p()")));
+int hal_param_u32_set(const char *name, unsigned long value) __attribute__((deprecated("Use hal_set_p()")));
+int hal_param_s32_set(const char *name, signed long value) __attribute__((deprecated("Use hal_set_p()")));
+int hal_param_u64_set(const char *name, unsigned long value) __attribute__((deprecated("Use hal_set_p()")));
+int hal_param_s64_set(const char *name, signed long value) __attribute__((deprecated("Use hal_set_p()")));
 
 /** 'hal_param_alias()' assigns an alternate name, aka an alias, to
     a parameter.  Once assigned, the parameter can be referred to by
@@ -918,7 +940,7 @@ extern int hal_param_alias(const char *pin_name, const char *alias);
     If successful, hal_param_set() returns 0.  On failure
     it returns a negative error code.
 */
-extern int hal_param_set(const char *name, hal_type_t type, void *value_addr);
+int hal_param_set(const char *name, hal_type_t type, void *value_addr) __attribute__((deprecated("Use hal_set_p()")));
 
 /***********************************************************************
 *                 PIN/SIG/PARAM GETTER FUNCTIONS                       *
@@ -933,7 +955,7 @@ extern int hal_param_set(const char *name, hal_type_t type, void *value_addr);
  */
 
 extern int hal_get_pin_value_by_name(
-    const char *name, hal_type_t *type, hal_data_u **data, bool *connected);
+    const char *name, hal_type_t *type, hal_data_u **data, bool *connected) __attribute__((deprecated("Use hal_get_p()")));
 
 /** 'hal_get_signal_value_by_name()' returns the value of any arbitrary HAL
  * signal by signal name.
@@ -944,7 +966,7 @@ extern int hal_get_pin_value_by_name(
  */
 
 extern int hal_get_signal_value_by_name(
-    const char *name, hal_type_t *type, hal_data_u **data, bool *has_writers);
+    const char *name, hal_type_t *type, hal_data_u **data, bool *has_writers) __attribute__((deprecated("Use hal_get_s()")));
 
 /** 'hal_get_param_value_by_name()' returns the value of any arbitrary HAL
  * parameter by parameter name.
@@ -954,7 +976,7 @@ extern int hal_get_signal_value_by_name(
  */
 
 extern int hal_get_param_value_by_name(
-    const char *name, hal_type_t *type, hal_data_u **data);
+    const char *name, hal_type_t *type, hal_data_u **data) __attribute__((deprecated("Use hal_get_p()")));
 
 
 /***********************************************************************

src/hal/hal_lib.c

@@ -69,6 +69,7 @@
 
 #include <rtapi.h>		/* RTAPI realtime OS API */
 #include "hal.h"		/* HAL public API decls */
+#define __HAL_LIBRARY_INTERNAL_ONLY 1
 #include "hal_priv.h"		/* HAL private decls */
 
 #include <rtapi_string.h>
@@ -777,10 +778,10 @@ const char *hal_strerror(int err)
     }
 }
 
-char *hal_comp_name(int comp_id)
+const char *hal_comp_name(int comp_id)
 {
     hal_comp_t *comp;
-    char *result = NULL;
+    const char *result = NULL;
     halpr_mutex_acquire();
     comp = halpr_find_comp_by_id(comp_id);
     if(comp) result = comp->name;
@@ -2061,6 +2062,10 @@ int hal_param_new_fake(int compid, hal_refs_u *ref)
 
 /* wrapper functs for typed params - these call the generic funct below */
 
+// We don't want our library to emit the deprecation warning.
+// We already know it and need to provide them until removed.
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
 int hal_param_bit_set(const char *name, int value)
 {
     return hal_param_set(name, HAL_BIT, &value);
@@ -2090,6 +2095,7 @@ int hal_param_s64_set(const char *name, signed long value)
 {
     return hal_param_set(name, HAL_S64, &value);
 }
+#pragma GCC diagnostic pop
 
 /* this is a generic function that does the majority of the work */
 
@@ -5221,6 +5227,8 @@ EXPORT_SYMBOL(hal_param_new_uint);
 EXPORT_SYMBOL(hal_param_new_real);
 EXPORT_SYMBOL(hal_param_new_fake);
 
+// Parameter set functions have been deprecated.
+// Use the generic hal_set_p() instead.
 EXPORT_SYMBOL(hal_param_bit_set);
 EXPORT_SYMBOL(hal_param_float_set);
 EXPORT_SYMBOL(hal_param_u32_set);
@@ -5244,6 +5252,8 @@ EXPORT_SYMBOL(hal_del_funct_from_thread);
 EXPORT_SYMBOL(hal_start_threads);
 EXPORT_SYMBOL(hal_stop_threads);
 
+// All HAL lib internals' access has bee deprecated. All function prefixed with
+// halpr_ are only for private internal use.
 EXPORT_SYMBOL(hal_shmem_base);
 EXPORT_SYMBOL(halpr_find_comp_by_name);
 EXPORT_SYMBOL(halpr_find_pin_by_name);
@@ -5262,7 +5272,7 @@ EXPORT_SYMBOL(halpr_find_pin_by_sig);
 EXPORT_SYMBOL(hal_pin_alias);
 EXPORT_SYMBOL(hal_param_alias);
 
-EXPORT_SYMBOL(hal_port_alloc);
+EXPORT_SYMBOL(hal_port_alloc); // Deprecated
 EXPORT_SYMBOL(hal_port_read);
 EXPORT_SYMBOL(hal_port_peek);
 EXPORT_SYMBOL(hal_port_peek_commit);

src/hal/hal_lib_extra.c

@@ -16,6 +16,7 @@
 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
 #include "hal.h"
+#define __HAL_LIBRARY_INTERNAL_ONLY 1
 #include "hal_priv.h"
 
 //

src/hal/hal_lib_query.c

@@ -16,6 +16,7 @@
 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
 #include "hal.h"
+#define __HAL_LIBRARY_INTERNAL_ONLY 1
 #include "hal_priv.h"
 
 //=====================================================

src/hal/hal_priv.h

@@ -57,6 +57,10 @@
 
 */
 
+#if !defined(__HAL_LIBRARY_INTERNAL_ONLY)
+#warning "You should not be including HAL's private hal_priv.h. Please use the HAL query API."
+#endif
+
 /***********************************************************************
 *                       GENERAL INFORMATION                            *
 ************************************************************************/
@@ -527,7 +531,7 @@ extern hal_pin_t *halpr_find_pin_by_sig(hal_sig_t * sig, hal_pin_t * start);
     should use hal_set_s() to allocate the port once the pins are connected to
     the signal.
 */
-extern int hal_port_alloc(unsigned size, hal_port_t *port);
+int hal_port_alloc(unsigned size, hal_port_t *port) __attribute__((deprecated("Use hal_set_s()")));
 int halpr_port_alloc(unsigned size, hal_port_t *port);
 
 // Recursive HAL mutex (replaces old mutex)