Merge pull request #32 from UAVCAN/subject-id

Chapters 1 and 2

specification/UAVCAN_Specification.tex

@@ -53,7 +53,7 @@ \section*{Support and feedback}
 
 \section*{License}
 
-UAVCAN is a standard open to everyone.
+UAVCAN is a standard open to everyone, and it will always remain this way.
 No licensing or approval of any kind is necessary for its implementation, distribution, or use.
 
 % The following statement looks a bit archaic, but it is the recommended form according to
@@ -63,7 +63,7 @@ \section*{License}
 or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
 
 \begin{center}
-    \includegraphics[width=0.2\textwidth]{cc-by}
+    \includegraphics[width=0.3\textwidth]{cc-by}
 \end{center}
 
 \BeginRightColumn

specification/basic_concepts/basic_concepts.tex

@@ -1,79 +1,210 @@
 \chapter{Basic concepts}\label{sec:basic_concepts}
 
+\section{Main principles}
+
+\subsection{Communication}
+
+\subsubsection{Architecture}
 
 A UAVCAN network is a decentralized peer network, where each peer (node) has a unique
-numeric identifier --- \emph{node ID} --- ranging from 1 to 127, inclusively.
+numeric identifier\footnote{Here and elsewhere in this specification, \emph{ID} and \emph{identifier} are used
+interchangeably unless specifically indicated otherwise.}
+--- \emph{node ID} --- ranging from 1 to 127, inclusively.
 Nodes of a UAVCAN network can communicate using the following communication methods:
 
 \begin{description}
-    \item[Message broadcasting] --- The primary method of data exchange with one-to-all publish/subscribe semantics.
-    \item[Service invocation] --- The communication method for peer-to-peer request/response
+    \item[Message publication] --- The primary method of data exchange with one-to-many publish/subscribe semantics.
+    \item[Service invocation] --- The communication method for one-to-one request/response
     interactions\footnote{Like remote procedure call (RPC).}.
 \end{description}
 
-For each type of communication, a predefined set of data structures is used,
-where each data structure has a unique identifier --- the \emph{data type ID} (DTID).
-Additionally, every data structure definition has a pair of major and minor semantic version numbers,
+For each type of communication, a predefined set of data types is used,
+where each data type has a unique name.
+Additionally, every data type definition has a pair of major and minor version numbers,
 which enable data type definitions to evolve in arbitrary ways while ensuring a well-defined
 migration path if backward-incompatible changes are introduced.
