Re: [virtio-dev][PATCH 2/2] virtio-spi: add the device specification

[Harald Mommer <harald.mommer@opensynergy.com>]

Hello,

I've some comments on the draft specification. Looks promising but 
pointers in structures used to exchange information between driver and 
device are a no go. And there are some things which need to be (better) 
defined and clarified to implement an SPI device or driver from this 
draft specification.

On 17.04.23 16:03, Haixu Cui wrote:
> virtio-spi is a virtual SPI master and it allows a guset to operate and
> use the physical SPI master controlled by the host.
> ---
>   device-types/spi/description.tex        | 155 ++++++++++++++++++++++++
>   device-types/spi/device-conformance.tex |   7 ++
>   device-types/spi/driver-conformance.tex |   7 ++
>   3 files changed, 169 insertions(+)
>   create mode 100644 device-types/spi/description.tex
>   create mode 100644 device-types/spi/device-conformance.tex
>   create mode 100644 device-types/spi/driver-conformance.tex
>
> diff --git a/device-types/spi/description.tex b/device-types/spi/description.tex
> new file mode 100644
> index 0000000..a68e5f4
> --- /dev/null
> +++ b/device-types/spi/description.tex
> @@ -0,0 +1,155 @@
> +\section{SPI Master Device}\label{sec:Device Types / SPI Master Device}
> +
> +virtio-spi is a virtual SPI(Serial Peripheral Interface) master and it allows a
> +guest to operate and use the physical SPI master devices controlled by the host.
> +By attaching the host SPI controlled nodes to the virtual SPI master device, the
> +guest can communicate with them without changing or adding extra drivers for these
> +controlled SPI devices.
> +
> +In a typical host and guest architecture with Virtio SPI, Virtio SPI driver
> +is the front-end and exists in the guest kernel, Virtio SPI device acts as
> +the back-end and exists in the host. And VirtQueue is used for communication
> +between the front-end and the back-end.
> +
> +\subsection{Device ID}\label{sec:Device Types / SPI Master Device / Device ID}
> +45
> +
> +\subsection{Virtqueues}\label{sec:Device Types / SPI Master Device / Virtqueues}
> +
> +\begin{description}
> +\item[0] requestq
> +\end{description}
> +
> +\subsection{Feature bits}\label{sec:Device Types / SPI Master Device / Feature bits}
> +
> +None.
> +
> +\subsection{Device configuration layout}\label{sec:Device Types / SPI Master Device / Device configuration layout}
> +
> +All fields of this configuration are always available and read-only for the Virtio SPI driver.
> +
> +\begin{lstlisting}
> +struct virtio_spi_config {
> +    u32 bus_num;
> +    u32 chip_select_max_number;
> +};
> +\end{lstlisting}
> +
> +\begin{description}
> +\item[\field{bus_num}] is the physical spi master assigned to guset, and this is SOC-specific.
> +
> +\item[\field{chip_select_max_number}] is the number of chipselect the physical spi master supported.
> +\end{description}
> +
> +\subsection{Device Initialization}\label{sec:Device Types / SPI Master Device / Device Initialization}
> +
> +\begin{itemize}
> +\item The Virtio SPI driver configures and initializes the virtqueue.
> +
> +\item The Virtio SPI driver allocates and registers the virtual SPI master.
> +\end{itemize}
> +
> +\subsection{Device Operation}\label{sec:Device Types / SPI Master Device / Device Operation}
> +
> +\subsubsection{Device Operation: Request Queue}\label{sec:Device Types / SPI Master Device / Device Operation: Request Queue}
> +
> +The Virtio SPI driver queues requests to the virtqueue, and they are used by the
> +Virtio SPI device. Each request represents one SPI transfer and it is of the form:
> +
> +\begin{lstlisting}
> +struct virtio_spi_transfer_head {
> +    u32 mode;
> +    u32 freq;
> +    u32 word_delay;
> +    u8 slave_id;
> +    u8 bits_per_word;
> +    u8 cs_change;
> +    u8 reserved;
> +};

Hunting for some length information of tx_buf and rx_buf.

The driver provides the device readable and the device writable buffers.

So for half duplex write the length of tx_buf is the total length of the 
device readable descriptors - transfer head.

So for half duplex read the length of rx_buf is the total length of the 
device writable descriptors - transfer end.

if (total size of device readable descriptors == transfer head) => half 
duplex read

if (total size of device writable descriptors == transfer end) => half 
duplex write

otherwise it's full duplex

