Address design issues in uavcan.metatransport (#99)

* Address #96 for CAN transport * Address #96 for serial * Address #96 for UDP by replacing it with uavcan.metatransport.ethernet * Add explicit deprecation note
OpenCyphal · Jan 8, 2021 · f07d09b · f07d09b
1 parent d874225
commit f07d09b
Show file tree

Hide file tree

Showing 10 changed files with 53 additions and 0 deletions.
diff --git a/uavcan/metatransport/can/Frame.0.1.uavcan b/uavcan/metatransport/can/Frame.0.1.uavcan
@@ -1,5 +1,7 @@
 # CAN 2.0 or CAN FD frame representation. This is the top-level data type in its namespace.
 
+@deprecated  # See next version.
+
 uavcan.time.SynchronizedTimestamp.1.0 timestamp
 
 Manifestation.0.1 manifestation

diff --git a/uavcan/metatransport/can/Frame.0.2.uavcan b/uavcan/metatransport/can/Frame.0.2.uavcan
@@ -0,0 +1,12 @@
+# Classic CAN or CAN FD frame representation. This is the top-level data type in its namespace.
+
+@union
+
+Error.0.1       error                        # CAN error (intentional or disturbance)
+DataFD.0.1      data_fd                      # Bit rate switch flag active
+DataClassic.0.1 data_classic                 # Bit rate switch flag not active
+RTR.0.1         remote_transmission_request  # Bit rate switch flag not active
+
+@sealed                         # Sealed because the structure is rigidly dictated by an external standard.
+@assert _offset_.min == 8 + 32
+@assert _offset_.max == 8 + 8 + 32 + 8 + 64 * 8
diff --git a/uavcan/metatransport/can/Manifestation.0.1.uavcan b/uavcan/metatransport/can/Manifestation.0.1.uavcan
@@ -1,5 +1,6 @@
 # CAN frame properties that can be manifested on the bus.
 
+@deprecated     # See Frame.0.2 as a replacement
 @union
 
 Error.0.1       error                        # CAN error (intentional or disturbance)

diff --git a/uavcan/metatransport/ethernet/EtherType.0.1.uavcan b/uavcan/metatransport/ethernet/EtherType.0.1.uavcan
@@ -0,0 +1,10 @@
+# Standard EtherType constants as defined by IEEE Registration Authority and IANA.
+# This list is only a small subset of constants that are considered to be relevant for UAVCAN.
+
+uint16 value
+
+uint16 IP_V4 = 0x0800
+uint16 ARP   = 0x0806
+uint16 IP_V6 = 0x86DD
+
+@sealed
diff --git a/uavcan/metatransport/ethernet/Frame.0.1.uavcan b/uavcan/metatransport/ethernet/Frame.0.1.uavcan
@@ -0,0 +1,11 @@
+# IEEE 802.3 Ethernet frame encapsulation.
+# In terms of libpcap/tcpdump, the corresponding link type is LINKTYPE_ETHERNET/DLT_EN10MB.
+
+uint8[6] destination
+uint8[6] source
+
+EtherType.0.1 ethertype
+
+uint8[<=9216] payload  # Supports conventional jumbo frames (up to 9 KiB).
+
+@sealed  # Sealed because the format is defined by external specifications.
diff --git a/uavcan/metatransport/serial/Fragment.0.1.uavcan b/uavcan/metatransport/serial/Fragment.0.1.uavcan
@@ -1,6 +1,8 @@
 # A chunk of raw bytes exchanged over a serial transport. Serial links do not support framing natively.
 # The chunk may be of arbitrary size.
 
+@deprecated  # See next version.
+
 uavcan.time.SynchronizedTimestamp.1.0 timestamp
 
 uint9 CAPACITY_BYTES = 256

diff --git a/uavcan/metatransport/serial/Fragment.0.2.uavcan b/uavcan/metatransport/serial/Fragment.0.2.uavcan
@@ -0,0 +1,10 @@
+# A chunk of raw bytes exchanged over a serial transport. Serial links do not support framing natively.
+# The chunk may be of arbitrary size.
+#
+# If this data type is used to encapsulate UAVCAN/serial, then it is recommended to ensure that each message
+# contains at most one UAVCAN/serial transport frame (frames are separated by zero-valued delimiter bytes).
+
+uint12 CAPACITY_BYTES = 2048
+uint8[<=CAPACITY_BYTES] data
+
+@sealed
diff --git a/uavcan/metatransport/udp/DEPRECATED b/uavcan/metatransport/udp/DEPRECATED
@@ -0,0 +1 @@
+All data types in this namespace are deprecated. Find replacement under uavcan.metatransport.ethernet.
diff --git a/uavcan/metatransport/udp/Endpoint.0.1.uavcan b/uavcan/metatransport/udp/Endpoint.0.1.uavcan
@@ -1,5 +1,7 @@
 # A UDP/IP endpoint address specification.
 
+@deprecated  # Replaced by uavcan.metatransport.ethernet
+
 uint8[16] ip_address
 # The IP address of the host in the network byte order (big endian).
 # IPv6 addresses are represented as-is.

diff --git a/uavcan/metatransport/udp/Frame.0.1.uavcan b/uavcan/metatransport/udp/Frame.0.1.uavcan
@@ -1,6 +1,8 @@
 # A generic UDP/IP frame.
 # Jumboframes are supported in the interest of greater application compatibility.
 
+@deprecated  # Replaced by uavcan.metatransport.ethernet
+
 uavcan.time.SynchronizedTimestamp.1.0 timestamp
 
 void8
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		All data types in this namespace are deprecated. Find replacement under uavcan.metatransport.ethernet.