-Some data structures are standard and defined by the protocol specification (of which only a small 
+Some data types are standard and defined by the protocol specification (of which only a small
 subset are required); others may be specific to a particular application or vendor.
 
-Since every message or service data type has its own unique data type ID,
-and each node in the network has its own unique node ID,
-a pair of data type ID and node ID can be used to support redundant nodes with identical
-functionality inside the same network.
+\subsubsection{Subjects and services}
+
+Message exchanges between nodes are grouped into \emph{subjects} by the semantic meaning of the message.
+Message exchanges belonging to the same subject use same message data type down to the major version
+(minor versions are allowed to differ) and pertain to same function or process within the system.
+
+Request/response exchanges between nodes are grouped into \emph{services} by the semantic meaning
+of the request and response,
+like messages are grouped into subjects.
+Requests and their corresponding responses that belong to the same service use same service data type down to
+the major version (minor versions are allowed to differ; as a consequence, the minor data type version number
+of a service response may differ from that of its corresponding request) and pertain to the same function.
+
+Each message subject is identified by a unique natural number -- a \emph{subject ID};
+likewise, each service is identified by a unique \emph{service ID}.
+An umbrella term \emph{port ID} is used to refer either to a subject ID or to a service ID
+(port identifiers have no direct manifestation in the construction of the protocol,
+but they are convenient for discussion).
+
+\subsection{Data types}
+
+\subsubsection{Data type definitions}
+
+Message and service data types\footnote{Data types are the core concept of UAVCAN.}
+are defined using the \emph{data structure description language} (DSDL) (chapter \ref{sec:dsdl}).
+A DSDL definition specifies the name, major version, minor version, the data structure,
+and an optional predefined port ID of the data type.
+Message data types always contain exactly one data structure, whereas
+service data types contain two data structures: one for request, and the other for response.
+
+If a port identifier is specified in a data type definition, such identifier is said to be a
+\emph{fixed port identifier}
+(by inheritance, the same naming principle applies to \emph{fixed subject ID} and \emph{fixed service ID}).
+A data type can be used with an arbitrary number of different port identifiers assigned on a per-application basis,
+but not more than one fixed port identifier.
+
+\subsubsection{Regulation}
+
+Data type definitions can be created by the UAVCAN specification maintainers or by its users,
+such as equipment vendors or application designers.
+Irrespective of the origin, data types can be included into the set of data type definitions maintained
+and distributed by the UAVCAN specification maintainers;
+definitions belonging to this set are termed \emph{regulated data type definitions}.
+The specification maintainers undertake to keep regulated definitions well-maintained and may occasionally
+amend them and release new versions, if such actions are believed to benefit the protocol.
+User-created (i.e., vendor-specific or application-specific) data type definitions that are
+not included into the aforementioned set are called \emph{unregulated data type definitions}.
+
+Unregulated definitions that are made available for reuse by others are called
+\emph{unregulated public data type definitions};
+those that are kept closed-source for private use by their authors are called
+\emph{(unregulated) private data type definitions}\footnote{The word \emph{``unregulated''} is redundant
+because private data types cannot be regulated, by definition.
+Likewise, all regulated definitions are public, so the word \emph{``public''} can be omitted.}.
+
+Data type definitions authored by the specification maintainers for the purpose of supporting and advancing
+this specification are called \emph{standard data type definitions}.
+All standard data type definitions are regulated.
+
+Fixed port identifiers can be used only with regulated data type definitions or with private definitions.
+Fixed port identifiers must not be used with public unregulated data types,
+since that is likely to cause unresolvable port identifier collisions\footnote{
+    Any system that relies on data type definitions with fixed port identifiers provided by
+    an external party (i.e., data types and the system in question are designed by different parties)
+    runs the risk of encountering port identifier conflicts that cannot be resolved without resorting to help
+    from said external party since the designers of the system do not have control over their fixed port identifiers.
+    Because of this, the specification strongly discourages the use of fixed unregulated private port identifiers.
+    If a data type definition is ever disclosed to any other party (i.e., a party that did not author it)
+    or to the public at large it is important that the data type \emph{not} include a fixed port-identifier.
+}.
+This restriction shall be followed at all times by all compliant implementations and
+systems\footnote{
+    In general, private unregulated fixed port identifiers are collision-prone by their nature, so they should
+    be avoided unless there are very strong reasons for their usage and the authors fully understand the risks.
+}.
+
+\begin{UAVCANSimpleTable}{Data type taxonomy}{|l|X|X|}
+    & Regulated & Unregulated \\
+    \bfseries{Public}
+    &
+    Standard and contributed (e.g., vendor-specific) definitions.\newline
+    Fixed port identifiers are allowed; they are called \emph{``regulated port ID''}.
+    &
+    Definitions distributed separately from the UAVCAN specification.\newline
+    Fixed port identifiers are \emph{not allowed}.
+    \\
+
+    \bfseries{Private}
+    &
+    Nonexistent category.
+    &
+    Definitions that are not available to anyone except their authors.\newline
+    Fixed port identifiers are permitted (although not recommended) as long as the definition is only used by
+    its authors; they are called \emph{``unregulated fixed port ID''}.
+    \\
+\end{UAVCANSimpleTable}
+
+DSDL processing tools shall prohibit unregulated fixed port identifiers by default,
+unless they are explicitly configured otherwise.
+
+Each of the two sets of valid port identifiers (which are subject identifiers and port identifiers) are
+segregated into three categories: application-specific (i.e., non-fixed or unregulated) identifiers,
+regulated non-standard port identifiers, and standard port identifiers.
+Fixed unregulated port identifiers can be allocated in the same range where application-specific identifiers are.
+The ranges are documented in chapter \ref{sec:application_layer}.
+
+Data type authors that want to release regulated data type definitions or contribute to the standard data
+type set should contact the UAVCAN maintainers for coordination.
+The maintainers will choose unoccupied fixed port identifiers for use with the new definitions, if necessary.
+Since the set of regulated definitions is maintained in a highly centralized manner,
+it can be statically ensured that no identifier collisions will take place within it;
+also, since the identifier ranges used with regulated definitions are segregated,
+regulated port-IDs will not conflict with any other compliant UAVCAN node or system\footnote{
+    The motivation for the prohibition of fixed port identifiers in unregulated public data types is
+    derived directly from the above: since there is no central repository of unregulated definitions,
+    collisions would be likely.
+}.
 
-Message and service data structures are defined using the Data Structure Description Language
-(DSDL) (chapter \ref{sec:dsdl}).
-A DSDL description can be used to automatically generate the serialization/deserialization code
-for every defined data structure in a particular programming language.
+\subsubsection{Serialization}
+
+A DSDL description can be used to automatically generate the serialization and deserialization code
+for every defined data type in a particular programming language.
+Alternatively, a DSDL description can be used to construct appropriate serialization code manually by a human.
 DSDL ensures that the worst case memory footprint and computational complexity per data type
 are constant and easily predictable.
 
+Serialized message and service data structures are exchanged by means of the transport
+layer (chapter \ref{sec:transport_layer}), which implements automatic decomposition of
+long transfers into several transport frames\footnote{Here and
+elsewhere, a \emph{transport frame} means a block of data that can be atomically exchanged
+over the transport layer network, e.g., a CAN frame.} and reassembly from these transport frames
+back into a single atomic data block, allowing nodes to exchange data structures of
+arbitrary size.
+
+\subsection{High-level functions}
+
 On top of the standard data types, UAVCAN defines a set of standard high-level functions including:
 node health monitoring, node discovery, time synchronization, firmware update,
 plug-and-play node support, and more.
 For more information see chapter \ref{sec:application_layer}.
 
-Serialized message and service data structures are exchanged by means of the transport
-layer (chapter \ref{sec:transport_layer}), which implements automatic decomposition of
-long transfers into several transport frames\footnote{Here and 
-elsewhere, a \emph{transport frame} means a block of data that can be atomically exchanged 
-over the network, e.g., a CAN frame.} and reassembly from these transport frames
-back into a single transfer buffer, allowing nodes to exchange data structures of 
-arbitrary size.
-
 \begin{figure}[hbt]
     \centering
     \begin{tabular}{|c|c|l|c|l|c|}
         \hline
-        \multicolumn{6}{|c|}{Applications}                                                                                              \\ \hline
-        \multicolumn{1}{|l|}{} & Required functions &            & Standard functions          &            & Custom functions          \\ \cline{2-2} \cline{4-4} \cline{6-6} 
-        \multicolumn{2}{|c|}{Required data types}   & \multicolumn{2}{c|}{Standard data types} & \multicolumn{2}{c|}{Custom data types} \\ \hline
-        \multicolumn{6}{|c|}{Serialization}                                                                                             \\ \hline
-        \multicolumn{6}{|c|}{Transport}                                                                                                 \\ \hline
+        \multicolumn{6}{|c|}{Applications} \\ \hline
+
+        \qquad{} & Required functions &
+        \qquad{} & Standard functions &
+        \qquad{} & Custom functions \\
+        \cline{2-2} \cline{4-4} \cline{6-6}
+
+        \multicolumn{2}{|c|}{Required data types} &
+        \multicolumn{2}{c|}{Standard data types} &
+        \multicolumn{2}{c|}{Custom data types} \\ \hline
+
+        \multicolumn{6}{|c|}{Serialization} \\ \hline
+
+        \multicolumn{6}{|c|}{Transport} \\ \hline
     \end{tabular}
     \caption{UAVCAN architectural diagram.\label{fig:architecture}}
 \end{figure}
 
-\section{Message broadcasting}
+\section{Message publication}
 
-Message broadcasting refers to the transmission of a serialized data structure over the network to other nodes.
+Message publication refers to the transmission of a serialized data structure over the network to other nodes.
 This is the primary data exchange mechanism used in UAVCAN;
 it is functionally similar to raw data exchange with minimal overhead,
 additional communication integrity guarantees, and automatic decomposition and reassembly of long payloads
 across multiple transport frames.
 Typical use cases may include transfer of the following kinds of data (either cyclically or on an ad-hoc basis):
 sensor measurements, actuator commands, equipment status information, and more.
 
-Information contained in a broadcast message is summarized in the table \ref{table:broadcast_message_info}.
+Information contained in a published message is summarized in the table \ref{table:published_message_info}.
 
-\begin{UAVCANSimpleTable}{Broadcast message properties}{|l X|}\label{table:broadcast_message_info}
+\begin{UAVCANSimpleTable}{Published message properties}{|l X|}\label{table:published_message_info}
     Property        & Description \\
     Payload         & The serialized message data structure. \\
-    Data type ID    & Numerical identifier that indicates how the data structure should be interpreted. \\
-    Data type major version number & Semantic major version number of the data type description. \\
+    Subject ID      & Numerical identifier that indicates how the information should be interpreted. \\
     Source node ID  & The node ID of the transmitting node (excepting anonymous messages). \\
     Transfer ID     & A small overflowing integer that increments with every transfer
                       of this message type from a given node. Used for message sequence monitoring,
@@ -83,20 +214,21 @@ \section{Message broadcasting}
                       detail in the chapter \ref{sec:transport_layer}. \\
 \end{UAVCANSimpleTable}
 
-\subsection{Anonymous message broadcasting}
+\subsection{Anonymous message publication}
 
-Nodes that don't have a unique node ID can publish \emph{anonymous messages}.
-An anonymous message is different from a regular message in that it doesn't contain a source node ID.
+Nodes that don't have a unique node ID can publish only \emph{anonymous messages}.
+An anonymous message is different from a regular message in that it doesn't contain a source node ID,
+and that it can't be decomposed across several transport frames.
 
 UAVCAN nodes will not have an identifier initially until they are assigned one,
 either statically (which is generally the preferred option for applications where a high degree of
-determinism and high safety assurances are required) or dynamically.
-Anonymous messages are particularly useful for the dynamic node ID allocation feature,
-which is explored in detail in the chapter~\ref{sec:application_layer}.
+determinism and high safety assurances are required) or automatically (i.e., plug-and-play).
+Anonymous messages are particularly useful for the plug-and-play feature,
+which is explored in detail in chapter~\ref{sec:application_layer}.
 
 Anonymous messages cannot be decomposed into multiple transport frames,
 meaning that their payload capacity is limited to that of a single transport frame.
