Hi Matias,
On 2/20/24 13:19, Matias Ezequiel Vara Larsen wrote:
Hello Mikail,
On Mon, Jan 08, 2024 at 06:18:50PM +0100, Mikhail Golubev-Ciuchea wrote:
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
Is this to indicate that when a driver requests a change, the device can
omit notifying of the change? As I understand the specification, the
device can omit the notification, but the change must still occur? Is it
possible for the device to omit the change as well? What else could have
triggered the status change if it wasn't the driver?
Thanks.
The change request notification OK/NOT_OK for every mode transition
request is there in any case. In some cases the device would
additionally notify the driver about the controller status via
'virtio_can_config' in config space (config space change notification
mechanism), e.g. in case of a BusOff event on the device side. Although,
it is possible to omit the config space notification e.g. when
transitioning to stopped mode.
In the previous draft version of the spec a separate asynchronous queue
was used to send BusOff events and the proposal had an issue with races:
it was not possible to distinguish whether a received BusOff event was
meant to be from an old session or is already from the new session.
Hence, the indication queue was removed and a config space status was
added instead.
Best regard,
Mikhail
--
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
