The I2C protocol allows zero-length requests with no data, like the SMBus Quick command, where the command is inferred based on the read/write flag itself.
In order to allow such a request, allocate another bit, VIRTIO_I2C_FLAGS_M_RD(1), in the flags to pass the request type, as read or write. This was earlier done using the read/write permission to the buffer itself.
Add a new feature flag for zero length requests and make it mandatory for it to be implemented, so we don't need to drag the old implementation around.
Fixes: https://github.com/oasis-tcs/virtio-spec/issues/112 Reviewed-by: Arnd Bergmann arnd@arndb.de Reviewed-by: Jie Deng jie.deng@intel.com Signed-off-by: Viresh Kumar viresh.kumar@linaro.org --- virtio-i2c.tex | 42 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 39 insertions(+), 3 deletions(-)
diff --git a/virtio-i2c.tex b/virtio-i2c.tex index 5d634aec6e7c..5d407cb9e7c2 100644 --- a/virtio-i2c.tex +++ b/virtio-i2c.tex @@ -17,7 +17,21 @@ \subsection{Virtqueues}\label{sec:Device Types / I2C Adapter Device / Virtqueues
\subsection{Feature bits}\label{sec:Device Types / I2C Adapter Device / Feature bits}
-None currently defined. +\begin{description} +\item[VIRTIO_I2C_F_ZERO_LENGTH_REQUEST (0)] The device supports zero-length I2C +request and \field{VIRTIO_I2C_FLAGS_M_RD} flag. It is mandatory to implement +this feature. +\end{description} + +\begin{note} +The \field{VIRTIO_I2C_FLAGS_M_RD} flag was not present in the initial +implementation of the specification and the direction of the transfer (read or +write) was inferred from the permissions (read-only or write-only) of the +buffer itself. There is no need of having backwards compatibility for the older +specification and so the \field{VIRTIO_I2C_FLAGS_FAIL_NEXT} feature is made +mandatory. The driver should abort negotiation with the device, if the device +doesn't offer this feature. +\end{note}
\subsection{Device configuration layout}\label{sec:Device Types / I2C Adapter Device / Device configuration layout}
@@ -83,13 +97,20 @@ \subsubsection{Device Operation: Request Queue}\label{sec:Device Types / I2C Ada and sets it on the other requests. If this bit is set and a device fails to process the current request, it needs to fail the next request instead of attempting to execute it. + +\item[VIRTIO_I2C_FLAGS_M_RD(1)] is used to mark the request as READ or WRITE. + If \field{VIRTIO_I2C_FLAGS_M_RD} bit is set in the \field{flags}, then the + request is called a read request. If \field{VIRTIO_I2C_FLAGS_M_RD} bit is + unset in the \field{flags}, then the request is called a write request. \end{description}
Other bits of \field{flags} are currently reserved as zero for future feature extensibility.
-The \field{buf} of the request contains one segment of an I2C transaction -being read from or written to the device. +The \field{buf} is optional and will not be present for a zero-length request, +like the SMBus "Quick" command. The \field{buf} contains one segment of an I2C +transaction being read from or written to the device, based on the value of the +\field{VIRTIO_I2C_FLAGS_M_RD} bit in the \field{flags} field.
The final \field{status} byte of the request is written by the device: either VIRTIO_I2C_MSG_OK for success or VIRTIO_I2C_MSG_ERR for error. @@ -124,13 +145,25 @@ \subsubsection{Device Operation: Operation Status}\label{sec:Device Types / I2C
\drivernormative{\subsubsection}{Device Operation}{Device Types / I2C Adapter Device / Device Operation}
+A driver MUST accept the \field{VIRTIO_I2C_F_ZERO_LENGTH_REQUEST} feature and +MUST abort negotiation with the device, if the device doesn't offer this +feature. + A driver MUST set \field{addr} and \field{flags} before sending the request.
A driver MUST set the reserved bits of \field{flags} to be zero.
+A driver MUST NOT send the \field{buf}, for a zero-length request. + A driver MUST NOT use \field{buf}, for a read request, if the final \field{status} returned from the device is VIRTIO_I2C_MSG_ERR.
+A driver MUST set the \field{VIRTIO_I2C_FLAGS_M_RD} flag for a read operation, +where the buffer is write-only for the device. + +A driver MUST NOT set the \field{VIRTIO_I2C_FLAGS_M_RD} flag for a write +operation, where the buffer is read-only for the device. + A driver MUST queue the requests in order if multiple requests are going to be sent at a time.
@@ -141,6 +174,9 @@ \subsubsection{Device Operation: Operation Status}\label{sec:Device Types / I2C
\devicenormative{\subsubsection}{Device Operation}{Device Types / I2C Adapter Device / Device Operation}
+A device MUST offer the \field{VIRTIO_I2C_F_ZERO_LENGTH_REQUEST} feature and +MUST reject any driver that doesn't negotiate this feature. + A device SHOULD keep consistent behaviors with the hardware as described in \hyperref[intro:I2C]{I2C}.