transport updates

Author: pavel-kirienko

specification/transport/can/can.tex

@@ -255,6 +255,53 @@ \subsection{CAN ID field}
                                                       client if request, server if response. \\
 \end{CyphalSimpleTable}
 
+\subsubsection{Format selection}\label{sec:transport_can_format_selection}
+
+The two message formats differ not only in the CAN ID bit layout but also in the payload carried on the wire.
+The v1.1 16-bit format carries a full session-layer message including its session-layer header;
+the v1.0 legacy 13-bit format carries only the raw application payload without any session-layer wrapping,
+which is what makes it wire-compatible with Cyphal/CAN v1.0 nodes that predate the session layer.
+
+A sender shall use the v1.0 legacy 13-bit format for a message transfer if and only if both of the following hold:
+(a) the subject-ID lies in the pinned range $[0, 8191]$, and
+(b) the message is a best-effort publication.
+In all other cases -- auto-allocated subject-IDs, the broadcast subject, gossip shards, reliable messages,
+gossip messages, service discovery, and RPC -- the sender shall use the v1.1 16-bit format.
+
+When transmitting on a pinned subject using the 13-bit format, the sender shall strip the session-layer
+header from the outgoing message before enqueuing the frame, so that only the raw application payload
+appears on the wire. This is what makes a 13-bit frame parseable by Cyphal/CAN v1.0 nodes,
+which are unaware of the session layer.
+
+When receiving a 13-bit-format frame on a subscribed pinned subject, the receiver shall reconstruct a
+session-layer header consistent with the matching pinned topic and prepend it to the received payload
+before forwarding the message to the session layer. The reconstructed header shall declare the message as
+best-effort and shall carry a message tag drawn from a monotonically increasing per-subscription counter,
+so that session-layer duplicate suppression continues to function.
+The reconstructed message shall be otherwise indistinguishable from an equivalent message originated by
+a v1.1 node on the same pinned topic.
+
+\begin{remark}
+    This rule confines every v1.1-specific feature to the 16-bit format, which v1.0 receivers unconditionally
+    discard at the bit~7 check. A message reaching a v1.0 receiver is therefore always in a form that the
+    receiver can parse: a plain application payload on a pinned subject-ID.
+\end{remark}
+
+\subsubsection{Unicast transfers}\label{sec:transport_can_unicast}
+
+Cyphal/CAN does not define a dedicated CAN ID layout for unicast delivery.
+A unicast transfer shall be represented as an RPC-service \emph{request} to the reserved service-ID $511$
+addressed to the destination node.
+The session layer treats service-ID $511$ as an opaque unicast channel;
+no service response is issued at the transport layer, and higher-layer reply semantics, if any,
+are carried in subsequent unicast requests in the opposite direction.
+
+The sender shall maintain a $128$-element array of transfer-ID counters indexed by the destination node-ID,
+and increment the entry corresponding to the destination of each outgoing unicast transfer.
+This ensures that the receiver observes a monotonic transfer-ID stream on every $(\text{source}, \text{destination})$
+pair, so that the standard transfer-ID timeout check
+(section~\ref{sec:transport_can_transfer_id_timeout}) applies without modification.
+
 \subsubsection{Transfer priority}
 
 Valid values for transfer priority range from 0 to 7, inclusively,
@@ -421,6 +468,33 @@ \subsubsection{Transfer CRC}\label{sec:transport_can_transfer_crc}
 The transfer CRC function is \textbf{CRC-16/CCITT-FALSE}:
 polynomial $0x1021$, initial value $0xFFFF$, no input or output reflection, no final XOR.
 