The "mode" field seems to be foreseen to determine "half duplex read", 
"half duplex write" or "full duplex". So the "mode" field is redundant 
information but this is really no issue.

I think I got it now how to get the length information for all the 
possible transfers without having any buffer length information in the 
transfer head. Tricky. Should really be elaborated in the specification, 
took me hours to get it and I'm not convinced yet it's that. Initially I 
thought the length information in the transfer head was simply missing 
but most probably it is indeed not because the information can be 
obtained in a different way from the virtqueues.

What to send for half duplex read? Is it don't care or 0xFF, 0x00 or 
something else which needs to be determinable? In the past I had to use 
SPI always full duplex on the small controllers I worked with so the 
question did not arise.

> +\end{lstlisting}
> +
> +\begin{lstlisting}
> +struct virtio_spi_transfer_end {
> +    u8 status; // Device=>Driver, device writable
> +};
> +\end{lstlisting}
> +
> +\begin{lstlisting}
> +struct virtio_spi_req {
> +    struct virtio_spi_transfer_head head; // Driver=>Device, device readable
> +    u8 *rx_buf; // Device=>Driver, device writable
> +    u8 *tx_buf; // Driver=>Device, device readable

Won't work 1:

"2.7.4.2 Driver Requirements: Message Framing
The driver MUST place any deviceÂ-writable descriptor elements after any 
deviceÂ-readable descriptor eleÂments."

=> First tx_buf and afterwards rx_buf. The elements need to be exchanged.

Won't work 2:

You cannot send pointers around in virtio. A pointer in the virtual 
address space of the device has no meaning in the virtual address space 
of the driver and vice versa. And what's a pointer? Is it 32 bit or 64 
bit? Casting to le64 won't help also. You need to have buffers of 
sufficient size instead of the pointers in the structure.

Compare this with struct virtio_i2c_req from the I2C chapter:

u8 buf[]Í

This is a buffer of sufficient size, not a pointer. As there is only 1 
device writable descriptor (struct virtio_i2c_in_hdr) we have there also 
no issue finding the status. Different here. We have tx_buf in front of 
the status and we don't know how long this is.

The buf[] length in I2C may be obtained by the device from the bytes 
written by the driver to the virtqueue (need to check again) so no issue 
for I2C as they seem not to have a dedicated length information in their 
message structures.

=>

u8 tx_buf[];

u8 rx_buf[];

> +    struct virtio_spi_transfer_end end;
> +};
> +\end{lstlisting}
> +
> +The \field{mode} defines the SPI transfer mode.

Difficult. Your enumeration below looks like a enumeration in the text 
and not like the definition of values. Better is to clearly define the 
values.

#define VIRTIO_SPI_MODE_XXX 1 /* or whatever */

#define VIRTIO_SPI_MODE_YYY 2 /* or whatever */

#define VIRTIO_SPI_MODE_ZZZ 3 /* or whatever */

> +
> +The \field{freq} defines the SPI transfer speed in Hz.
> +
> +The \field{word_delay} defines how long to wait between words within one SPI transfer,
> +in ns unit.
> +
> +The \field{slave_id} defines the chipselect index the SPI transfer used.
> +
> +The \field{bits_per_word} defines the number of bits in each SPI transfer word.
> +
> +The \field{cs_change} defines whether to deselect device before starting the next SPI transfer.
Most probably 0 is "don't deselect" and 1 is "deselect". Better define 
this clearly.
> +
> +The \field{rx_buf} is the receive buffer, used to hold the data received from the external device.
> +
> +The \field{tx_buf} is the transmit buffer, used to hold the data sent to the external device.
> +
> +The final \field{status} byte of the request is written by the Virtio SPI device: either
> +VIRTIO_SPI_MSG_OK for success or VIRTIO_SPI_MSG_ERR for error.
> +
> +\begin{lstlisting}
> +#define VIRTIO_SPI_MSG_OK     0
> +#define VIRTIO_SPI_MSG_ERR    1
> +\end{lstlisting}
> +
> +\subsubsection{Device Operation: Operation Status}\label{sec:Device Types / SPI Master Device / Device Operation: Operation Status}
> +
> +Members in \field{struct virtio_spi_transfer_head} are determined by the Virtio SPI driver, while \field{status}
> +in \field{struct virtio_spi_transfer_end} is determined by the processing of the Virtio SPI device.
"determined" = "written" or "filled"? Below you use "filled". Beware 
English is not my native language but at least in the translation to 
German "determined" becomes ambiguous so it may be indeed ambiguous.
> +
> +Virtio SPI supports three transfer types: 1) half-duplex read, 2) half-duplex write, 3) full-duplex read and write.
> +For half-duplex read transfer, \field{rx_buf} is filled by the Virtio SPI device and consumed by the Virtio SPI driver.
> +For half-duplex write transfer, \field{tx_buf} is filled by the Virtio SPI driver and consumed by the Virtio SPI device.
> +And for full-duplex read and write transfer, both \field{tx_buf} and \field{rx_buf} are used.
The "transfer mode" above has become a "transfer type" here.
> +
> +\drivernormative{\subsubsection}{Device Operation}{Device Types / SPI Master Device / Device Operation}
> +
> +The Virtio SPI driver MUST send messages on the requestq virtqueue.
> +
> +The \field{struct spi_transfer_head} MUST be filled by the Virtio SPI driver
> +and MUST be readable for the Virtio SPI device.
> +
> +The \field{struct spi_transfer_end} MUST be filled by the Virtio SPI device
> +and MUST be writable for the Virtio SPI device.

