Stabilize uavcan.node.port.List (#138)

Stabilize uavcan.node.port.List

Author: pavel-kirienko

uavcan/node/port/7510.List.0.1.dsdl

@@ -9,6 +9,8 @@
 # - At the OPTIONAL priority level at least every MAX_PUBLICATION_PERIOD seconds.
 # - At the OPTIONAL or SLOW priority level within MAX_PUBLICATION_PERIOD after the port configuration is changed.
 
+@deprecated  # Replaced with v1.
+
 uint8 MAX_PUBLICATION_PERIOD = 10  # [seconds]
 # If the port configuration is not updated in this amount of time, the node should publish this message anyway.
 

uavcan/node/port/7510.List.1.0.dsdl

@@ -0,0 +1,20 @@
+# A list of ports that this node is using:
+# - Subjects published by this node (whether periodically or ad-hoc).
+# - Subjects that this node is subscribed to (a datalogger or a debugger would typically subscribe to all subjects).
+# - RPC services consumed by this node (i.e., service clients).
+# - RPC services provided by this node (i.e., service servers).
+#
+# All nodes should implement this capability to provide network introspection and diagnostic capabilities.
+# This message should be published using the fixed subject-ID as follows:
+# - At the OPTIONAL priority level at least every MAX_PUBLICATION_PERIOD seconds.
+# - At the OPTIONAL or SLOW priority level within MAX_PUBLICATION_PERIOD after the port configuration is changed.
+
+uint8 MAX_PUBLICATION_PERIOD = 10  # [seconds]
+# If the port configuration is not updated in this amount of time, the node should publish this message anyway.
+
+SubjectIDList.1.0 publishers
+SubjectIDList.1.0 subscribers
+ServiceIDList.1.0 clients
+ServiceIDList.1.0 servers
+
+@sealed

uavcan/node/port/ServiceIDList.0.1.dsdl

@@ -2,6 +2,8 @@
 # This is a trivial constant-size bitmask with some reserved space in case the range of service-ID is increased
 # in a future revision of the protocol.
 
+@deprecated  # Replaced with v1.
+
 uint16 CAPACITY = ServiceID.1.0.MAX + 1
 
 bool[CAPACITY] mask

uavcan/node/port/ServiceIDList.1.0.dsdl

@@ -0,0 +1,13 @@
+# A list of service identifiers.
+# This is a trivial constant-size bitmask with some reserved space in case the range of service-ID is increased
+# in a future revision of the protocol.
+
+uint16 CAPACITY = ServiceID.1.0.MAX + 1
+
+bool[CAPACITY] mask
+# The index represents the identifier value. True -- present/used. False -- absent/unused.
+
+@extent 1024  # Reserve space in case the range is extended in the future.
+
+@assert CAPACITY % 8 == 0
+@assert _offset_ == {CAPACITY}

uavcan/node/port/SubjectIDList.0.1.dsdl

@@ -3,6 +3,7 @@
 # resource-constrained systems. To address that, we provide two extra options: a simple variable-length list,
 # and a special case that indicates that every subject-ID is in use.
 
+@deprecated  # Replaced with v1.
 @union
 
 uint16 CAPACITY = SubjectID.1.0.MAX + 1

uavcan/node/port/SubjectIDList.1.0.dsdl

@@ -0,0 +1,19 @@
+# A list of subject identifiers.
+# The range of subject-ID is large, so using a fixed-size bitmask would make this type difficult to handle on
+# resource-constrained systems. To address that, we provide two extra options: a simple variable-length list,
+# and a special case that indicates that every subject-ID is in use.
+
+@union
+
+uint16 CAPACITY = SubjectID.1.0.MAX + 1
+
+bool[CAPACITY] mask
+# The index represents the identifier value. True -- present/used. False -- absent/unused.
+
+SubjectID.1.0[<256] sparse_list
+# A list of identifiers that can be used instead of the mask if most of the identifiers are unused.
+
+uavcan.primitive.Empty.1.0 total
+# A special case indicating that all identifiers are in use.
+
+@extent 8 + 2 ** 15  # Reserve space in case the range is extended in the future.