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} -- 2.34.1
