virtio-i2c is a virtual I2C adapter device. It provides a way
to ?exibly 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.
+
+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