-More info is provided in the chapter~\ref{sec:transport_layer}.
+More info is provided in chapter~\ref{sec:transport_layer}.
 
 \section{Service invocation}
 
@@ -112,16 +244,15 @@ \section{Service invocation}
 
 Typical use cases for this type of communication include:
 node configuration parameter update, firmware update, an ad-hoc action request, file transfer,
-and similar service tasks.
+and other functions of similar nature.
 
 Information contained in service requests and responses is summarized in the
 table \ref{table:service_req_resp_info}.
 
 \begin{UAVCANSimpleTable}{Service request/response properties}{|l X|}\label{table:service_req_resp_info}
     Property        & Description \\
     Payload         & The serialized request/response data structure. \\
-    Data type ID    & Numerical identifier that indicates how the data structure should be interpreted. \\
-    Data type major version number & Semantic major version number of the data type definition. \\
+    Service ID      & Numerical identifier that indicates how the service should be handled. \\
     Client node ID  & Source node ID during request transfer, destination node ID during response transfer. \\
     Server node ID  & Destination node ID during request transfer, source node ID during response transfer. \\
     Transfer ID     & A small overflowing integer that increments with every call
@@ -132,7 +263,7 @@ \section{Service invocation}
                       detail in the chapter \ref{sec:transport_layer}. \\
 \end{UAVCANSimpleTable}
 
-Both request and response contain same values for all listed fields except payload,
+Both the request and the response contain same values for all listed fields except payload,
 where the content is application-defined.
 Clients match responses with corresponding requests using the following fields:
-data type ID, data type major version number, client node ID, server node ID, and transfer ID.
+service ID, client node ID, server node ID, and transfer ID.