[virtio-comment] Re: [PATCH v2] virtio-i2c: add the device specification

["Michael S. Tsirkin" <mst@redhat.com>]

On Fri, Oct 23, 2020 at 02:51:25PM +0800, Jie Deng wrote:
> virtio-i2c is a virtual I2C adapter device. It provides a way
> to flexibly communicate with the I2C slave devices from the guest.
> 
> This patch adds the specification for this device.
> 
> Signed-off-by: Jie Deng <jie.deng@intel.com>
> ---
>  conformance.tex | 28 +++++++++++++++---
>  content.tex     |  1 +
>  virtio-i2c.tex  | 88 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  3 files changed, 113 insertions(+), 4 deletions(-)
>  create mode 100644 virtio-i2c.tex
> 
> diff --git a/conformance.tex b/conformance.tex
> index f1f23a8..12bce3a 100644
> --- a/conformance.tex
> +++ b/conformance.tex
> @@ -27,8 +27,10 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
>  \ref{sec:Conformance / Driver Conformance / Socket Driver Conformance},
>  \ref{sec:Conformance / Driver Conformance / RPMB Driver Conformance},
>  \ref{sec:Conformance / Driver Conformance / IOMMU Driver Conformance},
> -\ref{sec:Conformance / Driver Conformance / Sound Driver Conformance} or
> -\ref{sec:Conformance / Driver Conformance / Memory Driver Conformance}.
> +\ref{sec:Conformance / Driver Conformance / Sound Driver Conformance}
> +\ref{sec:Conformance / Driver Conformance / Memory Driver Conformance} or
> +\ref{sec:Conformance / Driver Conformance / I2C Adapter Driver Conformance}.
> +
>      \item Clause \ref{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}.
>    \end{itemize}
>  \item[Device] A device MUST conform to four conformance clauses:
> @@ -47,8 +49,10 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
>  \ref{sec:Conformance / Device Conformance / Socket Device Conformance}, 
>  \ref{sec:Conformance / Device Conformance / RPMB Device Conformance},
>  \ref{sec:Conformance / Device Conformance / IOMMU Device Conformance},
> -\ref{sec:Conformance / Device Conformance / Sound Device Conformance} or
> -\ref{sec:Conformance / Device Conformance / Memory Device Conformance}.
> +\ref{sec:Conformance / Device Conformance / Sound Device Conformance}
> +\ref{sec:Conformance / Device Conformance / Memory Device Conformance} or
> +\ref{sec:Conformance / Device Conformance / I2C Adapter Device Conformance}.
> +
>      \item Clause \ref{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}.
>    \end{itemize}
>  \end{description}
> @@ -261,6 +265,14 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
>  \item \ref{drivernormative:Device Types / Memory Device / Device Operation / STATE request}
>  \end{itemize}
>  
> +\conformance{\subsection}{I2C Adapter Driver Conformance}\label{sec:Conformance / Driver Conformance / I2C Adapter Driver Conformance}
> +
> +An I2C Adapter driver MUST conform to the following normative statements:
> +
> +\begin{itemize}
> +\item \ref{drivernormative:Device Types / I2C Adapter Device / Device Operation}
> +\end{itemize}
> +
>  \conformance{\section}{Device Conformance}\label{sec:Conformance / Device Conformance}
>  
>  A device MUST conform to the following normative statements:
> @@ -477,6 +489,14 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
>  \item \ref{devicenormative:Device Types / Memory Device / Device Operation / STATE request}
>  \end{itemize}
>  
> +\conformance{\subsection}{I2C Adapter Device Conformance}\label{sec:Conformance / Device Conformance / I2C Adapter Device Conformance}
> +
> +An I2C Adapter device MUST conform to the following normative statements:
> +
> +\begin{itemize}
> +\item \ref{devicenormative:Device Types / I2C Adapter Device / Device Operation}
> +\end{itemize}
> +
>  \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
>  non-transitional, see \ref{intro:Legacy
> diff --git a/content.tex b/content.tex
> index 91855b4..95e2ed8 100644
> --- a/content.tex
> +++ b/content.tex
> @@ -6200,6 +6200,7 @@ \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device
>  \input{virtio-iommu.tex}
>  \input{virtio-sound.tex}
>  \input{virtio-mem.tex}
> +\input{virtio-i2c.tex}
>  
>  \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
>  
> diff --git a/virtio-i2c.tex b/virtio-i2c.tex
> new file mode 100644
> index 0000000..379f683
> --- /dev/null
> +++ b/virtio-i2c.tex
> @@ -0,0 +1,88 @@
> +\section{I2C Adapter Device}\label{sec:Device Types / I2C Adapter Device}
> +
> +virtio-i2c is a virtual I2C adapter device. It provides a way to flexibly
> +organize and manage I2C slave devices from the guest. By attaching ACPI
> +I2C slave nodes to the virtual I2C adapter device, the guest can
> +communicate with them without changing or adding extra drivers for these
> +slave I2C devices. 
> +
> +\subsection{Device ID}\label{sec:Device Types / I2C Adapter Device / Device ID}
> +34
> +
> +\subsection{Virtqueues}\label{sec:Device Types / I2C Adapter Device / Virtqueues}
> +
> +\begin{description}
> +\item[0] requestq
> +\end{description}
> +
> +\subsection{Feature bits}\label{sec:Device Types / I2C Adapter Device / Feature bits}
> +
> +None currently defined.
> +
> +\subsection{Device configuration layout}\label{sec:Device Types / I2C Adapter Device / Device configuration layout}
> +
> +None currently defined.
> +
> +\subsection{Device Initialization}\label{sec:Device Types / I2C Adapter Device / Device Initialization}
> +
> +\begin{enumerate}
> +\item The virtqueue is initialized.
> +\end{enumerate}
> +
> +\subsection{Device Operation}\label{sec:Device Types / I2C Adapter Device / Device Operation}
> +
> +The driver queues requests to the virtqueues, and they are used by the
> +device. The request is the representation of one segment of an I2C
> +transaction. Each request is of form:
> +
> +\begin{lstlisting}
> +struct virtio_i2c_req {
> +        le16 addr;
> +        le16 flags;
> +        le16 len;
> +        u8 buf[];
> +        u8 status;
> +};
> +\end{lstlisting}
> +
> +The \field{addr} is the address of the I2C slave device.
> +
> +The first bit of \field{flags} indicates whether it is a read or write request.
> +It means a read request if the first bit of \field{flags} is set, otherwise
> +it is a write request. The rest bits of \field{flags} are reserved.
>


So how does one creates a multi-segment transaction then?


> +The \field{len} is the number of data bytes in the \field{buf} being read from or
> +written to the I2C slave address.
> +
> +The \field{buf} of the request contains one segment of an I2C transaction.
> +If the first bit of \field{flags} is '1', the \field{buf} is written by the
> +device and it contains one segment of an I2C transaction being read from the
> +device. If the first bit of \field{flags} is '0', the \field{buf} is written
> +by the driver and it contains one segment of an I2C transaction being written
> +to the the device.
> +
> +The final \field{status} byte is written by the device: either VIRTIO_I2C_MSG_OK
> +for success or VIRTIO_I2C_MSG_ERR for error.
> +
> +\begin{lstlisting}
> +#define VIRTIO_I2C_MSG_OK     0
> +#define VIRTIO_I2C_MSG_ERR    1
> +\end{lstlisting}
> +
> +\drivernormative{\subsubsection}{Device Operation}{Device Types / I2C Adapter Device / Device Operation}
> +
> +A driver MUST set \field{addr}, \field{flags} and \field{len} before sending
> +the request.
> +
> +A driver MUST place one segment of an I2C transaction into \field{buf} if the
> +first bit of \field{flags} is '0'.
> +
> +A driver MUST NOT use \field{addr}, \field{flags}, \field{len} and \field{buf}
> +if the final \field{status} returned from the device is VIRTIO_I2C_MSG_ERR.
> +
> +\devicenormative{\subsubsection}{Device Operation}{Device Types / I2C Adapter Device / Device Operation}
> +
> +A device MUST NOT change the value of \field{addr}, \field{flags} and \field{len}.
> +
> +A device MUST place one segment of an I2C transaction into \field{buf} if the first
> +bit of \field{flags} is '1'.
> -- 
> 2.7.4


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/