+\subsubsection{Transfer-ID timeout}\label{sec:transport_can_transfer_id_timeout}
+
+The \emph{transfer-ID timeout} governs the duration over which a receiver retains the last-admitted
+transfer-ID of a reassembly session for duplicate suppression. A start-of-transfer frame whose transfer-ID
+matches the last-admitted value within the timeout window is discarded as a duplicate;
+after the timeout elapses, the next admission is accepted unconditionally.
+The recommended default value is $2$ seconds.
+
+The timeout applies to the following session kinds:
+\begin{itemize}
+    \item Message (subject) sessions, in both the v1.1 16-bit and the v1.0 legacy 13-bit formats.
+    \item Service request sessions, including the unicast channel defined in
+    section~\ref{sec:transport_can_unicast}.
+\end{itemize}
+
+A transfer-ID timeout of \emph{zero} shall be used for service \emph{response} sessions.
+The transfer-ID of a service response is not generated by the server -- it is echoed from the request being
+answered. Because the transfer-ID field is only five bits wide, the client may legitimately re-use the same
+transfer-ID value for two different requests to the same server within a short interval as its counter wraps;
+with a nonzero timeout, the later matching response would be rejected as a duplicate of the earlier one.
+Setting the timeout to zero disables transport-level duplicate suppression on response sessions,
+leaving the receiving application to correlate responses with outstanding requests by other
+means\footnote{%
+    See \href{https://github.com/OpenCyphal/libcanard/issues/247}{OpenCyphal/libcanard issue~247}
+    for the original discussion.
+}.
+
 \subsection{Examples}
 
 \begin{remark}[breakable]

specification/transport/transport.tex

@@ -2,7 +2,26 @@ \chapter{Transport layer}\label{sec:transport}
 
 \section{Function}
 
-TODO: DEFINE THE CORE TRANSPORT CONTRACT PER cy.
+A Cyphal \emph{transport} provides unreliable, unordered, deduplicated delivery of integrity-checked messages
+between Cyphal nodes. A message is either delivered intact or not delivered at all; the transport performs
+neither retransmission nor ordering recovery. Reliable delivery, ordering, and session semantics, where required,
+are provided by higher layers on top of this minimal contract.
+
+A transport shall provide two delivery modes:
+\begin{description}
+    \item[Multicast] Delivery to the group of subscribers on a \emph{subject}, identified by a numerical
+    \emph{subject-ID}\footnote{In IP networks this analogous to multicast groups.}.
+    \item[Unicast] Delivery to a single \emph{remote node}, identified by its \emph{node-ID}.
+\end{description}
+
+Messages may be of arbitrary size not larger than 4 gibibytes.
+A transport shall perform segmentation and reassembly transparently to the higher layers,
+so that a received message is always delivered as a single unit.
+A transport may offer redundant interfaces for fault tolerance, with transparent failover,
+which is invisible to the higher layers.
+
+Participant discovery is provided implicitly as a side effect of joining the broadcast subject defined in
+section~\ref{sec:transport_subject_id_ranges}; no separate discovery protocol is required.
 
 \section{Definitions}
 
@@ -150,5 +169,29 @@ \subsection{Redundancy}
     Specific examples include time synchronization algorithms or diagnostic probes.
 }.
 
+\subsection{Subject-ID ranges}\label{sec:transport_subject_id_ranges}
+
+Subject-ID values range from zero up to a transport-specific maximum and are partitioned as follows:
+
+\begin{description}
+    \item[{$[0,\, 8191]$ -- pinned subjects}] Statically-assigned subject-IDs.
+    This range is the only one used by Cyphal/CAN v1.0 and is retained as the primary path for interoperation
+    with v1.0 nodes.
+
+    \item[{$[8192,\, 8191{+}M]$ -- auto-allocated subjects}] Subject-IDs assigned dynamically by the session layer,
+    where $M$ is a transport-specific prime \emph{modulus} satisfying $M \bmod 4 = 3$.
+
+    \item[Maximum value -- broadcast subject] Used by the session layer for low-rate broadcast traffic such as
+    topic allocation gossip and service discovery scouts.
+
+    \item[Remaining values -- gossip shards] Subject-IDs strictly between $(8191{+}M)$ and the broadcast subject
+    are used as sharded subjects for background gossip propagation.
+\end{description}
+
+On the broadcast subject and on the gossip shard subjects, the transport is permitted to relax two requirements:
+(a) deduplication is not mandatory, and (b) support for messages exceeding a single transport frame is not required.
+The session layer tolerates occasional duplication on these subjects and constrains its own protocol messages
+to fit within a single transport frame.
+
 % Please keep \clearpage in front of every section to enforce clear separation!
 \clearpage\input{transport/can/can.tex}