Hi all!
I kindly request a vote.
Fixes: https://github.com/oasis-tcs/virtio-spec/issues/186
Best wishes,
Mikhail Golubev-Ciuchea
On 6/9/23 16:22, Mikhail Golubev-Ciuchea wrote:
From: Harald Mommer <harald.mommer@xxxxxxxxxxxxxxx>
virtio-can is a virtual CAN device. It provides a way to give access to
a CAN controller from a driver guest. The device is aimed to be used by
driver guests running a HLOS as well as by driver guests running a
typical RTOS as used in controller environments.
Signed-off-by: Harald Mommer <Harald.Mommer@xxxxxxxxxxxxxxx>
Signed-off-by: Mikhail Golubev-Ciuchea <Mikhail.Golubev-Ciuchea@xxxxxxxxxxxxxxx>
---
RFC v3:
* Add length fields in CAN RX and TX messages.
* Replace bus off indication queue with a config space bit.
* Clarify handling of unknown flag bits set in CAN frame.
* Remove MISRA C suffixes in constants.
* Reserve 16 bits in RX/TX messages for CAN XL priority.
* Reserve 8 bits in RX/TX messages for CAN classic DLC.
* Rework according to general virtio spec POV.
* Implementation:
driver: https://lore.kernel.org/all/20230607145613.133203-1-Mikhail.Golubev-Ciuchea@xxxxxxxxxxxxxxx/
QEmu device: https://github.com/OpenSynergy/qemu/tree/virtio-can-spec-rfc-v3
RFC v2:
* Add CAN classic feature flag.
* Add feature flag VIRTIO_CAN_F_LATE_TX_ACK.
* Add feature flag VIRTIO_CAN_F_RTR_FRAMES.
* Reserve 32 bits in RX/TX messages.
* Remove priorities of messages.
conformance.tex | 12 +-
content.tex | 1 +
device-types/can/description.tex | 249 ++++++++++++++++++++++++
device-types/can/device-conformance.tex | 8 +
device-types/can/driver-conformance.tex | 7 +
introduction.tex | 2 +
6 files changed, 275 insertions(+), 4 deletions(-)
create mode 100644 device-types/can/description.tex
create mode 100644 device-types/can/device-conformance.tex
create mode 100644 device-types/can/driver-conformance.tex
diff --git a/conformance.tex b/conformance.tex
index 01ccd69..a07ef02 100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -32,8 +32,9 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
\ref{sec:Conformance / Driver Conformance / Memory Driver Conformance},
\ref{sec:Conformance / Driver Conformance / I2C Adapter Driver Conformance},
\ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance},
-\ref{sec:Conformance / Driver Conformance / GPIO Driver Conformance} or
-\ref{sec:Conformance / Driver Conformance / PMEM Driver Conformance}.
+\ref{sec:Conformance / Driver Conformance / GPIO Driver Conformance},
+\ref{sec:Conformance / Driver Conformance / PMEM Driver Conformance} or
+\ref{sec:Conformance / Driver Conformance / CAN Driver Conformance}.
\item Clause \ref{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}.
\end{itemize}
@@ -59,8 +60,9 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
\ref{sec:Conformance / Device Conformance / Memory Device Conformance},
\ref{sec:Conformance / Device Conformance / I2C Adapter Device Conformance},
\ref{sec:Conformance / Device Conformance / SCMI Device Conformance},
-\ref{sec:Conformance / Device Conformance / GPIO Device Conformance} or
-\ref{sec:Conformance / Device Conformance / PMEM Device Conformance}.
+\ref{sec:Conformance / Device Conformance / GPIO Device Conformance},
+\ref{sec:Conformance / Device Conformance / PMEM Device Conformance} or
+\ref{sec:Conformance / Device Conformance / CAN Device Conformance}.
\item Clause \ref{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}.
\end{itemize}
@@ -152,6 +154,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
\input{device-types/scmi/driver-conformance.tex}
\input{device-types/gpio/driver-conformance.tex}
\input{device-types/pmem/driver-conformance.tex}
+\input{device-types/can/driver-conformance.tex}
\conformance{\section}{Device Conformance}\label{sec:Conformance / Device Conformance}
@@ -238,6 +241,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
\input{device-types/scmi/device-conformance.tex}
\input{device-types/gpio/device-conformance.tex}
\input{device-types/pmem/device-conformance.tex}
+\input{device-types/can/device-conformance.tex}
\conformance{\section}{Legacy Interface: Transitional Device and Transitional Driver Conformance}\label{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}
A conformant implementation MUST be either transitional or
diff --git a/content.tex b/content.tex
index d2ab9eb..8806b57 100644
--- a/content.tex
+++ b/content.tex
@@ -765,6 +765,7 @@ \chapter{Device Types}\label{sec:Device Types}
\input{device-types/scmi/description.tex}
\input{device-types/gpio/description.tex}
\input{device-types/pmem/description.tex}
+\input{device-types/can/description.tex}
\chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
diff --git a/device-types/can/description.tex b/device-types/can/description.tex
new file mode 100644
index 0000000..2511d9c
--- /dev/null
+++ b/device-types/can/description.tex
@@ -0,0 +1,249 @@
+\section{CAN Device}\label{sec:Device Types / CAN Device}
+
+virtio-can is a virtio based CAN (Controller Area Network) controller.
+It is used to give a virtual machine access to a CAN bus. The CAN bus
+might either be a physical CAN bus or a virtual CAN bus between virtual
+machines or a combination of both.
+
+\subsection{Device ID}\label{sec:Device Types / CAN Device / Device ID}
+
+36
+
+\subsection{Virtqueues}\label{sec:Device Types / CAN Device / Virtqueues}
+
+\begin{description}
+\item[0] Txq
+\item[1] Rxq
+\item[2] Controlq
+\end{description}
+
+The \field{Txq} is used to send CAN packets to the CAN bus.
+
+The \field{Rxq} is used to receive CAN packets from the CAN bus.
+
+The \field{Controlq} is used to control the state of the CAN controller.
+
+\subsection{Feature bits}{Device Types / CAN Device / Feature bits}
+
+Actual CAN controllers support Extended CAN IDs with 29 bits (CAN~2.0B)
+as well as Standard CAN IDs with 11 bits (CAN~2.0A). The support of
+CAN~2.0B Extended CAN IDs is considered as mandatory for this
+specification.
+
+\begin{description}
+
+\item[VIRTIO_CAN_F_CAN_CLASSIC (0)]
+
+The device supports classic CAN frames with a maximum payload size of 8
+bytes.
+
+\item[VIRTIO_CAN_F_CAN_FD (1)]
+
+The device supports CAN FD frames with a maximum payload size of 64
+bytes.
+
+\item[VIRTIO_CAN_F_RTR_FRAMES (2)]
+
+The device supports RTR (remote transmission request) frames. RTR frames
+are only supported with classic CAN.
+
+\item[VIRTIO_CAN_F_LATE_TX_ACK (3)]
+
+The virtio CAN device marks transmission requests from the \field{Txq}
+as used after the CAN message has been transmitted on the CAN bus. If
+this feature bit has not been negotiated, the device is allowed to mark
+transmission requests already as used when the CAN message has been
+scheduled for transmission but might not yet have been transmitted on
+the CAN bus.
+
+\end{description}
+
+\subsubsection{Feature bit requirements}\label{sec:Device Types / CAN Device / Feature bits / Feature bit requirements}
+
+Some CAN feature bits require other CAN feature bits:
+\begin{description}
+\item[VIRTIO_CAN_F_RTR_FRAMES] Requires VIRTIO_CAN_F_CAN_CLASSIC.
+\end{description}
+
+It is required that at least one of VIRTIO_CAN_F_CAN_CLASSIC and
+VIRTIO_CAN_F_CAN_FD is negotiated.
+
+\subsection{Device configuration layout}\label{sec:Device Types / CAN Device / Device configuration layout}
+
+Device configuration fields are listed below, they are read-only for a
+driver. The \field{status} always exists. A single read-only bit (for
+the driver) is currently defined for \field{status}:
+
+\begin{lstlisting}
+struct virtio_can_config {
+#define VIRTIO_CAN_S_CTRL_BUSOFF (1 << 0)
+ le16 status;
+};
+\end{lstlisting}
+
+The bit VIRTIO_CAN_S_CTRL_BUSOFF in \field{status} is used to indicate
+the unsolicited CAN controller state change from started to stopped due
+to a detected bus off condition.
+
+\drivernormative{\subsubsection}{Device Initialization}{Device Types / CAN Device / Device Operation / Initialization}
+
+The driver MUST populate the \field{Rxq} with empty device-writeable
+buffers of at least the size of struct virtio_can_rx, see section
+\ref{struct virtio_can_rx}.
+
+\subsection{Device Operation}\label{sec:Device Types / CAN Device / Device Operation}
+
+A device operation has an outcome which is described by one of the
+following values:
+
+\begin{lstlisting}
+#define VIRTIO_CAN_RESULT_OK 0
+#define VIRTIO_CAN_RESULT_NOT_OK 1
+\end{lstlisting}
+
+Other values are to be treated like VIRTIO_CAN_RESULT_NOT_OK.
+
+\subsubsection{Controller Mode}\label{sec:Device Types / CAN Device / Device Operation / Controller Mode}
+
+The general format of a request in the \field{Controlq} is
+
+\begin{lstlisting}
+struct virtio_can_control_out {
+#define VIRTIO_CAN_SET_CTRL_MODE_START 0x0201
+#define VIRTIO_CAN_SET_CTRL_MODE_STOP 0x0202
+ le16 msg_type;
+};
+\end{lstlisting}
+
+To participate in bus communication the CAN controller is started by
+sending a VIRTIO_CAN_SET_CTRL_MODE_START control message, to stop
+participating in bus communication it is stopped by sending a
+VIRTIO_CAN_SET_CTRL_MODE_STOP control message. Both requests are
+confirmed by the result of the operation.
+
+\begin{lstlisting}
+struct virtio_can_control_in {
+ u8 result;
+};
+\end{lstlisting}
+
+If the transition succeeded the \field{result} is VIRTIO_CAN_RESULT_OK
+otherwise it is VIRTIO_CAN_RESULT_NOT_OK. If a status update is
+necessary, the device updates the configuration \field{status} before
+marking the request used. As the configuration \field{status} change is
+caused by a request from the driver the device is allowed to omit the
+configuration change notification here. The device marks the request
+used when the CAN controller has finalized the transition to the
+requested controller mode.
+
+On transition to the STOPPED state the device cancels all CAN messages
+already pending for transmission and marks them as used with
+\field{result} VIRTIO_CAN_RESULT_NOT_OK. In the STOPPED state the
+device marks messages received from the
+\field{Txq} as used with \field{result} VIRTIO_CAN_RESULT_NOT_OK without
+transmitting them to the CAN bus.
+
+Initially the CAN controller is in the STOPPED state.
+
+Control queue messages are processed in order.
+
+\devicenormative{\subsubsection}{CAN Message Transmission}{Device Types / CAN Device / Device Operation / CAN Message Transmission}
+
+The driver transmits messages by placing outgoing CAN messages in the
+\field{Txq} virtqueue.
+
+\label{struct virtio_can_tx_out}
+\begin{lstlisting}
+struct virtio_can_tx_out {
+#define VIRTIO_CAN_TX 0x0001
+ le16 msg_type;
+ le16 length; /* 0..8 CC, 0..64 CAN-FD, 0..2048 CAN-XL, 12 bits */
+ u8 reserved_classic_dlc; /* If CAN classic length = 8 then DLC can be 8..15 */
+ u8 padding;
+ le16 reserved_xl_priority; /* May be needed for CAN XL priority */
+#define VIRTIO_CAN_FLAGS_FD 0x4000
+#define VIRTIO_CAN_FLAGS_EXTENDED 0x8000
+#define VIRTIO_CAN_FLAGS_RTR 0x2000
+ le32 flags;
+ le32 can_id;
+ u8 sdu[];
+};
+
+struct virtio_can_tx_in {
+ u8 result;
+};
+\end{lstlisting}
+
+The length of the \field{sdu} is determined by the \field{length}.
+
+The type of a CAN message identifier is determined by \field{flags}. The
+3 most significant bits of \field{can_id} do not bear the information
+about the type of the CAN message identifier and are 0.
+
+The device MUST reject any CAN frame type for which support has not been
+negotiated with VIRTIO_CAN_RESULT_NOT_OK in \field{result} and MUST NOT
+schedule the message for transmission. A CAN frame with an undefined bit
+set in \field{flags} is treated like a CAN frame for which support has
+not been negotiated.
+
+The device MUST reject any CAN frame for which \field{can_id} or
+\field{sdu} length are out of range or the CAN controller is in an
+invalid state with VIRTIO_CAN_RESULT_NOT_OK in \field{result} and MUST
+NOT schedule the message for transmission.
+
+If the parameters are valid the message is scheduled for transmission.
+
+If feature VIRTIO_CAN_F_CAN_LATE_TX_ACK has been negotiated the
+transmission request MUST be marked as used with \field{result} set to
+VIRTIO_CAN_OK after the CAN controller acknowledged the successful
+transmission on the CAN bus. If this feature bit has not been negotiated
+the transmission request MAY already be marked as used with
+\field{result} set to VIRTIO_CAN_OK when the transmission request has
+been processed by the virtio CAN device and send down the protocol stack
+being scheduled for transmission.
+
+\subsubsection{CAN Message Reception}\label{sec:Device Types / CAN Device / Device Operation / CAN Message Reception}
+
+Messages can be received by providing empty incoming buffers to the
+virtqueue \field{Rxq}.
+
+\label{struct virtio_can_rx}
+\begin{lstlisting}
+struct virtio_can_rx {
+#define VIRTIO_CAN_RX 0x0101
+ le16 msg_type;
+ le16 length; /* 0..8 CC, 0..64 CAN-FD, 0..2048 CAN-XL, 12 bits */
+ u8 reserved_classic_dlc; /* If CAN classic length = 8 then DLC can be 8..15 */
+ u8 padding;
+ le16 reserved_xl_priority; /* May be needed for CAN XL priority */
+ le32 flags;
+ le32 can_id;
+ u8 sdu[];
+};
+\end{lstlisting}
+
+If the feature VIRTIO_CAN_F_CAN_FD has been negotiated the maximal
+possible \field{sdu} length is 64, if the feature has not been
+negotiated the maximal possible \field{sdu} length is 8.
+
+The actual length of the \field{sdu} is determined by the \field{length}.
+
+The type of a CAN message identifier is determined by \field{flags} in
+the same way as for transmitted CAN messages, see section \ref{struct
+virtio_can_tx_out}. The 3 most significant bits of \field{can_id} do not
+bear the information about the type of the CAN message identifier and
+are 0. The flag bits are exactly the same as for the \field{flags} of
+struct virtio_can_tx_out.
+
+\subsubsection{BusOff Indication}\label{sec:Device Types / CAN Device / Device Operation / BusOff Indication}
+
+There are certain error conditions so that the physical CAN controller
+has to stop participating in CAN communication on the bus. If such an
+error condition occurs the device informs the driver about the
+unsolicited CAN controller state change by setting the
+VIRTIO_CAN_S_CTRL_BUSOFF bit in the configuration \field{status} field.
+
+After bus-off detection the CAN controller is in STOPPED state. The CAN
+controller does not participate in bus communication any more so all CAN
+messages pending for transmission are put into the used queue with
+\field{result} VIRTIO_CAN_RESULT_NOT_OK.
diff --git a/device-types/can/device-conformance.tex b/device-types/can/device-conformance.tex
new file mode 100644
index 0000000..f944ffd
--- /dev/null
+++ b/device-types/can/device-conformance.tex
@@ -0,0 +1,8 @@
+\conformance{\subsection}{CAN Device Conformance}\label{sec:Conformance / Device Conformance / CAN Device Conformance}
+
+A CAN device MUST conform to the following normative statements:
+
+\begin{itemize}
+\item \ref{devicenormative:Device Types / CAN Device / Feature bits}
+\item \ref{devicenormative:Device Types / CAN Device / Device Operation / CAN Message Transmission}
+\end{itemize}
diff --git a/device-types/can/driver-conformance.tex b/device-types/can/driver-conformance.tex
new file mode 100644
index 0000000..32e3e87
--- /dev/null
+++ b/device-types/can/driver-conformance.tex
@@ -0,0 +1,7 @@
+\conformance{\subsection}{CAN Driver Conformance}\label{sec:Conformance / Driver Conformance / CAN Driver Conformance}
+
+A CAN driver MUST conform to the following normative statements:
+
+\begin{itemize}
+\item \ref{drivernormative:Device Types / CAN Device / Device Operation / Initialization}
+\end{itemize}
diff --git a/introduction.tex b/introduction.tex
index b7155bf..d560c63 100644
--- a/introduction.tex
+++ b/introduction.tex
@@ -101,6 +101,8 @@ \section{Normative References}\label{sec:Normative References}
\phantomsection\label{intro:SEC1}\textbf{[SEC1]} &
Standards for Efficient Cryptography Group(SECG), ``SEC1: Elliptic Cureve Cryptography'', Version 1.0, September 2000.
\newline\url{https://www.secg.org/sec1-v2.pdf}\\
+ \phantomsection\label{intro:CAN}\textbf{[CAN]} &
+ ISO 11898-1:2015 Road vehicles -- Controller area network (CAN) -- Part 1: Data link layer and physical signalling\\
\end{longtable}
--
Mikhail Golubev-Ciuchea
OpenSynergy GmbH
Rotherstr. 20, 10245 Berlin
Telefon: +49 (30) 60985400
EMail:
mikhail.golubev-ciuchea@xxxxxxxxxxxxxxx<mailto:mikhail.golubev-ciuchea@xxxxxxxxxxxxxxx>
www.opensynergy.com
Handelsregister/Commercial Registry: Amtsgericht Charlottenburg, HRB 108616B
Geschäftsführer/Managing Director: Regis Adjamah
