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

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

[Jie Deng]

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  | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 110 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..b631211
--- /dev/null
+++ b/virtio-i2c.tex
@@ -0,0 +1,85 @@
+\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 (not necessarily in order). 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 mesns 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.
+
+The \field{len} of the request indicates the length of the I2C message.
+
+The \field{buf} of the request contains the I2C message. If the first bit of
+\field{flags} is '1', the \field{buf} is written by the device and it contains
+the message read from the device. If the first bit of \field{flags} is '0', the
+\field{buf} is written by the driver and it contains the message 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 message.
+
+A driver MUST place the I2C message into \field{buf} if the first bit of
+\field{flags} is '0'.
+
+A driver MUST NOT use the message if the final \field{status} return 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 the message into \field{buf} if the first bit of \field{flags}
+is '1'.
\ No newline at end of file
-- 
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/

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

[Michael S. Tsirkin]

On Tue, Sep 22, 2020 at 10:49:02AM +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  | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  3 files changed, 110 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..b631211
> --- /dev/null
> +++ b/virtio-i2c.tex
> @@ -0,0 +1,85 @@
> +\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 (not necessarily in order). 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 mesns a read request if the first bit of \field{flags} is set, otherwise


means

> +it is a write request. The rest bits of \field{flags} are reserved.

Do we really need this flg? write request is just a big write followed by 1
byte read, read request is write read 1 byte read.



> +The \field{len} of the request indicates the length of the I2C message.
> +
> +The \field{buf} of the request contains the I2C message. If the first bit of
> +\field{flags} is '1', the \field{buf} is written by the device and it contains
> +the message read from the device. If the first bit of \field{flags} is '0', the
> +\field{buf} is written by the driver and it contains the message 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 message.
> +
> +A driver MUST place the I2C message into \field{buf} if the first bit of
> +\field{flags} is '0'.
> +
> +A driver MUST NOT use the message if the final \field{status}


What does "use the message" mean? What message?
> return from the

> +device is VIRTIO_I2C_MSG_ERR.

returned?

> +
> +\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 the message into \field{buf} if the first bit of \field{flags}
> +is '1'.


again, what the message?


> \ No newline at end of file
> -- 
> 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/


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/

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

[Jie Deng]

On 2020/10/21 20:08, Michael S. Tsirkin wrote:

> On Tue, Sep 22, 2020 at 10:49:02AM +0800, Jie Deng wrote:
>
> +
> +The first bit of \field{flags} indicates whether it is a read or write request.
> +It mesns a read request if the first bit of \field{flags} is set, otherwise
>
> means

I will fix this typo. Thank you.

>> +it is a write request. The rest bits of \field{flags} are reserved.
> Do we really need this flg? write request is just a big write followed by 1
> byte read, read request is write read 1 byte read.
The "addr", "flags", "len" and "buf" are all from Linux kernel structure 
"struct i2c_msg".
This design may help the backend driver to extract "struct i2c_msg" from
"struct virtio_i2c_req" easily.

The "flags" has many bits been defined in I2C. It is no mere an 
identification for
read/write. Although, currently, we only used the first bit, we may use 
other bits
for feature extension in the future. So I think it's necessary to keep it.

Thanks.


>
>
>> +The \field{len} of the request indicates the length of the I2C message.
>> +
>> +The \field{buf} of the request contains the I2C message. If the first bit of
>> +\field{flags} is '1', the \field{buf} is written by the device and it contains
>> +the message read from the device. If the first bit of \field{flags} is '0', the
>> +\field{buf} is written by the driver and it contains the message 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 message.
>> +
>> +A driver MUST place the I2C message into \field{buf} if the first bit of
>> +\field{flags} is '0'.
>> +
>> +A driver MUST NOT use the message if the final \field{status}
>
> What does "use the message" mean? What message?
I mean  the "addr", "flags" , "len " and "buf " in "virtio_i2c_req" here.
I will describe it more precisely in v2.

Thanks.

>> return from the
>> +device is VIRTIO_I2C_MSG_ERR.
> returned?

I will fix this typo. Thank you.


>> +
>> +\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 the message into \field{buf} if the first bit of \field{flags}
>> +is '1'.
>
> again, what the message?
>
Here is the I2C message. I will describe it more precisely in v2.

Thanks.


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/

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

[Michael S. Tsirkin]

On Thu, Oct 22, 2020 at 03:45:16PM +0800, Jie Deng wrote:
> On 2020/10/21 20:08, Michael S. Tsirkin wrote:
> 
> > On Tue, Sep 22, 2020 at 10:49:02AM +0800, Jie Deng wrote:
> > 
> > +
> > +The first bit of \field{flags} indicates whether it is a read or write request.
> > +It mesns a read request if the first bit of \field{flags} is set, otherwise
> > 
> > means
> 
> I will fix this typo. Thank you.
> 
> > > +it is a write request. The rest bits of \field{flags} are reserved.
> > Do we really need this flg? write request is just a big write followed by 1
> > byte read, read request is write read 1 byte read.
> The "addr", "flags", "len" and "buf" are all from Linux kernel structure
> "struct i2c_msg".
> This design may help the backend driver to extract "struct i2c_msg" from
> "struct virtio_i2c_req" easily.
> 
> The "flags" has many bits been defined in I2C. It is no mere an
> identification for
> read/write. Although, currently, we only used the first bit, we may use
> other bits
> for feature extension in the future. So I think it's necessary to keep it.
> 
> Thanks.

It's ok to reserve 2 bytes for now.




> 
> > 
> > 
> > > +The \field{len} of the request indicates the length of the I2C message.
> > > +
> > > +The \field{buf} of the request contains the I2C message. If the first bit of
> > > +\field{flags} is '1', the \field{buf} is written by the device and it contains
> > > +the message read from the device. If the first bit of \field{flags} is '0', the
> > > +\field{buf} is written by the driver and it contains the message 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 message.
> > > +
> > > +A driver MUST place the I2C message into \field{buf} if the first bit of
> > > +\field{flags} is '0'.
> > > +
> > > +A driver MUST NOT use the message if the final \field{status}
> > 
> > What does "use the message" mean? What message?
> I mean  the "addr", "flags" , "len " and "buf " in "virtio_i2c_req" here.
> I will describe it more precisely in v2.
> 
> Thanks.


Right. For example it is very unclear what does the
buffer map to.  a single i2c_msg? then do we not need STOP
etc etc ... ?


> > > return from the
> > > +device is VIRTIO_I2C_MSG_ERR.
> > returned?
> 
> I will fix this typo. Thank you.
> 
> 
> > > +
> > > +\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 the message into \field{buf} if the first bit of \field{flags}
> > > +is '1'.
> > 
> > again, what the message?
> > 
> Here is the I2C message. I will describe it more precisely in v2.
> 
> Thanks.


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/

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

[Jie Deng]

[-- Attachment #1: Type: text/plain, Size: 578 bytes --]

On 2020/10/22 20:15, Michael S. Tsirkin wrote:

> On Thu, Oct 22, 2020 at 03:45:16PM +0800, Jie Deng wrote:
>
> does "use the message" mean? What message?
>> I mean  the "addr", "flags" , "len " and "buf " in "virtio_i2c_req" here.
>> I will describe it more precisely in v2.
>>
>> Thanks.
>
> Right. For example it is very unclear what does the
> buffer map to.  a single i2c_msg? then do we not need STOP
> etc etc ... ?
>
Yes. virtio_i2c_req is just a wrap of i2c_msg.
I have updated the v2 hoping that the description will look more precise.

Thanks.


[-- Attachment #2: Type: text/html, Size: 1310 bytes --]