core: added PORT_ and CONFIG_ATTR_CLONED

Signed-off-by: Markus Klotzbuecher <mk@mkio.de>

ChangeLog.md

@@ -20,14 +20,21 @@ This file tracks user visible API changes
 - `ubx_config_add2` adds a config incl `min`/`max` constraints and
   attrs.
 
-- `ubx_port_add`: the past parameter `state` has been dropped (as has
-  the member in `ubx_port_t`.
+- The attributes `CONFIG_ATTR_CLONED` and `PORT_ATTR_CLONED` are set
+  for ports/configs that were created as a consequence of creating a
+  block by cloning. Put differently, these attributes are unset for
+  configs and ports that were added dynamically.
+
+- `ubx_port_add` `ubx_inport_add`, `ubx_outport_add`: the parameter
+  `state` has been dropped (as has the member in `ubx_port_t`. Instead
+  `attrs` has been added as parameter #4. Check `ubx_proto.h` for the
+  new prototypes.
 
 - `ubx_types.h`: converted object names (node, block, port, config)
   from dynamically allocated strings to fixed strings where
   possible.
 
-- `ubx_types.h`, ports:
+- `ubx_types.h`:
    - removed port `state`, which was never used. The functions
 	 `ubx_port_add` (lua `ubx.port_add`) consequently drop the last
 	 parameter.

README.md

@@ -11,7 +11,7 @@ framework for use-cases such as *embedded control* or *signal
 processing*. It provides generic and configurable code for typical
 challenges such as *lock-free communication* between different
 criticality domains, real-time safe logging or triggers with
-configurable POSIX attributes.
+configurable POSIX realtime properties.
 
 Main features:
 

docs/dev/002-stable-port-ptrs.md

@@ -16,7 +16,7 @@ lists instead. This simplifies the code and guarantees stable
 pointers. Iterating over all ports becomes as simple as:
 
 ```C
-ubx_port_t *p;
+ubx_port_t *p = NULL;
 
 DL_FOREACH(b->ports, p) {
 	write_int(p, 42);

libubx/ubx.c

@@ -493,6 +493,7 @@ int ubx_block_register(ubx_node_info_t *ni, struct ubx_proto_block *prot)
 			ret = ubx_port_add(newb,
 					   p->name,
 					   p->doc,
+					   p->attrs & PORT_ATTR_CLONED,
 					   p->in_type_name,
 					   p->in_data_len,
 					   p->out_type_name,
@@ -510,7 +511,7 @@ int ubx_block_register(ubx_node_info_t *ni, struct ubx_proto_block *prot)
 					      c->type_name,
 					      c->min,
 					      c->max,
-					      c->attrs);
+					      c->attrs & CONFIG_ATTR_CLONED);
 			if (ret)
 				goto out_err;
 		}
@@ -966,6 +967,7 @@ void ubx_block_free(ubx_block_t *b)
 static int __ubx_port_add(ubx_block_t *b,
 			  const char *name,
 			  const char *doc,
+			  const uint32_t attrs,
 			  const ubx_type_t *in_type,
 			  const long in_data_len,
 			  const ubx_type_t *out_type,
@@ -1031,7 +1033,7 @@ static ubx_block_t *ubx_block_clone(ubx_block_t *prot, const char *name)
 				       csrc->type,
 				       csrc->min,
 				       csrc->max,
-				       csrc->attrs);
+				       csrc->attrs & CONFIG_ATTR_CLONED);
 		if (ret != 0)
 			goto out_free;
 	}
@@ -1040,6 +1042,7 @@ static ubx_block_t *ubx_block_clone(ubx_block_t *prot, const char *name)
 		ret = __ubx_port_add(newb,
 				     psrc->name,
 				     NULL,
+				     psrc->attrs & PORT_ATTR_CLONED,
 				     psrc->in_type,
 				     psrc->in_data_len,
 				     psrc->out_type,
@@ -1763,6 +1766,7 @@ static int check_minmax(const ubx_block_t *b, const int checklate)
 static int __ubx_port_add(ubx_block_t *b,
 			  const char *name,
 			  const char *doc,
+			  const uint32_t attrs,
 			  const ubx_type_t *in_type,
 			  const long in_data_len,
 			  const ubx_type_t *out_type,
@@ -1802,6 +1806,7 @@ static int __ubx_port_add(ubx_block_t *b,
 		}
 	}
 
+	pnew->attrs = attrs;
 	pnew->in_type = in_type;
 	pnew->out_type = out_type;
 	pnew->in_data_len = (in_data_len == 0) ? 1 : in_data_len;
@@ -1835,6 +1840,7 @@ static int __ubx_port_add(ubx_block_t *b,
 int ubx_port_add(ubx_block_t *b,
 		 const char *name,
 		 const char *doc,
+		 const uint32_t attrs,
 		 const char *in_type_name,
 		 const long in_data_len,
 		 const char *out_type_name,
@@ -1860,7 +1866,7 @@ int ubx_port_add(ubx_block_t *b,
 			return EINVALID_TYPE;
 		}
 	}
-	return __ubx_port_add(b, name, doc, in_type, in_data_len, out_type, out_data_len);
+	return __ubx_port_add(b, name, doc, attrs, in_type, in_data_len, out_type, out_data_len);
 }
 
 /**
@@ -1872,10 +1878,11 @@ int ubx_port_add(ubx_block_t *b,
  * @param out_data_len
  * @return < 0 in case of error, 0 otherwise
  */
-int ubx_outport_add(ubx_block_t *b, const char *name, const char *doc,
+int ubx_outport_add(ubx_block_t *b, const char *name, const char *doc, uint32_t attrs,
 		    const char *out_type_name, long out_data_len)
 {
-	return ubx_port_add(b, name, doc, NULL, 0, out_type_name, out_data_len);
+	return ubx_port_add(b, name, doc, attrs,
+			    NULL, 0, out_type_name, out_data_len);
 }
 
 /**
@@ -1925,10 +1932,10 @@ int ubx_outport_resize(struct ubx_port *p, long len)
  * @param in_data_len
  * @return < 0 in case of error, 0 otherwise
  */
-int ubx_inport_add(ubx_block_t *b, const char *name, const char *doc,
+int ubx_inport_add(ubx_block_t *b, const char *name, const char *doc, uint32_t attrs,
 		   const char *in_type_name, long in_data_len)
 {
-	return ubx_port_add(b, name, doc, in_type_name, in_data_len, NULL, 0);
+	return ubx_port_add(b, name, doc, attrs, in_type_name, in_data_len, NULL, 0);
 }
 
 /**

libubx/ubx_types.h

@@ -15,7 +15,9 @@
 #ifndef UBX_TYPES_H
 #define UBX_TYPES_H
 
-/* constants */
+/**
+ * constants
+ */
 enum {
 	UBX_NODE_NAME_MAXLEN	= 31,
 	UBX_BLOCK_NAME_MAXLEN	= 63,
@@ -28,7 +30,9 @@ enum {
 	UBX_TYPE_HASHSTR_LEN	= UBX_TYPE_HASH_LEN * 2,	/* hexstring md5 */
 };
 
-/* return error codes */
+/**
+ * error codes
+ */
 enum {
 	EINVALID_BLOCK 		= -32767, /* invalid block */
 	EINVALID_PORT,			  /* invalid port */
@@ -54,6 +58,9 @@ enum {
 
 };
 
+/**
+ * loglevels
+ */
 enum {
 	UBX_LOGLEVEL_EMERG	= 0,	/* system unusable */
 	UBX_LOGLEVEL_ALERT	= 1,	/* immediate action required */
@@ -71,18 +78,33 @@ struct ubx_block;
 struct ubx_node_info;
 struct ubx_log_msg;
 
-/*
- * module and node
+/**
+ * __ubx_initialize_module - module initialization hook
+ *
+ * @ni: node handle for the module to register blocks and types
+ * @return: 0 if OK, -1 otherwise
  */
 int __ubx_initialize_module(struct ubx_node_info *ni);
+
+/**
+ * __ubx_cleanup_module - module cleanuphook
+ *
+ * @ni: node handle for the module to unregister blocks and types
+ */
 void __ubx_cleanup_module(struct ubx_node_info *ni);
 
 
-/* type and value (data) */
+/**
+ * type classes
+ *
+ * @TYPE_CLASS_BASIC: primivitve C type
+ * @TYPE_CLASS_STRUCT: C struct type
+ *
+ * currently only BASIC and STRUCT are used
+ */
 enum {
 	TYPE_CLASS_BASIC = 1,
 	TYPE_CLASS_STRUCT,	/* simple sequential memory struct */
-	TYPE_CLASS_CUSTOM	/* requires custom serialization */
 };
 
 /**
@@ -134,12 +156,19 @@ enum {
 /**
  * anonymous enum for port attributes
  *
- * @PORT_ATTR_DYN: the configuration was added to the interface
- * 		   dynamically using @ubx_config_add (opposed to being
- * 		   added during block creation).
+ * @PORT_ATTR_CLONED: set if this port was added during cloning from a
+ * 		      prototype, i.e. it was not added dynamically
+ * 		      later. This can be useful for identifying and
+ * 		      removing custom ports in cleanup without
+ * 		      touching the "static" ones created from the
+ * 		      prototype.
+ *
+ * the first 8 bits are reserved, the others can be used freely.
  */
 enum {
-	PORT_ATTR_DYN 		= 1<<0
+	PORT_ATTR_CLONED 		= 1<<0,
+	/* ... */
+	PORT_ATTR_RESERVED7 		= 1<<7,
 };
 
 /**
@@ -213,21 +242,29 @@ typedef struct ubx_config {
 /**
  * anonymous enum for config attributes
  *
- * @CONFIG_ATTR_CHECKLATE: perform checking of min, max before start
- *			   instead of before init hook
- * @CONFIG_ATTR_DYN: 	   the configuration was added to the interface
- * 		           dynamically using @ubx_config_add.
+ * @CONFIG_ATTR_CLONED: set if this config was added during cloning
+ * 			from a prototype, i.e. it was not added
+ * 			dynamically later. This can be useful for
+ * 			identifying and removing custom configs in
+ * 			cleanup without touching the "static" ones
+ * 			created from the prototype.
+ *
+ * @CONFIG_ATTR_CHECKLATE: perform checking of min and max before
+ *			   start instead of before init hook
+ *
+ * The first 8 bit are reserved, the others can be used freely.
  */
 enum {
-	CONFIG_ATTR_CHECKLATE = 1<<0,
-	CONFIG_ATTR_DYN =	1<<1
+	CONFIG_ATTR_CLONED = 	1<<0,
+	CONFIG_ATTR_CHECKLATE = 1<<1,
+	/* ... */
+	CONFIG_ATTR_RESERVED =	1<<7,
 };
 
-/*
- * ubx block
- */
 
-/* Block types */
+/**
+ * Block types
+ */
 enum {
 	BLOCK_TYPE_COMPUTATION = 1,
 	BLOCK_TYPE_INTERACTION
@@ -245,7 +282,9 @@ enum {
 	BLOCK_ATTR_ACTIVE =	1<<1,
 };
 
-/* block states */
+/**
+ * block lifecycle states
+ */
 enum {
 	BLOCK_STATE_PREINIT,
 	BLOCK_STATE_INACTIVE,

lua/ubx.lua

@@ -106,7 +106,6 @@ local function setup_enums()
    M.type_class_tostr={
       [ffi.C.TYPE_CLASS_BASIC]='basic',
       [ffi.C.TYPE_CLASS_STRUCT]='struct',
-      [ffi.C.TYPE_CLASS_CUSTOM]='custom'
    }
 
    M.block_state_tostr={

std_blocks/const/const.c

@@ -85,7 +85,7 @@ static int const_init(ubx_block_t *b)
 
 #ifndef BUILD_IBLOCK
 	/* add port 'out' */
-	ret = ubx_outport_add(b, OUT, "const value output port",
+	ret = ubx_outport_add(b, OUT, "const value output port", 0,
 			      type_name, inf->data_len);
 
 	if (ret != 0)

tests/test_blockdiagram.lua

@@ -16,7 +16,7 @@ local ubx=require "ubx"
 local ffi=require("ffi")
 
 function init(block)
-   assert(ubx.port_add(block, "in", "test in-port", "uint32_t", 1, nil, 0))
+   assert(ubx.port_add(block, "in", "test in-port", 0, "uint32_t", 1, nil, 0))
    return true
 end
 

tests/test_dyn_block_if.lua

@@ -77,6 +77,7 @@ function test_port_add_rm()
 					    "testport"..tostring(k),
 					    -- "{ desc='a testport without further meaning "..tostring(k).."' }",
 					    "",
+                                            0,
 					    "int32_t", 5, "size_t", 1)
 			    end
 		      ]]))

tests/test_ptrig.lua

@@ -16,8 +16,8 @@ local ubx=require "ubx"
 local p_ramp_cnt, p_test_result
 
 function init(b)
-   ubx.inport_add(b, "ramp_cnt", "ramp counter in", "uint64_t", 1)
-   ubx.outport_add(b, "test_result", "test results", "int", 1)
+   ubx.inport_add(b, "ramp_cnt", "ramp counter in", 0, "uint64_t", 1)
+   ubx.outport_add(b, "test_result", "test results", 0, "int", 1)
    p_ramp_cnt = ubx.port_get(b, "ramp_cnt")
    p_test_result = ubx.port_get(b, "test_result")
    return true

tests/test_struct_comm.lua

@@ -32,13 +32,11 @@ function init(b)
    ubx.ffi_load_types(b.ni)
 
    -- print("adding port 'pos_in' to block ", ubx.safe_tostr(b.name))
-   ubx.port_add(b, "pos_in",
-		  "{ desc='current measured position' }",
-		  "struct kdl_vector", 1, nil, 0)
+   ubx.port_add(b, "pos_in", "{ desc='current measured position' }",
+                0, "struct kdl_vector", 1, nil, 0)
 
-   ubx.port_add(b, "pos_out",
-		  "{ desc='desired position' }",
-		  nil, 0, "struct kdl_vector", 1)
+   ubx.port_add(b, "pos_out", "{ desc='desired position' }",
+                0, nil, 0, "struct kdl_vector", 1)
 
    rd = ubx.data_alloc(b.ni, "struct kdl_vector")
    return true