Isn't it obvious that the parts which MUST be written by side X must be 
readable by side Y? Nothing wrong here.

However this here is under the headline of "drivernormative" and I see a 
"MUST be filled by the Virtio SPI device" which is a requirement for the 
device.

> +
> +For half-duplex read, the Virtio SPI driver MUST send \field{struct spi_transfer_head},
> +\field{rx_buf} and \field{struct spi_transfer_end} to the SPI Virtio Device in order.
> +
> +For half-duplex write, the Virtio SPI driver MUST send \field{struct spi_transfer_head},
> +\field{tx_buf} and \field{struct spi_transfer_end} to the SPI Virtio Device in order.
> +
> +For full-duplex read and write, the Virtio SPI driver MUST send \field{struct spi_transfer_head},
> +\field{rx_buf}, \field{tx_buf} and \field{struct spi_transfer_end} to the SPI Virtio Device in order.
> +
> +For half-duplex write or full-duplex read and write, the Virtio SPI driver MUST not use
> +\field{rx_buf} if the final \field{status} returned from the Virtio SPI device is VIRTIO_SPI_MSG_ERR.
> +
> +\devicenormative{\subsubsection}{Device Operation}{Device Types / SPI Master Device / Device Operation}
> +
> +The Virtio SPI device MUST set all the fields of the \field{struct virtio_spi_config} on
> +receiving a configuration request from the Virtio SPI driver.
> +
> +The Virtio SPI device MUST set the \field{struct spi_transfer_end} before sending it
> +back to the Virtio SPI driver.
> +
> +The Virtio SPI device MUST be able to identify the transfer type according to the
> +received VirtQueue descriptors.

Having difficulties. "Type" is "Mode"? By reading the "mode" field? This 
would be the trivial meaning of the sentence.

Or is there a more deep meaning of "according to the received VirtQueue 
descriptors"?

If the length information of tx_buf and rx_buf are indeed not missing in 
the transfer head structure it would be probably good to elaborate on 
obtaining the length information here.

> +
> +The Virtio SPI device MUST NOT change the value of the send buffer if transfer type
> +is half-duplex write or full-duplex read and write.
> diff --git a/device-types/spi/device-conformance.tex b/device-types/spi/device-conformance.tex
> new file mode 100644
> index 0000000..b9dea91
> --- /dev/null
> +++ b/device-types/spi/device-conformance.tex
> @@ -0,0 +1,7 @@
> +\conformance{\subsection}{SPI Master Device Conformance}\label{sec:Conformance / Device Conformance / SPI Master Device Conformance}
> +
> +A SPI Master device MUST conform to the following normative statements:
> +
> +\begin{itemize}
> +\item \ref{devicenormative:Device Types / SPI Master Device / Device Operation}
> +\end{itemize}
> diff --git a/device-types/spi/driver-conformance.tex b/device-types/spi/driver-conformance.tex
> new file mode 100644
> index 0000000..719b42e
> --- /dev/null
> +++ b/device-types/spi/driver-conformance.tex
> @@ -0,0 +1,7 @@
> +\conformance{\subsection}{SPI Master Driver Conformance}\label{sec:Conformance / Driver Conformance / SPI Master Driver Conformance}
> +
> +A SPI Master driver MUST conform to the following normative statements:
> +
> +\begin{itemize}
> +\item \ref{drivernormative:Device Types / SPI Master Device / Device Operation}
> +\end{itemize}

Regards
Harald Mommer