[virtio-dev] Re: [RFC PATCH v3 3/3] SPI: Add virtio SPI driver.
On 2/13/2024 9:53 PM, Harald Mommer wrote:
+static struct spi_board_info board_info = {
+ .modalias = "spi-virtio",
+};
Hi Harald,
Do you add "spi-virtio" in spidev_spi_ids in spidev.c when you
doing the tests, to probe spidev driver?
Thanks
-
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
[virtio-dev] Re: [RFC PATCH v3 3/3] SPI: Add virtio SPI driver.
On 2/13/2024 9:53 PM, Harald Mommer wrote:
From: Harald Mommer
This is the virtio SPI Linux kernel driver.
Signed-off-by: Harald Mommer
---
drivers/spi/Kconfig | 11 +
drivers/spi/Makefile | 1 +
drivers/spi/spi-virtio.c | 475 +++
3 files changed, 487 insertions(+)
create mode 100644 drivers/spi/spi-virtio.c
diff --git a/drivers/spi/Kconfig b/drivers/spi/Kconfig
index bc7021da2fe9..0b5cd4c1f06b 100644
--- a/drivers/spi/Kconfig
+++ b/drivers/spi/Kconfig
@@ -1125,6 +1125,17 @@ config SPI_UNIPHIER
If your SoC supports SCSSI, say Y here.
+config SPI_VIRTIO
+ tristate "Virtio SPI Controller"
+ depends on SPI_MASTER && VIRTIO
+ help
+ This enables the Virtio SPI driver.
+
+ Virtio SPI is an SPI driver for virtual machines using Virtio.
+
+ If your Linux is a virtual machine using Virtio, say Y here.
+ If unsure, say N.
+
config SPI_XCOMM
tristate "Analog Devices AD-FMCOMMS1-EBZ SPI-I2C-bridge driver"
depends on I2C
diff --git a/drivers/spi/Makefile b/drivers/spi/Makefile
index 4ff8d725ba5e..ff2243e44e00 100644
--- a/drivers/spi/Makefile
+++ b/drivers/spi/Makefile
@@ -146,6 +146,7 @@ spi-thunderx-objs := spi-cavium.o
spi-cavium-thunderx.o
obj-$(CONFIG_SPI_THUNDERX)+= spi-thunderx.o
obj-$(CONFIG_SPI_TOPCLIFF_PCH)+= spi-topcliff-pch.o
obj-$(CONFIG_SPI_UNIPHIER)+= spi-uniphier.o
+obj-$(CONFIG_SPI_VIRTIO) += spi-virtio.o
obj-$(CONFIG_SPI_XCOMM) += spi-xcomm.o
obj-$(CONFIG_SPI_XILINX) += spi-xilinx.o
obj-$(CONFIG_SPI_XLP) += spi-xlp.o
diff --git a/drivers/spi/spi-virtio.c b/drivers/spi/spi-virtio.c
new file mode 100644
index ..700cb36e815f
--- /dev/null
+++ b/drivers/spi/spi-virtio.c
@@ -0,0 +1,475 @@
+// SPDX-License-Identifier: GPL-2.0-only
+/*
+ * SPI bus driver for the Virtio SPI controller
+ * Copyright (C) 2023 OpenSynergy GmbH
+ */
+
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+
+/* virtio_spi private data structure */
+struct virtio_spi_priv {
+ /* The virtio device we're associated with */
+ struct virtio_device *vdev;
+ /* Pointer to the virtqueue */
+ struct virtqueue *vq;
+ /* Copy of config space mode_func_supported */
+ u32 mode_func_supported;
+ /* Copy of config space max_freq_hz */
+ u32 max_freq_hz;
+};
+
+struct virtio_spi_req {
+ struct completion completion;
+ struct spi_transfer_head transfer_head cacheline_aligned;
+ const uint8_t *tx_buf cacheline_aligned;
+ uint8_t *rx_buf cacheline_aligned;
+ struct spi_transfer_result result cacheline_aligned;
+};
+
Hello Harald,
Do you add the "spi-virtio" in spidev_spi_ids in spidev.c when you
doing the tests? And any other method to expose the spidev interface to
userspace?
+static struct spi_board_info board_info = {
+ .modalias = "spi-virtio",
+};
+
+static void virtio_spi_msg_done(struct virtqueue *vq)
+{
+ struct virtio_spi_req *req;
+ unsigned int len;
+
+ while ((req = virtqueue_get_buf(vq, &len)))
+ complete(&req->completion);
+}
+
+/*
+ * See also
+ * https://lore.kernel.org/all/6171c1c3-55ba-4f74-ae60-764820cf1...@quicinc.com
+ */
For setting delay function, looks good to me. And I will look into
other parts.
Thanks
+static int virtio_spi_set_delays(struct spi_transfer_head *th,
+struct spi_device *spi,
+struct spi_transfer *xfer)
+{
+ int cs_setup;
+ int cs_word_delay_xfer;
+ int cs_word_delay_spi;
+ int delay;
+ int cs_hold;
+ int cs_inactive;
+ int cs_change_delay;
+
+ cs_setup = spi_delay_to_ns(&spi->cs_setup, xfer);
+ if (cs_setup < 0) {
+ dev_warn(&spi->dev, "Cannot convert cs_setup\n");
+ return cs_setup;
+ }
+ th->cs_setup_ns = cpu_to_le32((u32)cs_setup);
+
+ cs_word_delay_xfer = spi_delay_to_ns(&xfer->word_delay, xfer);
+ if (cs_word_delay_xfer < 0) {
+ dev_warn(&spi->dev, "Cannot convert cs_word_delay_xfer\n");
+ return cs_word_delay_xfer;
+ }
+ cs_word_delay_spi = spi_delay_to_ns(&spi->word_delay, xfer);
+ if (cs_word_delay_spi < 0) {
+ dev_warn(&spi->dev, "Cannot convert cs_word_delay_spi\n");
+ return cs_word_delay_spi;
+ }
+ if (cs_word_delay_spi > cs_word_delay_xfer)
+ th->word_delay_ns = cpu_to_le32((u32)cs_word_delay_spi);
+ else
+ th->word_delay_ns = cpu_to_le32((u32)cs_word_delay_xfer);
+
+ delay = spi_delay_to_ns(&xfer->delay, xfer);
+ if (delay < 0) {
+ dev_war
[virtio-dev] Re: [RFC PATCH v2 3/3] SPI: Add virtio SPI driver (V10 draft specification).
On 1/4/2024 9:01 PM, Harald Mommer wrote:
+static int virtio_spi_one_transfer(struct virtio_spi_req *spi_req,
+ struct spi_controller *ctrl,
+ struct spi_message *msg,
+ struct spi_transfer *xfer)
+{
+ struct virtio_spi_priv *priv = spi_controller_get_devdata(ctrl);
+ struct device *dev = &priv->vdev->dev;
+ struct spi_device *spi = msg->spi;
+ struct spi_transfer_head *th;
+ struct scatterlist sg_out_head, sg_out_payload;
+ struct scatterlist sg_in_result, sg_in_payload;
+ struct scatterlist *sgs[4];
+ unsigned int outcnt = 0u;
+ unsigned int incnt = 0u;
+ int ret;
+
+ th = &spi_req->transfer_head;
+
+ /* Fill struct spi_transfer_head */
+ th->chip_select_id = spi_get_chipselect(spi, 0);
+ th->bits_per_word = spi->bits_per_word;
+ /*
+* Got comment: "The virtio spec for cs_change is*not* what the Linux
+* cs_change field does, this will not do the right thing."
+* TODO: Understand/discuss this, still unclear what may be wrong here
+*/
+ th->cs_change = xfer->cs_change;
+ th->tx_nbits = xfer->tx_nbits;
+ th->rx_nbits = xfer->rx_nbits;
+ th->reserved[0] = 0;
+ th->reserved[1] = 0;
+ th->reserved[2] = 0;
+
+ BUILD_BUG_ON(VIRTIO_SPI_CPHA != SPI_CPHA);
+ BUILD_BUG_ON(VIRTIO_SPI_CPOL != SPI_CPOL);
+ BUILD_BUG_ON(VIRTIO_SPI_CS_HIGH != SPI_CS_HIGH);
+ BUILD_BUG_ON(VIRTIO_SPI_MODE_LSB_FIRST != SPI_LSB_FIRST);
+
+ th->mode = cpu_to_le32(spi->mode & (SPI_LSB_FIRST | SPI_CS_HIGH |
+ SPI_CPOL | SPI_CPHA));
+ if ((spi->mode & SPI_LOOP) != 0)
+ th->mode |= cpu_to_le32(VIRTIO_SPI_MODE_LOOP);
+
+ th->freq = cpu_to_le32(xfer->speed_hz);
+
+ ret = spi_delay_to_ns(&xfer->word_delay, xfer);
+ if (ret < 0) {
+ dev_warn(dev, "Cannot convert word_delay\n");
+ goto msg_done;
+ }
+ th->word_delay_ns = cpu_to_le32((u32)ret);
+
+ ret = spi_delay_to_ns(&xfer->delay, xfer);
+ if (ret < 0) {
+ dev_warn(dev, "Cannot convert delay\n");
+ goto msg_done;
+ }
+ th->cs_setup_ns = cpu_to_le32((u32)ret);
+ th->cs_delay_hold_ns = cpu_to_le32((u32)ret);
+
+ /* This is the "off" time when CS has to be deasserted for a moment */
+ ret = spi_delay_to_ns(&xfer->cs_change_delay, xfer);
+ if (ret < 0) {
+ dev_warn(dev, "Cannot convert cs_change_delay\n");
+ goto msg_done;
+ }
+ th->cs_change_delay_inactive_ns = cpu_to_le32((u32)ret);
Hi Harald,
spi_device structure has three cs timing members, which will also
affect the cs timing.
struct spi_device {
...
struct spi_delaycs_setup;
struct spi_delaycs_hold;
struct spi_delaycs_inactive;
...
}
These three values should also be passed to the backend, for the
controller to control cs lines.
spi_device->cs_setup is the delay before cs asserted,
spi_device->cs_hold with spi_transfer->delay work before cs deasserted,
and spi_device->cs_inactive with spi_transfer->cs_change_delay take
effect at the stage after cs deasserted.
Here is the diagram
. . ... . . . . .
Delay + A + + B ++ C + D + E + F + A +
. . ... . . . . .
___. . ... . .___.___. .
CS# |___.__...___.___| . |___._
. . ... . . . . .
. . ... . . . . .
SCLK__.___.___NNN_NNN__.___.___.___.___.___.___NNN___
NOTE: 1st transfer has two words, the delay betweent these two words are
'B' in the diagram.
A => struct spi_device -> cs_setup
B => max{struct spi_transfer -> word_delay,
struct spi_device -> word_delay}
Note: spi_device and spi_transfer both have word_delay, Linux
choose the bigger one, refer to _spi_xfer_word_delay_update
function
C => struct spi_transfer -> delay
D => struct spi_device -> cs_hold
E => struct spi_device -> cs_inactive
F => struct spi_transfer -> cs_change_delay
So the corresponding relationship:
A <===> cs_setup_ns (after CS asserted)
B <===> word_delay_ns (no matter with CS)
C+D <===> cs_delay_hold_ns (before CS deasserted)
E+F <===> cs_change_delay_inactive_ns (after CS deasserted, these two
values also recommend in Linux driver to be added up)
Best Regards
Haixu
+
+ /* Set buffers */
+ spi_req->tx_buf = xfer->tx_buf;
+ spi_req->rx_buf = xfer->rx_buf;
+
+ /* Prepare sending of virtio message */
+ init_completion(&spi_req->completion);
+
+ sg_init_one(&sg_out_head, &spi_req->transfer_head,
+ sizeof(struct spi_transfer_head));
+
[virtio-dev][PATCH V10 2/2] virtio-spi: add the device specification
The Virtio SPI (Serial Peripheral Interface) device is a virtual
SPI controller that allows the driver to operate and use the SPI
controller under the control of the host.
This patch adds the specification for virtio-spi.
Signed-off-by: Haixu Cui
Reviewed-by: Viresh Kumar
---
conformance.tex | 12 +-
content.tex | 1 +
device-types/spi/description.tex| 286
device-types/spi/device-conformance.tex | 7 +
device-types/spi/driver-conformance.tex | 7 +
5 files changed, 309 insertions(+), 4 deletions(-)
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/conformance.tex b/conformance.tex
index dc00e84..af8aca0 100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -32,8 +32,9 @@ \section{Conformance Targets}\label{sec:Conformance /
Conformance Targets}
\ref{sec:Conformance / Driver Conformance / Memory Driver Conformance},
\ref{sec:Conformance / Driver Conformance / I2C Adapter Driver Conformance},
\ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance},
-\ref{sec:Conformance / Driver Conformance / GPIO Driver Conformance} or
-\ref{sec:Conformance / Driver Conformance / PMEM Driver Conformance}.
+\ref{sec:Conformance / Driver Conformance / GPIO Driver Conformance},
+\ref{sec:Conformance / Driver Conformance / PMEM Driver Conformance} or
+\ref{sec:Conformance / Driver Conformance / SPI Controller Driver Conformance}.
\item Clause \ref{sec:Conformance / Legacy Interface: Transitional Device
and Transitional Driver Conformance}.
\end{itemize}
@@ -59,8 +60,9 @@ \section{Conformance Targets}\label{sec:Conformance /
Conformance Targets}
\ref{sec:Conformance / Device Conformance / Memory Device Conformance},
\ref{sec:Conformance / Device Conformance / I2C Adapter Device Conformance},
\ref{sec:Conformance / Device Conformance / SCMI Device Conformance},
-\ref{sec:Conformance / Device Conformance / GPIO Device Conformance} or
-\ref{sec:Conformance / Device Conformance / PMEM Device Conformance}.
+\ref{sec:Conformance / Device Conformance / GPIO Device Conformance},
+\ref{sec:Conformance / Device Conformance / PMEM Device Conformance} or
+\ref{sec:Conformance / Device Conformance / SPI Controller Device Conformance}.
\item Clause \ref{sec:Conformance / Legacy Interface: Transitional Device
and Transitional Driver Conformance}.
\end{itemize}
@@ -152,6 +154,7 @@ \section{Conformance Targets}\label{sec:Conformance /
Conformance Targets}
\input{device-types/scmi/driver-conformance.tex}
\input{device-types/gpio/driver-conformance.tex}
\input{device-types/pmem/driver-conformance.tex}
+\input{device-types/spi/driver-conformance.tex}
\conformance{\section}{Device Conformance}\label{sec:Conformance / Device
Conformance}
@@ -238,6 +241,7 @@ \section{Conformance Targets}\label{sec:Conformance /
Conformance Targets}
\input{device-types/scmi/device-conformance.tex}
\input{device-types/gpio/device-conformance.tex}
\input{device-types/pmem/device-conformance.tex}
+\input{device-types/spi/device-conformance.tex}
\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
diff --git a/content.tex b/content.tex
index 1c608eb..84bc68f 100644
--- a/content.tex
+++ b/content.tex
@@ -767,6 +767,7 @@ \chapter{Device Types}\label{sec:Device Types}
\input{device-types/scmi/description.tex}
\input{device-types/gpio/description.tex}
\input{device-types/pmem/description.tex}
+\input{device-types/spi/description.tex}
\chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
diff --git a/device-types/spi/description.tex b/device-types/spi/description.tex
new file mode 100644
index 000..84fd2c9
--- /dev/null
+++ b/device-types/spi/description.tex
@@ -0,0 +1,286 @@
+\section{SPI Controller Device}\label{sec:Device Types / SPI Controller Device}
+
+The Virtio SPI (Serial Peripheral Interface) device is a virtual SPI
controller that
+allows the driver to operate and use the SPI controller under the control of
the host,
+either a physical SPI controller, or an emulated one.
+
+The Virtio SPI device has a single virtqueue. SPI transfer requests are placed
into
+the virtqueue by the driver, and are serviced by the device.
+
+In a typical host and guest architecture with the Virtio SPI device, the
Virtio SPI driver
+is the front-end running in the guest, and the Virtio SPI device is the
back-end
+in the host.
+
+\subsection{Device ID}\label{sec:Device Types / SPI Controller Device / Device
ID}
+45
+
+\subsection{Virtqueues}\label{sec:Device Types / SPI Controller Device /
Virtqueues}
+
+\begin{description}
+\item[0] requestq
+\end{description
[virtio-dev][PATCH V10 1/2] content: Rename SPI master to SPI controller
SPI master is an outdated term and should use SPI controller.
Signed-off-by: Haixu Cui
Reviewed-by: Viresh Kumar
---
content.tex | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/content.tex b/content.tex
index 0a62dce..1c608eb 100644
--- a/content.tex
+++ b/content.tex
@@ -737,7 +737,7 @@ \chapter{Device Types}\label{sec:Device Types}
\hline
44 & ISM device \\
\hline
-45 & SPI master \\
+45 & SPI controller \\
\hline
\end{tabular}
--
2.17.1
-
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
[virtio-dev][PATCH V10 0/2] virtio-spi: add virtual SPI controller
The Virtio SPI (Serial Peripheral Interface) device is a virtual SPI controller that allows the driver to operate and use the SPI controller under the control of the host, either a physical SPI controller, or an emulated one. changelog: = v9->v10: - add explanation of CPHA and CPOL - update the statement of bits_per_word_mask when it is set as 0 - add spi device and driver conformance in conformance.tex v8->v9: - add explanation of bits_per_word_mask in config space v7->v8: - change device to host v6->v7: - fix the format problems and syntax problems v5->v6: - use driver/device instead guest/host - add the definition of some terminologies - use controller instead of master throughout the spec - add buffer length validation for full-duplex transfer v4->v5: - use controller instead of master - fix indentation issue - extend the config space to expose the backend supported features - add another result value to indicate parameter error - add device and driver requirement about parameter checking v3->v4: - fix the spell errors - bus_num is not SOC-specific, remove it - add driver requirement to deal with the situation that the cs delay parameters are not 0 but the backend doesn't support cs timing setting v2->v3 - remove unnecessary statements and driver implementation details - add the parameters about cs timing delay and transfer delay - use "le32" instead of "u32" - swap the rx_buf and tx_buf in the request format - add the parameters about transfer bit width v1->v2: - explain SPI when it is firstly used - update the ambiguous expression of virtqueue v0->v1: - add definition of abbreviation SPI - remove the ID Haixu Cui (2): content: Rename SPI master to SPI controller virtio-spi: add the device specification conformance.tex | 12 +- content.tex | 3 +- device-types/spi/description.tex| 286 device-types/spi/device-conformance.tex | 7 + device-types/spi/driver-conformance.tex | 7 + 5 files changed, 310 insertions(+), 5 deletions(-) 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 -- 2.17.1 - To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
[virtio-dev][PATCH V10 2/2] virtio-spi: add the device specification
The Virtio SPI (Serial Peripheral Interface) device is a virtual
SPI controller that allows the driver to operate and use the SPI
controller under the control of the host.
This patch adds the specification for virtio-spi.
Signed-off-by: Haixu Cui
Reviewed-by: Viresh Kumar
---
conformance.tex | 12 +-
content.tex | 1 +
device-types/spi/description.tex| 286
device-types/spi/device-conformance.tex | 7 +
device-types/spi/driver-conformance.tex | 7 +
5 files changed, 309 insertions(+), 4 deletions(-)
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/conformance.tex b/conformance.tex
index dc00e84..af8aca0 100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -32,8 +32,9 @@ \section{Conformance Targets}\label{sec:Conformance /
Conformance Targets}
\ref{sec:Conformance / Driver Conformance / Memory Driver Conformance},
\ref{sec:Conformance / Driver Conformance / I2C Adapter Driver Conformance},
\ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance},
-\ref{sec:Conformance / Driver Conformance / GPIO Driver Conformance} or
-\ref{sec:Conformance / Driver Conformance / PMEM Driver Conformance}.
+\ref{sec:Conformance / Driver Conformance / GPIO Driver Conformance},
+\ref{sec:Conformance / Driver Conformance / PMEM Driver Conformance} or
+\ref{sec:Conformance / Driver Conformance / SPI Controller Driver Conformance}.
\item Clause \ref{sec:Conformance / Legacy Interface: Transitional Device
and Transitional Driver Conformance}.
\end{itemize}
@@ -59,8 +60,9 @@ \section{Conformance Targets}\label{sec:Conformance /
Conformance Targets}
\ref{sec:Conformance / Device Conformance / Memory Device Conformance},
\ref{sec:Conformance / Device Conformance / I2C Adapter Device Conformance},
\ref{sec:Conformance / Device Conformance / SCMI Device Conformance},
-\ref{sec:Conformance / Device Conformance / GPIO Device Conformance} or
-\ref{sec:Conformance / Device Conformance / PMEM Device Conformance}.
+\ref{sec:Conformance / Device Conformance / GPIO Device Conformance},
+\ref{sec:Conformance / Device Conformance / PMEM Device Conformance} or
+\ref{sec:Conformance / Device Conformance / SPI Controller Device Conformance}.
\item Clause \ref{sec:Conformance / Legacy Interface: Transitional Device
and Transitional Driver Conformance}.
\end{itemize}
@@ -152,6 +154,7 @@ \section{Conformance Targets}\label{sec:Conformance /
Conformance Targets}
\input{device-types/scmi/driver-conformance.tex}
\input{device-types/gpio/driver-conformance.tex}
\input{device-types/pmem/driver-conformance.tex}
+\input{device-types/spi/driver-conformance.tex}
\conformance{\section}{Device Conformance}\label{sec:Conformance / Device
Conformance}
@@ -238,6 +241,7 @@ \section{Conformance Targets}\label{sec:Conformance /
Conformance Targets}
\input{device-types/scmi/device-conformance.tex}
\input{device-types/gpio/device-conformance.tex}
\input{device-types/pmem/device-conformance.tex}
+\input{device-types/spi/device-conformance.tex}
\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
diff --git a/content.tex b/content.tex
index 1c608eb..84bc68f 100644
--- a/content.tex
+++ b/content.tex
@@ -767,6 +767,7 @@ \chapter{Device Types}\label{sec:Device Types}
\input{device-types/scmi/description.tex}
\input{device-types/gpio/description.tex}
\input{device-types/pmem/description.tex}
+\input{device-types/spi/description.tex}
\chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
diff --git a/device-types/spi/description.tex b/device-types/spi/description.tex
new file mode 100644
index 000..84fd2c9
--- /dev/null
+++ b/device-types/spi/description.tex
@@ -0,0 +1,286 @@
+\section{SPI Controller Device}\label{sec:Device Types / SPI Controller Device}
+
+The Virtio SPI (Serial Peripheral Interface) device is a virtual SPI
controller that
+allows the driver to operate and use the SPI controller under the control of
the host,
+either a physical SPI controller, or an emulated one.
+
+The Virtio SPI device has a single virtqueue. SPI transfer requests are placed
into
+the virtqueue by the driver, and are serviced by the device.
+
+In a typical host and guest architecture with the Virtio SPI device, the
Virtio SPI driver
+is the front-end running in the guest, and the Virtio SPI device is the
back-end
+in the host.
+
+\subsection{Device ID}\label{sec:Device Types / SPI Controller Device / Device
ID}
+45
+
+\subsection{Virtqueues}\label{sec:Device Types / SPI Controller Device /
Virtqueues}
+
+\begin{description}
+\item[0] requestq
+\end{description
[virtio-dev][PATCH V10 0/2] virtio-spi: add virtual SPI controller
The Virtio SPI (Serial Peripheral Interface) device is a virtual SPI controller that allows the driver to operate and use the SPI controller under the control of the host, either a physical SPI controller, or an emulated one. changelog: = v9->v10: - add explanation of CPHA and CPOL - update the statement of bits_per_word_mask when it is set as 0 v8->v9: - add explanation of bits_per_word_mask in config space v7->v8: - change device to host v6->v7: - fix the format problems and syntax problems v5->v6: - use driver/device instead guest/host - add the definition of some terminologies - use controller instead of master throughout the spec - add buffer length validation for full-duplex transfer v4->v5: - use controller instead of master - fix indentation issue - extend the config space to expose the backend supported features - add another result value to indicate parameter error - add device and driver requirement about parameter checking v3->v4: - fix the spell errors - bus_num is not SOC-specific, remove it - add driver requirement to deal with the situation that the cs delay parameters are not 0 but the backend doesn't support cs timing setting v2->v3 - remove unnecessary statements and driver implementation details - add the parameters about cs timing delay and transfer delay - use "le32" instead of "u32" - swap the rx_buf and tx_buf in the request format - add the parameters about transfer bit width v1->v2: - explain SPI when it is firstly used - update the ambiguous expression of virtqueue v0->v1: - add definition of abbreviation SPI - remove the ID Haixu Cui (2): content: Rename SPI master to SPI controller virtio-spi: add the device specification conformance.tex | 12 +- content.tex | 3 +- device-types/spi/description.tex| 286 device-types/spi/device-conformance.tex | 7 + device-types/spi/driver-conformance.tex | 7 + 5 files changed, 310 insertions(+), 5 deletions(-) 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 -- 2.17.1 - To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
[virtio-dev][PATCH V10 1/2] content: Rename SPI master to SPI controller
SPI master is an outdated term and should use SPI controller.
Signed-off-by: Haixu Cui
Reviewed-by: Viresh Kumar
---
content.tex | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/content.tex b/content.tex
index 0a62dce..1c608eb 100644
--- a/content.tex
+++ b/content.tex
@@ -737,7 +737,7 @@ \chapter{Device Types}\label{sec:Device Types}
\hline
44 & ISM device \\
\hline
-45 & SPI master \\
+45 & SPI controller \\
\hline
\end{tabular}
--
2.17.1
-
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
Re: [virtio-dev][PATCH V9 2/2] virtio-spi: add the device specification
Hello Harald,
On 12/22/2023 10:32 PM, Harald Mommer wrote:
Hello Haixu,
On 22.12.23 03:28, Haixu Cui wrote:
Hello Harald,
On 12/21/2023 7:25 PM, Harald Mommer wrote:
Hello,
On 12.12.23 04:33, Haixu Cui wrote:
+\field{bits_per_word_mask} is a mask indicating which values of
bits_per_word are supported.
+If bit n of \field{bits_per_word_mask} is set, the bits_per_word
with value (n+1) is supported.
+If all bits are not set, bits_per_word can be any value from 1 to 32.
"If all bits are not set" is not easy to understand as it means "if
no bit is set".
You can of course specify the value 0 this way to make code more
complicated.
To make code simple, 0 would be not given this special meaning. To
allow any value between 1 and 32 solely the value 0x would be
allowed. Which is already possible now without this additional
sentence for 0. Simply checking whether the respective bit is set in
the mask and done without having to add senseless additional code to
handle the special case that the mask is 0.
Giving 0 the same meaning as 0x brings nothing except confusion.
Here I refer to the __spi_validate_bits_per_word in drivers/spi/spi.c,
if bits_per_word_mask of spi controller is 0, no check will be done
for bits_per_word parameter.
Above is just the Linux mechanism, I agree with you, 0 and 0x
have the same meaning will cause confusion in this spec. I prefer
treating 0 as an invalid value because the backend must support at
least one bits_per_word value.
How about updating as:
For \field{bits_per_word_mask}, 0 is invalid because at least one
bits_per_word value should be supported.
Thanks & Regards
Haixu Cui
Interesting. I know that I had already a comment on this previously. And
also now. But sometimes I'm wrong. And here probably in both cases but
at least with my last comment.
* @bits_per_word_mask: A mask indicating which values of bits_per_word
are
* supported by the driver. Bit n indicates that a bits_per_word n+1 is
* suported. If set, the SPI core will reject any transfer with an
* unsupported bits_per_word. If not set, this value is simply ignored,
* and it's up to the individual driver to perform any validation.
Tried to find out why this is so in Linux. The function
__spi_validate_bits_per_word() was introduced by commit 63ab645f4d8b.
The member variable bits_per_word_mask in struct spi_master was already
introduced by 543bb255a198. The new variable was introduced in a way so
that if not set the behavior would not change for existing SPI drivers
not (yet) setting the field. At least I deduce that looking into the
commits. Made a lot of sense to introduce bits_per_word_mask in commit
543bb255a198 in Linux this way to make a change without causing other
changes everywhere. The virtio SPI specification is new, no need to be
backwards compatible here so there is no need to have 0 there as "don't
check" value. So your proposal to make 0 the invalid value is a good
one. So I thought.
On the other hand: The function __spi_validate_bits_per_word() does not
check for anything if bits_per_word_mask is 0. With 0 it does not check
for bits_per_word > 32 and it does not check for bits_per_word being a
power of 2. It never checks for bits_per_word > 0 but this is a
different issue.
1.) Now I'm looking into a data sheet from Freescale
https://www.manualslib.com/manual/1376296/Freescale-Semiconductor-Mk22fn256vdc12.html?page=1053
and see that the chip can use any frame sizes from 4 to 32. Means also
frame sizes which are not a power of 2. Nothing I've seen before but it
exists. So the value 0 is indeed needed to allow for those values.
The chip can only support 4 to 32 bits, so with the 32 bit restriction
in the V9 draft we would be fine.
2.)
https://community.nxp.com/t5/S32K/How-to-send-receive-64bit-or-longer-message-using-SPI/m-p/1476343#M15986
There are Bits/frame of 8, 10, 24, 32, 40, 64 mentioned in the example.
Not only that some of those are no power of 2 and cannot be represented
in this bit mask not having 0 but we have also 64 bit frame size. Means
restriction to 32 bits has also to fall to support something like this.
I looked further and found a data sheet from NXP in the internet which
should not be there. Maximum frame size for this chip is everything
between 8 bits and 4096-bits with some values in between excluded. As
bits_per_word is an u8 in Linux and in the draft spec something so
strange like this could not be supported by virtio spi nor in Linux.
=> The normal case for the majority of people is 8, 16 and maybe also 32
bit SPI.
=> The strange case is non power of 2 values which cannot be represented
in the mask not allowing 0. The V9 draft spec is perfect for this.
=> Another strange case is big frame sizes > 32 bit.
The sentence in draft V7 (on which I moaned, sorry for this
Re: [virtio-dev][PATCH V9 2/2] virtio-spi: add the device specification
On 12/22/2023 8:21 PM, Cornelia Huck wrote:
On Tue, Dec 12 2023, Haixu Cui wrote:
The Virtio SPI (Serial Peripheral Interface) device is a virtual
SPI controller that allows the driver to operate and use the SPI
controller under the control of the host.
This patch adds the specification for virtio-spi.
Signed-off-by: Haixu Cui
Reviewed-by: Viresh Kumar
---
device-types/spi/description.tex| 281
device-types/spi/device-conformance.tex | 7 +
device-types/spi/driver-conformance.tex | 7 +
3 files changed, 295 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
Oh, and I just noticed that you also need to include
{device,driver}-conformance.tex in conformance.tex.
I will add the device and driver in conformance.tex in patch 2.
Thanks
Haixu Cui
-
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
[virtio-dev] Re: [virtio-comment] Re: [virtio-dev][PATCH V9 2/2] virtio-spi: add the device specification
On 12/21/2023 5:54 PM, Cornelia Huck wrote:
On Thu, Dec 21 2023, Haixu Cui wrote:
Hi Cornelia,
On 12/21/2023 4:44 PM, Cornelia Huck wrote:
On Thu, Dec 21 2023, Haixu Cui wrote:
Please move inclusion of this new file into content.tex here, instead of
including a not-yet-existing file in the previous patch.
(...)
Sorry, I don't quite understand here. Maybe I should not add the
following line in content.tex, is that so?
\input{device-types/spi/description.tex}
No, please add this line; but do so in this patch instead of the
previous one that only changes the wording.
I am not clear where to put this line? In the commit message or in the
main text, e.g. at the start of the description.tex? As follows:
diff --git a/device-types/spi/description.tex
b/device-types/spi/description.tex
new file mode 100644
index 000..b76258c
--- /dev/null
+++ b/device-types/spi/description.tex
@@ -0,0 +1,281 @@
+\input{device-types/spi/description.tex}
+\section{SPI Controller Device}\label{sec:Device Types / SPI Controller
Device}
+
...
Ah no, the inclusion is of course in the right place where you put it in
context.tex; the *patch hunk* should be moved from patch 1 to patch 2,
that's all. Hope that's more clear now :)
Hello Cornelia,
Oh I think I get it. The patch 1 should be split into two. Changing the
wording is still in patch 1 and the line
"\input{device-types/spi/description.tex}" should be move to patch 2.
Thank you very much for your detailed explanations, I will do so in next
patch.
Best Regards
Haixu Cui
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-subscr...@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscr...@lists.oasis-open.org
List help: virtio-comment-h...@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/
-
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
Re: [virtio-dev][PATCH V9 2/2] virtio-spi: add the device specification
Hello Harald,
On 12/21/2023 7:25 PM, Harald Mommer wrote:
Hello,
On 12.12.23 04:33, Haixu Cui wrote:
+\field{bits_per_word_mask} is a mask indicating which values of
bits_per_word are supported.
+If bit n of \field{bits_per_word_mask} is set, the bits_per_word with
value (n+1) is supported.
+If all bits are not set, bits_per_word can be any value from 1 to 32.
"If all bits are not set" is not easy to understand as it means "if no
bit is set".
You can of course specify the value 0 this way to make code more
complicated.
To make code simple, 0 would be not given this special meaning. To allow
any value between 1 and 32 solely the value 0x would be allowed.
Which is already possible now without this additional sentence for 0.
Simply checking whether the respective bit is set in the mask and done
without having to add senseless additional code to handle the special
case that the mask is 0.
Giving 0 the same meaning as 0x brings nothing except confusion.
Here I refer to the __spi_validate_bits_per_word in drivers/spi/spi.c,
if bits_per_word_mask of spi controller is 0, no check will be done for
bits_per_word parameter.
Above is just the Linux mechanism, I agree with you, 0 and 0x
have the same meaning will cause confusion in this spec. I prefer
treating 0 as an invalid value because the backend must support at least
one bits_per_word value.
How about updating as:
For \field{bits_per_word_mask}, 0 is invalid because at least one
bits_per_word value should be supported.
Thanks & Regards
Haixu Cui
-
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
Re: [virtio-dev][PATCH V9 2/2] virtio-spi: add the device specification
Hi Cornelia,
On 12/21/2023 4:44 PM, Cornelia Huck wrote:
On Thu, Dec 21 2023, Haixu Cui wrote:
Hi Cornelia,
Much appreciated for your comments and please refer to my response.
On 12/18/2023 7:04 PM, Cornelia Huck wrote:
On Tue, Dec 12 2023, Haixu Cui wrote:
[BTW: A changelog would be useful, either in the patch or in the cover
letter.]
Sure, I summarize the major changes between these versions and will add
in next patch:
changelog:
v8->v9:
- add explanation of bits_per_word_mask in config space
v7->v8:
- change device to host
v6->v7:
- fix the format problem, syntax problem
v5->v6:
- use driver/device instead guest/host
- add the definition of some terminologies
- use controller instead of master throughout the spec
- add buffer length validation for full-duplex transfer
v4->v5:
- use controller instead of master
- fix indentation issue
- extend the config space to expose the backend supported features
- add another result value to indicate parameter error
- add device and driver requirement about parameter checkig
v3->v4:
- fix the spell error
- bus_num is not SOC-specific, remove it
- add driver requirement to deal with the situation that the cs delay
parameters are not 0 but the backend doesn't support cs timing setting
v2->v3
- remove unnecessary statements and driver implimentation details
- add the parameters about cs timing delay and transfer delay
- use "le32" instead of "u32"
- swap the rx_buf and tx_buf in the request format
- add the parameters about transfer bit width
v1->v2:
- explain SPI when it is firstly used
- update the ambiguous expression of virtqueue
v0->v1:
- add definition of abbreviation SPI
- remove the ID
Thanks. Might be best to add this in the cover letter.
In next patch I will add it in cover letter.
---
The Virtio SPI (Serial Peripheral Interface) device is a virtual
SPI controller that allows the driver to operate and use the SPI
controller under the control of the host.
This patch adds the specification for virtio-spi.
Signed-off-by: Haixu Cui
Reviewed-by: Viresh Kumar
---
device-types/spi/description.tex| 281
device-types/spi/device-conformance.tex | 7 +
device-types/spi/driver-conformance.tex | 7 +
3 files changed, 295 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
Please move inclusion of this new file into content.tex here, instead of
including a not-yet-existing file in the previous patch.
(...)
Sorry, I don't quite understand here. Maybe I should not add the
following line in content.tex, is that so?
\input{device-types/spi/description.tex}
No, please add this line; but do so in this patch instead of the
previous one that only changes the wording.
I am not clear where to put this line? In the commit message or in the
main text, e.g. at the start of the description.tex? As follows:
diff --git a/device-types/spi/description.tex
b/device-types/spi/description.tex
new file mode 100644
index 000..b76258c
--- /dev/null
+++ b/device-types/spi/description.tex
@@ -0,0 +1,281 @@
+\input{device-types/spi/description.tex}
+\section{SPI Controller Device}\label{sec:Device Types / SPI Controller
Device}
+
...
+\field{mode_func_supported} indicates whether the following features are
supported or not:
+bit 0-1: CPHA feature,
+0b00: invalid, must support as least one CPHA setting.
+0b01: supports CPHA=0 only;
+0b10: supports CPHA=1 only;
+0b11: supports CPHA=0 and CPHA=1;
+
+bit 2-3: CPOL feature,
+0b00: invalid, must support as least one CPOL setting.
+0b01: supports CPOL=0 only;
+0b10: supports CPOL=1 only;
+0b11: supports CPOL=0 and CPOL=1;
+
+bit 4: chipselect active high feature, 0 for unsupported and 1 for
supported,
+chipselect active low must always be supported.
+
+bit 5: LSB first feature, 0 for unsupported and 1 for supported, MSB
first must always be
+supported.
+
+bit 6: loopback mode feature, 0 for unsupported and 1 for supported,
normal mode
+must always be supported.
+
+Note: CPOL is clock polarity and CPHA is clock phase. If CPOL is 0, the clock
idles at the logical
+low voltage, otherwise it idles at the logical high voltage. CPHA determines
how data is outputted
+and sampled.
Shouldn't you also specify what CPHA==0 and CPHA==1 mean?
Yes, I will add the following explanation:
If CPHA is 0, the first bit is outputted immediately when chipselect is
active and subsequent bits are outputted on the clock edges when clock
s/when clock/when the clock/
transitions from active level to idle le
Re: [virtio-dev][PATCH V9 2/2] virtio-spi: add the device specification
Hi Cornelia,
Much appreciated for your comments and please refer to my response.
On 12/18/2023 7:04 PM, Cornelia Huck wrote:
On Tue, Dec 12 2023, Haixu Cui wrote:
[BTW: A changelog would be useful, either in the patch or in the cover
letter.]
Sure, I summarize the major changes between these versions and will add
in next patch:
changelog:
v8->v9:
- add explanation of bits_per_word_mask in config space
v7->v8:
- change device to host
v6->v7:
- fix the format problem, syntax problem
v5->v6:
- use driver/device instead guest/host
- add the definition of some terminologies
- use controller instead of master throughout the spec
- add buffer length validation for full-duplex transfer
v4->v5:
- use controller instead of master
- fix indentation issue
- extend the config space to expose the backend supported features
- add another result value to indicate parameter error
- add device and driver requirement about parameter checkig
v3->v4:
- fix the spell error
- bus_num is not SOC-specific, remove it
- add driver requirement to deal with the situation that the cs delay
parameters are not 0 but the backend doesn't support cs timing setting
v2->v3
- remove unnecessary statements and driver implimentation details
- add the parameters about cs timing delay and transfer delay
- use "le32" instead of "u32"
- swap the rx_buf and tx_buf in the request format
- add the parameters about transfer bit width
v1->v2:
- explain SPI when it is firstly used
- update the ambiguous expression of virtqueue
v0->v1:
- add definition of abbreviation SPI
- remove the ID
---
The Virtio SPI (Serial Peripheral Interface) device is a virtual
SPI controller that allows the driver to operate and use the SPI
controller under the control of the host.
This patch adds the specification for virtio-spi.
Signed-off-by: Haixu Cui
Reviewed-by: Viresh Kumar
---
device-types/spi/description.tex| 281
device-types/spi/device-conformance.tex | 7 +
device-types/spi/driver-conformance.tex | 7 +
3 files changed, 295 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
Please move inclusion of this new file into content.tex here, instead of
including a not-yet-existing file in the previous patch.
(...)
Sorry, I don't quite understand here. Maybe I should not add the
following line in content.tex, is that so?
\input{device-types/spi/description.tex}
+\field{mode_func_supported} indicates whether the following features are
supported or not:
+bit 0-1: CPHA feature,
+0b00: invalid, must support as least one CPHA setting.
+0b01: supports CPHA=0 only;
+0b10: supports CPHA=1 only;
+0b11: supports CPHA=0 and CPHA=1;
+
+bit 2-3: CPOL feature,
+0b00: invalid, must support as least one CPOL setting.
+0b01: supports CPOL=0 only;
+0b10: supports CPOL=1 only;
+0b11: supports CPOL=0 and CPOL=1;
+
+bit 4: chipselect active high feature, 0 for unsupported and 1 for
supported,
+chipselect active low must always be supported.
+
+bit 5: LSB first feature, 0 for unsupported and 1 for supported, MSB
first must always be
+supported.
+
+bit 6: loopback mode feature, 0 for unsupported and 1 for supported,
normal mode
+must always be supported.
+
+Note: CPOL is clock polarity and CPHA is clock phase. If CPOL is 0, the clock
idles at the logical
+low voltage, otherwise it idles at the logical high voltage. CPHA determines
how data is outputted
+and sampled.
Shouldn't you also specify what CPHA==0 and CPHA==1 mean?
Yes, I will add the following explanation:
If CPHA is 0, the first bit is outputted immediately when chipselect is
active and subsequent bits are outputted on the clock edges when clock
transitions from active level to idle level. Data is sampled on the
clock edges when clock transitions from idle level to active level.
If CPHA is 1, the first bit is outputted on the fist clock edge after
chipselect is active, subsequent bits are outputted on the clock edges
when clock transitions from idle level to active level. Data is sampled
on the clock edges when clock transitions from active level to idle level.
(...)
+VIRTIO_SPI_TRANS_ERR indicates a transfer error, which means that the
parameters are all
+valid but the trasnfer process failed.
s/trasnfer/transfer/
OK will update the spell mistake
LGTM otherwise. Does anybody else have comments?
Best Regards
Haixu Cui
-
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
Re: [virtio-dev][PATCH V9 0/2] virtio-spi: add virtual SPI controller
Hi Cornelia, In patch V9, all comments have been fixed. Could you please help to review the new patch. And if there are no other comments, can you help to merge it as the initial version of virtio-spi. Thank you so much for your support. Thanks Haixu Cui On 12/12/2023 11:33 AM, Haixu Cui wrote: The Virtio SPI (Serial Peripheral Interface) device is a virtual SPI controller that allows the driver to operate and use the SPI controller under the control of the host, either a physical SPI controller, or an emulated one. Patch summary: patch 1 rename virtual SPI device name patch 2 add the specification for virtio-spi Haixu Cui (2): content: Rename SPI master to SPI controller virtio-spi: add the device specification content.tex | 3 +- device-types/spi/description.tex| 281 device-types/spi/device-conformance.tex | 7 + device-types/spi/driver-conformance.tex | 7 + 4 files changed, 297 insertions(+), 1 deletion(-) 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 - To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
[virtio-dev][PATCH V9 2/2] virtio-spi: add the device specification
The Virtio SPI (Serial Peripheral Interface) device is a virtual
SPI controller that allows the driver to operate and use the SPI
controller under the control of the host.
This patch adds the specification for virtio-spi.
Signed-off-by: Haixu Cui
Reviewed-by: Viresh Kumar
---
device-types/spi/description.tex| 281
device-types/spi/device-conformance.tex | 7 +
device-types/spi/driver-conformance.tex | 7 +
3 files changed, 295 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 000..b76258c
--- /dev/null
+++ b/device-types/spi/description.tex
@@ -0,0 +1,281 @@
+\section{SPI Controller Device}\label{sec:Device Types / SPI Controller Device}
+
+The Virtio SPI (Serial Peripheral Interface) device is a virtual SPI
controller that
+allows the driver to operate and use the SPI controller under the control of
the host,
+either a physical SPI controller, or an emulated one.
+
+The Virtio SPI device has a single virtqueue. SPI transfer requests are placed
into
+the virtqueue by the driver, and are serviced by the device.
+
+In a typical host and guest architecture with the Virtio SPI device, the
Virtio SPI driver
+is the front-end running in the guest, and the Virtio SPI device is the
back-end
+in the host.
+
+\subsection{Device ID}\label{sec:Device Types / SPI Controller Device / Device
ID}
+45
+
+\subsection{Virtqueues}\label{sec:Device Types / SPI Controller Device /
Virtqueues}
+
+\begin{description}
+\item[0] requestq
+\end{description}
+
+\subsection{Feature bits}\label{sec:Device Types / SPI Controller Device /
Feature bits}
+
+None
+
+\subsection{Device configuration layout}\label{sec:Device Types / SPI
Controller Device / Device configuration layout}
+
+All fields of this configuration are mandatory and read-only for the driver.
+The config space shows the features and settings supported by the device.
+
+\begin{lstlisting}
+struct virtio_spi_config {
+ u8 cs_max_number;
+ u8 cs_change_supported;
+ u8 tx_nbits_supported;
+ u8 rx_nbits_supported;
+ le32 bits_per_word_mask;
+ le32 mode_func_supported;
+ le32 max_freq_hz;
+ le32 max_word_delay_ns;
+ le32 max_cs_setup_ns;
+ le32 max_cs_hold_ns;
+ le32 max_cs_inactive_ns;
+};
+\end{lstlisting}
+
+\field{cs_max_number} is the maximum number of chipselect the device supports.
+
+Note: chipselect is an electrical signal, which is used to select the SPI
peripherals connected
+to the controller.
+
+\field{cs_change_supported} indicates if the device supports to toggle
chipselect
+after each transfer in one message:
+0: unsupported, chipselect will be kept in active state throughout the
message transaction;
+1: supported.
+
+Note: Message here contains a sequence of SPI transfers.
+
+\field{tx_nbits_supported} and \field{rx_nbits_supported} indicate the
different n-bit transfer
+modes supported by the device, for writing and reading respectively. SINGLE is
always supported.
+A set bit here indicates that the corresponding n-bit transfer is supported,
otherwise not:
+bit 0: DUAL;
+bit 1: QUAD;
+bit 2: OCTAL;
+other bits are reserved and must be set as 0 by the device.
+
+Note: The commonly used SPI n-bit transfer options are:
+\begin{itemize}
+\item SINGLE: 1-bit transfer
+\item DUAL: 2-bit transfer
+\item QUAD: 4-bit transfer
+\item OCTAL: 8-bit transfer
+\end{itemize}
+
+\field{bits_per_word_mask} is a mask indicating which values of bits_per_word
are supported.
+If bit n of \field{bits_per_word_mask} is set, the bits_per_word with value
(n+1) is supported.
+If all bits are not set, bits_per_word can be any value from 1 to 32.
+
+Note: bits_per_word corresponds to \field{bits_per_word} in \field{struct
virtio_spi_transfer_head}.
+
+\field{mode_func_supported} indicates whether the following features are
supported or not:
+bit 0-1: CPHA feature,
+0b00: invalid, must support as least one CPHA setting.
+0b01: supports CPHA=0 only;
+0b10: supports CPHA=1 only;
+0b11: supports CPHA=0 and CPHA=1;
+
+bit 2-3: CPOL feature,
+0b00: invalid, must support as least one CPOL setting.
+0b01: supports CPOL=0 only;
+0b10: supports CPOL=1 only;
+0b11: supports CPOL=0 and CPOL=1;
+
+bit 4: chipselect active high feature, 0 for unsupported and 1 for
supported,
+chipselect active low must always be supported.
+
+bit 5: LSB first feature, 0 for unsupported and 1 for supported, MSB
first must always be
+supported.
+
+bit 6: loopback mode feature, 0 for unsupported and 1 for supported,
normal mode
[virtio-dev][PATCH V9 1/2] content: Rename SPI master to SPI controller
SPI master is an outdated term and should use SPI controller.
Signed-off-by: Haixu Cui
Reviewed-by: Viresh Kumar
---
content.tex | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/content.tex b/content.tex
index 0a62dce..84bc68f 100644
--- a/content.tex
+++ b/content.tex
@@ -737,7 +737,7 @@ \chapter{Device Types}\label{sec:Device Types}
\hline
44 & ISM device \\
\hline
-45 & SPI master \\
+45 & SPI controller \\
\hline
\end{tabular}
@@ -767,6 +767,7 @@ \chapter{Device Types}\label{sec:Device Types}
\input{device-types/scmi/description.tex}
\input{device-types/gpio/description.tex}
\input{device-types/pmem/description.tex}
+\input{device-types/spi/description.tex}
\chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
--
2.17.1
-
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
[virtio-dev][PATCH V9 0/2] virtio-spi: add virtual SPI controller
The Virtio SPI (Serial Peripheral Interface) device is a virtual SPI controller that allows the driver to operate and use the SPI controller under the control of the host, either a physical SPI controller, or an emulated one. Patch summary: patch 1 rename virtual SPI device name patch 2 add the specification for virtio-spi Haixu Cui (2): content: Rename SPI master to SPI controller virtio-spi: add the device specification content.tex | 3 +- device-types/spi/description.tex| 281 device-types/spi/device-conformance.tex | 7 + device-types/spi/driver-conformance.tex | 7 + 4 files changed, 297 insertions(+), 1 deletion(-) 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 -- 2.17.1 - To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
Re: [virtio-dev][PATCH V8 2/2] virtio-spi: add the device specification
Hello Harald,
On 12/6/2023 12:18 AM, Harald Mommer wrote:
Hello,
updating my device and driver to V8 and having some comments now.
On 05.12.23 09:24, Haixu Cui wrote:
The Virtio SPI (Serial Peripheral Interface) device is a virtual
SPI controller that allows the driver to operate and use the SPI
controller under the control of the host.
This patch adds the specification for virtio-spi.
Signed-off-by: Haixu Cui
---
device-types/spi/description.tex | 280
device-types/spi/device-conformance.tex | 7 +
device-types/spi/driver-conformance.tex | 7 +
3 files changed, 294 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 000..ef686bd
--- /dev/null
+++ b/device-types/spi/description.tex
@@ -0,0 +1,280 @@
+\section{SPI Controller Device}\label{sec:Device Types / SPI
Controller Device}
+
+The Virtio SPI (Serial Peripheral Interface) device is a virtual SPI
controller that
+allows the driver to operate and use the SPI controller under the
control of the host,
+either a physical SPI controller, or an emulated one.
+
+The Virtio SPI device has a single virtqueue. SPI transfer requests
are placed into
+the virtqueue by the driver, and are serviced by the device.
+
+In a typical host and guest architecture with the Virtio SPI device,
the Virtio SPI driver
+is the front-end running in the guest, and the Virtio SPI device is
the back-end
+in the host.
+
+\subsection{Device ID}\label{sec:Device Types / SPI Controller Device
/ Device ID}
+45
+
+\subsection{Virtqueues}\label{sec:Device Types / SPI Controller
Device / Virtqueues}
+
+\begin{description}
+\item[0] requestq
+\end{description}
+
+\subsection{Feature bits}\label{sec:Device Types / SPI Controller
Device / Feature bits}
+
+None
+
+\subsection{Device configuration layout}\label{sec:Device Types / SPI
Controller Device / Device configuration layout}
+
+All fields of this configuration are mandatory and read-only for the
driver.
+The config space shows the features and settings supported by the
device.
+
+\begin{lstlisting}
+struct virtio_spi_config {
+ u8 cs_max_number;
+ u8 cs_change_supported;
+ u8 tx_nbits_supported;
+ u8 rx_nbits_supported;
+ le32 bits_per_word_mask;
+ le32 mode_func_supported;
+ le32 max_freq_hz;
+ le32 max_word_delay_ns;
+ le32 max_cs_setup_ns;
+ le32 max_cs_hold_ns;
+ le32 max_cs_inactive_ns;
+};
+\end{lstlisting}
+
+\field{cs_max_number} is the maximum number of chipselect the device
supports.
+
+Note: chipselect is an electrical signal, which is used to select the
SPI slaves connected
+to the controller.
+
+\field{cs_change_supported} indicates if the device supports to
toggle chipselect
+after each transfer in one message:
+ 0: unsupported, chipselect will be kept in active state
throughout the message transaction;
+ 1: supported.
+
+Note: Message here contains a sequence of SPI transfers.
+
+\field{tx_nbits_supported} and \field{rx_nbits_supported} indicate
the different n-bit transfer
+modes supported by the device, for writing and reading respectively.
SINGLE is always supported.
+A set bit here indicates that the corresponding n-bit transfer is
supported, otherwise not:
+ bit 0: DUAL;
+ bit 1: QUAD;
+ bit 2: OCTAL;
+ other bits are reserved and must be set as 0 by the device.
+
+Note: The commonly used SPI n-bit transfer options are:
+\begin{itemize}
+\item SINGLE: 1-bit transfer
+\item DUAL: 2-bit transfer
+\item QUAD: 4-bit transfer
+\item OCTAL: 8-bit transfer
+\end{itemize}
+
+\field{bits_per_word_mask} is a mask indicating which values of
bits_per_word are supported.
+If not set, there is no limitation for bits_per_word.
You have not given an exact coding here. Without this it's hard to
understand what is really specified and guesswork is needed.
1.) In Linux in spi.h there is a definition
/* Bitmask of supported bits_per_word for transfers */
u32 bits_per_word_mask;
#define SPI_BPW_MASK(bits) BIT((bits) - 1)
which brings us probably on the wrong path. Not sure any more. With this
coding you can have 1..32 as bits per word. 0 is not allowed for
bits_per_word_mask, at least it seems not to be used.
What you probably (guessing around) wanted to have is
#define VIRTIO_SPI_BPW_MASK(bits) ((u32)(1UL << (bits)))
without the - 1 as you specified 0 as "unlimited". In this case you can
define every value from 1 to 31. 32 and above is "unlimited" as for 32
and above (u32)(1UL << (bits)) == 0u.
I'm lost.
2.) "No limitation" is nonsense on a limited machine. Even the universe
is limited (at least the observable one), for sure your RAM is
Re: [virtio-dev][PATCH V8 1/2] content: Rename SPI master to SPI controller
Hello Harald,
On 12/5/2023 11:14 PM, Harald Mommer wrote:
Hello,
On 05.12.23 09:24, Haixu Cui wrote:
SPI master is an outdated term and should use SPI controller.
Signed-off-by: Haixu Cui
Reviewed-by: Viresh Kumar
---
content.tex | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/content.tex b/content.tex
index 0a62dce..1c608eb 100644
--- a/content.tex
+++ b/content.tex
@@ -737,7 +737,7 @@ \chapter{Device Types}\label{sec:Device Types}
\hline
44 & ISM device \\
\hline
-45 & SPI master \\
+45 & SPI controller \\
\hline
\end{tabular}
Please add somewhere behind
\input{device-types/pmem/description.tex}
the line
\input{device-types/spi/description.tex}
so that I get my PDF generated without having to add this line all the
time manually.
Sure I will.
Regards
Harald
Thanks & Regards
Haixu Cui
-
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
[virtio-dev][PATCH V8 2/2] virtio-spi: add the device specification
The Virtio SPI (Serial Peripheral Interface) device is a virtual
SPI controller that allows the driver to operate and use the SPI
controller under the control of the host.
This patch adds the specification for virtio-spi.
Signed-off-by: Haixu Cui
---
device-types/spi/description.tex| 280
device-types/spi/device-conformance.tex | 7 +
device-types/spi/driver-conformance.tex | 7 +
3 files changed, 294 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 000..ef686bd
--- /dev/null
+++ b/device-types/spi/description.tex
@@ -0,0 +1,280 @@
+\section{SPI Controller Device}\label{sec:Device Types / SPI Controller Device}
+
+The Virtio SPI (Serial Peripheral Interface) device is a virtual SPI
controller that
+allows the driver to operate and use the SPI controller under the control of
the host,
+either a physical SPI controller, or an emulated one.
+
+The Virtio SPI device has a single virtqueue. SPI transfer requests are placed
into
+the virtqueue by the driver, and are serviced by the device.
+
+In a typical host and guest architecture with the Virtio SPI device, the
Virtio SPI driver
+is the front-end running in the guest, and the Virtio SPI device is the
back-end
+in the host.
+
+\subsection{Device ID}\label{sec:Device Types / SPI Controller Device / Device
ID}
+45
+
+\subsection{Virtqueues}\label{sec:Device Types / SPI Controller Device /
Virtqueues}
+
+\begin{description}
+\item[0] requestq
+\end{description}
+
+\subsection{Feature bits}\label{sec:Device Types / SPI Controller Device /
Feature bits}
+
+None
+
+\subsection{Device configuration layout}\label{sec:Device Types / SPI
Controller Device / Device configuration layout}
+
+All fields of this configuration are mandatory and read-only for the driver.
+The config space shows the features and settings supported by the device.
+
+\begin{lstlisting}
+struct virtio_spi_config {
+ u8 cs_max_number;
+ u8 cs_change_supported;
+ u8 tx_nbits_supported;
+ u8 rx_nbits_supported;
+ le32 bits_per_word_mask;
+ le32 mode_func_supported;
+ le32 max_freq_hz;
+ le32 max_word_delay_ns;
+ le32 max_cs_setup_ns;
+ le32 max_cs_hold_ns;
+ le32 max_cs_inactive_ns;
+};
+\end{lstlisting}
+
+\field{cs_max_number} is the maximum number of chipselect the device supports.
+
+Note: chipselect is an electrical signal, which is used to select the SPI
slaves connected
+to the controller.
+
+\field{cs_change_supported} indicates if the device supports to toggle
chipselect
+after each transfer in one message:
+0: unsupported, chipselect will be kept in active state throughout the
message transaction;
+1: supported.
+
+Note: Message here contains a sequence of SPI transfers.
+
+\field{tx_nbits_supported} and \field{rx_nbits_supported} indicate the
different n-bit transfer
+modes supported by the device, for writing and reading respectively. SINGLE is
always supported.
+A set bit here indicates that the corresponding n-bit transfer is supported,
otherwise not:
+bit 0: DUAL;
+bit 1: QUAD;
+bit 2: OCTAL;
+other bits are reserved and must be set as 0 by the device.
+
+Note: The commonly used SPI n-bit transfer options are:
+\begin{itemize}
+\item SINGLE: 1-bit transfer
+\item DUAL: 2-bit transfer
+\item QUAD: 4-bit transfer
+\item OCTAL: 8-bit transfer
+\end{itemize}
+
+\field{bits_per_word_mask} is a mask indicating which values of bits_per_word
are supported.
+If not set, there is no limitation for bits_per_word.
+
+Note: bits_per_word corresponds to \field{bits_per_word} in \field{struct
virtio_spi_transfer_head}.
+
+\field{mode_func_supported} indicates whether the following features are
supported or not:
+bit 0-1: CPHA feature,
+0b00: supports CPHA=0 and CPHA=1;
+0b01: supports CPHA=0 only;
+0b10: supports CPHA=1 only;
+0b11: invalid, must support as least one CPHA setting.
+
+bit 2-3: CPOL feature,
+0b00: supports CPOL=0 and CPOL=1;
+0b01: supports CPOL=0 only;
+0b10: supports CPOL=1 only;
+0b11: invalid, must support as least one CPOL setting.
+
+bit 4: chipselect active high feature, 0 for unsupported and 1 for
supported,
+chipselect active low must always be supported.
+
+bit 5: LSB first feature, 0 for unsupported and 1 for supported, MSB
first must always be
+supported.
+
+bit 6: loopback mode feature, 0 for unsupported and 1 for supported,
normal mode
+must always be supported.
+
+Note: CPOL is clock polarity and CPHA is clock phase. If CPOL is 0, the clock
idles at the logical
+low voltage
[virtio-dev][PATCH V8 1/2] content: Rename SPI master to SPI controller
SPI master is an outdated term and should use SPI controller.
Signed-off-by: Haixu Cui
Reviewed-by: Viresh Kumar
---
content.tex | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/content.tex b/content.tex
index 0a62dce..1c608eb 100644
--- a/content.tex
+++ b/content.tex
@@ -737,7 +737,7 @@ \chapter{Device Types}\label{sec:Device Types}
\hline
44 & ISM device \\
\hline
-45 & SPI master \\
+45 & SPI controller \\
\hline
\end{tabular}
--
2.17.1
-
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
[virtio-dev][PATCH V8 0/2] virtio-spi: add virtual SPI controller
The Virtio SPI (Serial Peripheral Interface) device is a virtual SPI controller that allows the driver to operate and use the SPI controller under the control of the host, either a physical SPI controller, or an emulated one. Patch summary: patch 1 rename virtual SPI device name patch 2 add the specification for virtio-spi Haixu Cui (2): content: Rename SPI master to SPI controller virtio-spi: add the device specification content.tex | 2 +- device-types/spi/description.tex| 280 device-types/spi/device-conformance.tex | 7 + device-types/spi/driver-conformance.tex | 7 + 4 files changed, 295 insertions(+), 1 deletion(-) 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 -- 2.17.1 - To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
Re: [virtio-dev][PATCH V7 2/2] virtio-spi: add the device specification
Hi Viresh,
On 12/1/2023 4:37 PM, Viresh Kumar wrote:
On 01-12-23, 16:21, Haixu Cui wrote:
The Virtio SPI (Serial Peripheral Interface) device is a virtual
SPI controller that allows the driver to operate and use the SPI
controller under the control of the device.
This patch adds the specification for virtio-spi.
Signed-off-by: Haixu Cui
---
device-types/spi/description.tex| 280
device-types/spi/device-conformance.tex | 7 +
device-types/spi/driver-conformance.tex | 7 +
3 files changed, 294 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 000..7c81df5
--- /dev/null
+++ b/device-types/spi/description.tex
@@ -0,0 +1,280 @@
+\section{SPI Controller Device}\label{sec:Device Types / SPI Controller Device}
+
+The Virtio SPI (Serial Peripheral Interface) device is a virtual SPI
controller that
+allows the driver to operate and use the SPI controller under the control of
the device,
I feel the terminology here is still a bit confusing:
"the SPI controller under the control of the device"
The Virtio SPI controller is "the device" and it is not under its own control.
Exactly. I will update the statement as follows:
The Virtio SPI (Serial Peripheral Interface) device is a virtual SPI
controller that allows the driver to operate and use the SPI controller
under the control of the host, either a physical SPI controller, or an
emulated one.
As I suggested earlier, maybe this should be written as:
"the SPI controller under the control of the guest"
+either a physical SPI controller, or an emulated one.
I just skimmed through the rest this time. Thanks for your effort.
Thank you so much for your supports and helpful comments. Really appreciate.
Reviewed-by: Viresh Kumar
Best Regards
Haixu Cui
-
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
Re: [virtio-dev] [PATCH V6 2/2] virtio-spi: add the device specification
Hi Huck, On 12/1/2023 7:01 PM, Cornelia Huck wrote: On Fri, Dec 01 2023, Haixu Cui wrote: +Note: chipselect is an electrical signal controlled by the SPI controller, used to select the +SPI slaves connected to the controller. I wonder whether another term is now more commonly used... the Wikipedia article uses main/sub, is there a term that is usually used together with "controller"? In Wikipedia, "Historically, this arrangement has been called master/slave. But to avoid referencing slavery, alternative names discussed in § Alternative namings have been used." I am not quite sure if main/sub is widely used, but in latest Linux, still use master/slave but master is gradually replaced by "controller". So I think "controller" here does make sense. What is your suggestion? "controller" is fine, I'm just wondering if "slave" has started to be replaced with something else as well... if it hasn't, we probably need to stick with it to avoid confusing readers. slave is still being used, but it's better to be used along with "master". Here I prefer using "SPI peripherals" instead of "SPI slaves". Looking forward to your advice. Thank you so much. Best Regards Haixu Cui - To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
[virtio-dev][PATCH V7 2/2] virtio-spi: add the device specification
The Virtio SPI (Serial Peripheral Interface) device is a virtual
SPI controller that allows the driver to operate and use the SPI
controller under the control of the device.
This patch adds the specification for virtio-spi.
Signed-off-by: Haixu Cui
---
device-types/spi/description.tex| 280
device-types/spi/device-conformance.tex | 7 +
device-types/spi/driver-conformance.tex | 7 +
3 files changed, 294 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 000..7c81df5
--- /dev/null
+++ b/device-types/spi/description.tex
@@ -0,0 +1,280 @@
+\section{SPI Controller Device}\label{sec:Device Types / SPI Controller Device}
+
+The Virtio SPI (Serial Peripheral Interface) device is a virtual SPI
controller that
+allows the driver to operate and use the SPI controller under the control of
the device,
+either a physical SPI controller, or an emulated one.
+
+The Virtio SPI device has a single virtqueue. SPI transfer requests are placed
into
+the virtqueue by the driver, and are serviced by the device.
+
+In a typical host and guest architecture with the Virtio SPI device, the
Virtio SPI driver
+is the front-end running in the guest, and the Virtio SPI device is the
back-end
+in the host.
+
+\subsection{Device ID}\label{sec:Device Types / SPI Controller Device / Device
ID}
+45
+
+\subsection{Virtqueues}\label{sec:Device Types / SPI Controller Device /
Virtqueues}
+
+\begin{description}
+\item[0] requestq
+\end{description}
+
+\subsection{Feature bits}\label{sec:Device Types / SPI Controller Device /
Feature bits}
+
+None
+
+\subsection{Device configuration layout}\label{sec:Device Types / SPI
Controller Device / Device configuration layout}
+
+All fields of this configuration are mandatory and read-only for the driver.
+The config space shows the features and settings supported by the device.
+
+\begin{lstlisting}
+struct virtio_spi_config {
+ u8 cs_max_number;
+ u8 cs_change_supported;
+ u8 tx_nbits_supported;
+ u8 rx_nbits_supported;
+ le32 bits_per_word_mask;
+ le32 mode_func_supported;
+ le32 max_freq_hz;
+ le32 max_word_delay_ns;
+ le32 max_cs_setup_ns;
+ le32 max_cs_hold_ns;
+ le32 max_cs_inactive_ns;
+};
+\end{lstlisting}
+
+\field{cs_max_number} is the maximum number of chipselect the device supports.
+
+Note: chipselect is an electrical signal, which is used to select the SPI
slaves connected
+to the controller.
+
+\field{cs_change_supported} indicates if the device supports to toggle
chipselect
+after each transfer in one message:
+0: unsupported, chipselect will be kept in active state throughout the
message transaction;
+1: supported.
+
+Note: Message here contains a sequence of SPI transfers.
+
+\field{tx_nbits_supported} and \field{rx_nbits_supported} indicate the
different n-bit transfer
+modes supported by the device, for writing and reading respectively. SINGLE is
always supported.
+A set bit here indicates that the corresponding n-bit transfer is supported,
otherwise not:
+bit 0: DUAL;
+bit 1: QUAD;
+bit 2: OCTAL;
+other bits are reserved and must be set as 0 by the device.
+
+Note: The commonly used SPI n-bit transfer options are:
+\begin{itemize}
+\item SINGLE: 1-bit transfer
+\item DUAL: 2-bit transfer
+\item QUAD: 4-bit transfer
+\item OCTAL: 8-bit transfer
+\end{itemize}
+
+\field{bits_per_word_mask} is a mask indicating which values of bits_per_word
are supported.
+If not set, there is no limitation for bits_per_word.
+
+Note: bits_per_word corresponds to \field{bits_per_word} in \field{struct
virtio_spi_transfer_head}.
+
+\field{mode_func_supported} indicates whether the following features are
supported or not:
+bit 0-1: CPHA feature,
+0b00: supports CPHA=0 and CPHA=1;
+0b01: supports CPHA=0 only;
+0b10: supports CPHA=1 only;
+0b11: invalid, must support as least one CPHA setting.
+
+bit 2-3: CPOL feature,
+0b00: supports CPOL=0 and CPOL=1;
+0b01: supports CPOL=0 only;
+0b10: supports CPOL=1 only;
+0b11: invalid, must support as least one CPOL setting.
+
+bit 4: chipselect active high feature, 0 for unsupported and 1 for
supported,
+chipselect active low must always be supported.
+
+bit 5: LSB first feature, 0 for unsupported and 1 for supported, MSB
first must always be
+supported.
+
+bit 6: loopback mode feature, 0 for unsupported and 1 for supported,
normal mode
+must always be supported.
+
+Note: CPOL is clock polarity and CPHA is clock phase. If CPOL is 0, the clock
idles at the logical
+low voltage
[virtio-dev][PATCH V7 1/2] content: Rename SPI master to SPI controller
SPI master is an outdated term and should use SPI controller.
Signed-off-by: Haixu Cui
---
content.tex | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/content.tex b/content.tex
index 0a62dce..1c608eb 100644
--- a/content.tex
+++ b/content.tex
@@ -737,7 +737,7 @@ \chapter{Device Types}\label{sec:Device Types}
\hline
44 & ISM device \\
\hline
-45 & SPI master \\
+45 & SPI controller \\
\hline
\end{tabular}
--
2.17.1
-
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
[virtio-dev][PATCH V7 0/2] virtio-spi: add virtual SPI controller
The Virtio SPI (Serial Peripheral Interface) device is a virtual SPI controller that allows the driver to operate and use the SPI controller under the control of the device, either a physical SPI controller, or an emulated one. Patch summary: patch 1 rename virtual SPI device name patch 2 add the specification for virtio-spi Haixu Cui (2): content: Rename SPI master to SPI controller virtio-spi: add the device specification content.tex | 2 +- device-types/spi/description.tex| 280 device-types/spi/device-conformance.tex | 7 + device-types/spi/driver-conformance.tex | 7 + 4 files changed, 295 insertions(+), 1 deletion(-) 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 -- 2.17.1 - To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
Re: [virtio-dev] [PATCH V6 2/2] virtio-spi: add the device specification
Hi Viresh, On 12/1/2023 1:44 PM, Viresh Kumar wrote: On 01-12-23, 13:35, Haixu Cui wrote: Hi Viresh, SPI transfer modes here may cause misunderstanding, in Wikipedia, SPI mode is the combinations of clock polarity and clock phases: https://en.wikipedia.org/w/index.php?title=Serial_Peripheral_Interface&action=edit§ion=4 The word 'mode' is indeed confusing. It is used for combinations of PHA/POL, half/full duplex, n-bit transfers, etc.. Yes, it is. In this spec, for half/full duplex, I use "transfer type", and for line number, just use "n-bit transfer", to avoid ambiguity. What about updating as: "Note: The commonly used SPI n-bit transfer options are:" That's fine too. OK, thank you. Best Regards Haixu Cui - To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
Re: [virtio-dev] [PATCH V6 2/2] virtio-spi: add the device specification
On 12/1/2023 12:32 PM, Viresh Kumar wrote:
On 01-12-23, 12:05, Haixu Cui wrote:
Looks good. Will update as follows:
\field{tx_nbits_supported} and \field{rx_nbits_supported} indicate the
different n-bit transfer modes supported by the device, for writing and
reading respectively. SINGLE is always supported. A set bit here indicates
that the corresponding n-bit transfer is supported, otherwise not:
bit 0: DUAL;
bit 1: QUAD;
bit 2: OCTAL;
other bits are reserved and must be set as 0 by the device.
Note: Transfer bit options are commonly used in SPI:
Maybe:
Note: The commonly used SPI transfer modes are:
Hi Viresh,
SPI transfer modes here may cause misunderstanding, in Wikipedia,
SPI mode is the combinations of clock polarity and clock phases:
https://en.wikipedia.org/w/index.php?title=Serial_Peripheral_Interface&action=edit§ion=4
What about updating as: "Note: The commonly used SPI n-bit transfer
options are:"
Thanks & BR
Haixu Cui
-
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
Re: [virtio-dev] [PATCH V6 2/2] virtio-spi: add the device specification
Hi Huck,
On 11/30/2023 7:38 PM, Cornelia Huck wrote:
On Thu, Nov 30 2023, Haixu Cui wrote:
The Virtio SPI (Serial Peripheral Interface) device is a virtual
SPI controller that allows the driver to operate and use the SPI
controller under the control of the device.
This patch adds the specification for virtio-spi.
Signed-off-by: Haixu Cui
---
device-types/spi/description.tex| 288
device-types/spi/device-conformance.tex | 7 +
device-types/spi/driver-conformance.tex | 7 +
3 files changed, 302 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 000..c4816a6
--- /dev/null
+++ b/device-types/spi/description.tex
@@ -0,0 +1,288 @@
+\section{SPI Controller Device}\label{sec:Device Types / SPI Controller Device}
+
+The Virtio SPI (Serial Peripheral Interface) device is a virtual SPI
controller that
+allows the driver to operate and use the SPI controller under the control of
the device,
+either a physical SPI controller, or an emulated one.
+
+The Virtio SPI device has a single virtqueue. SPI transfer requests are placed
into
+the virtqueue, and serviced by the device.
I think it would still make sense to keep the host/guest example you
included in the last version; while we have to talk about device/driver
in the specification, giving host/guest as an example is completely
fine.
Okay, I will add it back to illustrate the host&guest scenario.
+
+\subsection{Device ID}\label{sec:Device Types / SPI Controller Device / Device
ID}
+45
+
+\subsection{Virtqueues}\label{sec:Device Types / SPI Controller Device /
Virtqueues}
+
+\begin{description}
+\item[0] requestq
+\end{description}
+
+\subsection{Feature bits}\label{sec:Device Types / SPI Controller Device /
Feature bits}
+
+None
+
+\subsection{Device configuration layout}\label{sec:Device Types / SPI
Controller Device / Device configuration layout}
+
+All fields of this configuration are always available and read-only for Virtio
SPI driver.
s/for Virtio SPI driver/for the driver/
Okay.
(matches what is said for other device types)
+The config space shows the features and settings supported by the device.
+
+\begin{lstlisting}
+struct virtio_spi_config {
+ u8 cs_max_number;
+ u8 cs_change_supported;
+ u8 tx_nbits_supported;
+ u8 rx_nbits_supported;
+ le32 bits_per_word_mask;
+ le32 mode_func_supported;
+ le32 max_freq_hz;
+ le32 max_word_delay_ns;
+ le32 max_cs_setup_ns;
+ le32 max_cs_hold_ns;
+ le32 max_cs_inactive_ns;
+};
+\end{lstlisting}
+
+\field{cs_max_number} is the maximum number of chipselect the device supports.
+
+Note: chipselect is an electrical signal controlled by the SPI controller,
used to select the
+SPI slaves connected to the controller.
I wonder whether another term is now more commonly used... the Wikipedia
article uses main/sub, is there a term that is usually used together
with "controller"?
In Wikipedia,
"Historically, this arrangement has been called master/slave. But to
avoid referencing slavery, alternative names discussed in § Alternative
namings have been used."
I am not quite sure if main/sub is widely used, but in latest Linux,
still use master/slave but master is gradually replaced by "controller".
So I think "controller" here does make sense. What is your suggestion?
+
+\field{cs_change_supported} indicates if the device supports to toggle
chipselect
+after each transfer in one message:
+0: unsupported, means chipselect will keep active when executing the
message transaction;
+1: supported.
+
+Note: Message here contains a sequence of SPI transfers.
+
+\field{tx_nbits_supported} indicates the supported number of bit for writing,
SINGLE is always
+supported. In the bit definition below, a set bit means the transfer is
supported, otherwise not:
+bit 0: DUAL;
+bit 1: QUAD;
+bit 2: OCTAL;
+other bits are reserved and must be set to 0 by the device.
+
+Note: Transfer bit options are commonly used in SPI:
+\begin{itemize}
+\item SINGLE: 1-bit transfer
+\item DUAL: 2-bit transfer
+\item QUAD: 4-bit transfer
+\item OCTAL: 8-bit transfer
+\end{itemize}
+
+\field{rx_nbits_supported} indicates the supported number of bit for reading,
SINGLE is always
+supported. In the bit definition below, a set bit means the transfer is
supported, otherwise not:
+bit 0: DUAL;
+bit 1: QUAD;
+bit 2: OCTAL;
+other bits are reserved and must be set to 0 by the device.
+
+\field{bits_per_word_mask} is a mask indicating which values of bits_per_word
are supported.
+If not set, no limitation for bits_per_word.
s/no limitatio
Re: [virtio-dev] [PATCH V6 2/2] virtio-spi: add the device specification
Hi Viresh,
On 11/30/2023 7:19 PM, Viresh Kumar wrote:
On 30-11-23, 17:22, Haixu Cui wrote:
The Virtio SPI (Serial Peripheral Interface) device is a virtual
SPI controller that allows the driver to operate and use the SPI
controller under the control of the device.
This patch adds the specification for virtio-spi.
Signed-off-by: Haixu Cui
---
device-types/spi/description.tex| 288
device-types/spi/device-conformance.tex | 7 +
device-types/spi/driver-conformance.tex | 7 +
3 files changed, 302 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 000..c4816a6
--- /dev/null
+++ b/device-types/spi/description.tex
@@ -0,0 +1,288 @@
+\section{SPI Controller Device}\label{sec:Device Types / SPI Controller Device}
+
+The Virtio SPI (Serial Peripheral Interface) device is a virtual SPI
controller that
+allows the driver to operate and use the SPI controller under the control of
the device,
s/control of the device/control of the host/
The host emulates and provides the guest with a device. 'device' is not really a
replacement for the word 'host`, but should be used to refer to the entity
emulated by the host.
Here I want to emphasize the driver&device pair in the virtio
architecture, device here can also be considered as the proxy of the
host to manage the real SPI controller.
I will add back the following statement to illustrate the host&guest
condition:
"In a typical host and guest architecture with the Virtio SPI device,
the Virtio SPI driver is the front-end running in the guest, and the
Virtio SPI device is the back-end in the host."
+either a physical SPI controller, or an emulated one.
+
+The Virtio SPI device has a single virtqueue. SPI transfer requests are placed
into
+the virtqueue, and serviced by the device.
s/the virtqueue, and /the virtqueue by the driver, and are /
Okay.
+
+\subsection{Device ID}\label{sec:Device Types / SPI Controller Device / Device
ID}
+45
+
+\subsection{Virtqueues}\label{sec:Device Types / SPI Controller Device /
Virtqueues}
+
+\begin{description}
+\item[0] requestq
+\end{description}
+
+\subsection{Feature bits}\label{sec:Device Types / SPI Controller Device /
Feature bits}
+
+None
+
+\subsection{Device configuration layout}\label{sec:Device Types / SPI
Controller Device / Device configuration layout}
+
+All fields of this configuration are always available and read-only for Virtio
SPI driver.
s/always available/mandatory/
Okay.
and "the Virtio SPI driver", everywhere else too..
Will update the whole spec.
+The config space shows the features and settings supported by the device.
+
+\begin{lstlisting}
+struct virtio_spi_config {
+ u8 cs_max_number;
+ u8 cs_change_supported;
+ u8 tx_nbits_supported;
+ u8 rx_nbits_supported;
+ le32 bits_per_word_mask;
+ le32 mode_func_supported;
+ le32 max_freq_hz;
+ le32 max_word_delay_ns;
+ le32 max_cs_setup_ns;
+ le32 max_cs_hold_ns;
+ le32 max_cs_inactive_ns;
+};
+\end{lstlisting}
+
+\field{cs_max_number} is the maximum number of chipselect the device supports.
+
+Note: chipselect is an electrical signal controlled by the SPI controller,
used to select the
+SPI slaves connected to the controller.
It isn't mandatory for the CS to be controlled by the controller. It can also be
a GPIO pin too which is controlled by the host driver.
Suggest rewriting as:
Note: chipselect is an electrical signal, which is used to select the SPI slaves
connected to the controller.
Got it. If GPIO, it's not appropriate to say cs is controlled by
controller, maybe the SPI driver just invokes the GPIO interface.
+\field{cs_change_supported} indicates if the device supports to toggle
chipselect
+after each transfer in one message:
+0: unsupported, means chipselect will keep active when executing the
message transaction;
0: unsupported, chipselect will be kept in active state throughout the
transaction;
Okay.
+1: supported.
+
+Note: Message here contains a sequence of SPI transfers.
+
+\field{tx_nbits_supported} indicates the supported number of bit for writing,
SINGLE is always
+supported. In the bit definition below, a set bit means the transfer is
supported, otherwise not:
+bit 0: DUAL;
+bit 1: QUAD;
+bit 2: OCTAL;
+other bits are reserved and must be set to 0 by the device.
+
Not sure if the below Note and the item list is required at all.
+Note: Transfer bit options are commonly used in SPI:
+\begin{itemize}
+\item SINGLE: 1-bit transfer
+\item DUAL: 2-bit transfer
+\item QUAD: 4-bit transfer
+\item OCTAL: 8-bit transfer
+\end
[virtio-dev] [PATCH V6 2/2] virtio-spi: add the device specification
The Virtio SPI (Serial Peripheral Interface) device is a virtual
SPI controller that allows the driver to operate and use the SPI
controller under the control of the device.
This patch adds the specification for virtio-spi.
Signed-off-by: Haixu Cui
---
device-types/spi/description.tex| 288
device-types/spi/device-conformance.tex | 7 +
device-types/spi/driver-conformance.tex | 7 +
3 files changed, 302 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 000..c4816a6
--- /dev/null
+++ b/device-types/spi/description.tex
@@ -0,0 +1,288 @@
+\section{SPI Controller Device}\label{sec:Device Types / SPI Controller Device}
+
+The Virtio SPI (Serial Peripheral Interface) device is a virtual SPI
controller that
+allows the driver to operate and use the SPI controller under the control of
the device,
+either a physical SPI controller, or an emulated one.
+
+The Virtio SPI device has a single virtqueue. SPI transfer requests are placed
into
+the virtqueue, and serviced by the device.
+
+\subsection{Device ID}\label{sec:Device Types / SPI Controller Device / Device
ID}
+45
+
+\subsection{Virtqueues}\label{sec:Device Types / SPI Controller Device /
Virtqueues}
+
+\begin{description}
+\item[0] requestq
+\end{description}
+
+\subsection{Feature bits}\label{sec:Device Types / SPI Controller Device /
Feature bits}
+
+None
+
+\subsection{Device configuration layout}\label{sec:Device Types / SPI
Controller Device / Device configuration layout}
+
+All fields of this configuration are always available and read-only for Virtio
SPI driver.
+The config space shows the features and settings supported by the device.
+
+\begin{lstlisting}
+struct virtio_spi_config {
+ u8 cs_max_number;
+ u8 cs_change_supported;
+ u8 tx_nbits_supported;
+ u8 rx_nbits_supported;
+ le32 bits_per_word_mask;
+ le32 mode_func_supported;
+ le32 max_freq_hz;
+ le32 max_word_delay_ns;
+ le32 max_cs_setup_ns;
+ le32 max_cs_hold_ns;
+ le32 max_cs_inactive_ns;
+};
+\end{lstlisting}
+
+\field{cs_max_number} is the maximum number of chipselect the device supports.
+
+Note: chipselect is an electrical signal controlled by the SPI controller,
used to select the
+SPI slaves connected to the controller.
+
+\field{cs_change_supported} indicates if the device supports to toggle
chipselect
+after each transfer in one message:
+0: unsupported, means chipselect will keep active when executing the
message transaction;
+1: supported.
+
+Note: Message here contains a sequence of SPI transfers.
+
+\field{tx_nbits_supported} indicates the supported number of bit for writing,
SINGLE is always
+supported. In the bit definition below, a set bit means the transfer is
supported, otherwise not:
+bit 0: DUAL;
+bit 1: QUAD;
+bit 2: OCTAL;
+other bits are reserved and must be set to 0 by the device.
+
+Note: Transfer bit options are commonly used in SPI:
+\begin{itemize}
+\item SINGLE: 1-bit transfer
+\item DUAL: 2-bit transfer
+\item QUAD: 4-bit transfer
+\item OCTAL: 8-bit transfer
+\end{itemize}
+
+\field{rx_nbits_supported} indicates the supported number of bit for reading,
SINGLE is always
+supported. In the bit definition below, a set bit means the transfer is
supported, otherwise not:
+bit 0: DUAL;
+bit 1: QUAD;
+bit 2: OCTAL;
+other bits are reserved and must be set to 0 by the device.
+
+\field{bits_per_word_mask} is a mask indicating which values of bits_per_word
are supported.
+If not set, no limitation for bits_per_word.
+
+Note: bits_per_word corresponds to \field{bits_per_word} in \field{struct
virtio_spi_transfer_head}.
+
+\field{mode_func_supported} indicates whether the following features are
supported or not:
+bit 0-1: CPHA feature,
+0b00: supports CPHA=0 and CPHA=1;
+0b01: supports CPHA=0 only;
+0b10: supports CPHA=1 only;
+0b11: invalid, must support as least one CPHA setting.
+
+bit 2-3: CPOL feature,
+0b00: supports CPOL=0 and CPOL=1;
+0b01: supports CPOL=0 only;
+0b10: supports CPOL=1 only;
+0b11: invalid, must support as least one CPOL setting.
+
+bit 4: chipselect active high feature, 0 for unsupported and 1 for
supported,
+chipselect active low must always be supported.
+
+bit 5: LSB first feature, 0 for unsupported and 1 for supported, MSB
first must always be
+supported.
+
+bit 6: loopback mode feature, 0 for unsupported and 1 for supported,
normal mode
+must always be supported.
+
+Note: CPOL is clock polarity and CPHA is clock phase. If
[virtio-dev] [PATCH V6 1/2] content: Rename SPI master to SPI controller
SPI master is an outdated term and should use SPI controller.
Signed-off-by: Haixu Cui
---
content.tex | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/content.tex b/content.tex
index 0a62dce..1c608eb 100644
--- a/content.tex
+++ b/content.tex
@@ -737,7 +737,7 @@ \chapter{Device Types}\label{sec:Device Types}
\hline
44 & ISM device \\
\hline
-45 & SPI master \\
+45 & SPI controller \\
\hline
\end{tabular}
--
2.17.1
-
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
[virtio-dev] [PATCH V6 0/2] virtio-spi: add virtual SPI controller
The Virtio SPI (Serial Peripheral Interface) device is a virtual SPI controller that allows the driver to operate and use the SPI controller under the control of the device, either a physical SPI controller, or an emulated one. Patch summary: patch 1 rename virtual SPI device name patch 2 add the specification for virtio-spi Haixu Cui (2): content: Rename SPI master to SPI controller virtio-spi: add the device specification content.tex | 2 +- device-types/spi/description.tex| 288 device-types/spi/device-conformance.tex | 7 + device-types/spi/driver-conformance.tex | 7 + 4 files changed, 303 insertions(+), 1 deletion(-) 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 -- 2.17.1 - To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
[virtio-dev] Re: [virtio-comment] [PATCH] [PATCH v5] virtio-spi: add the device specification
On 11/30/2023 12:13 PM, Viresh Kumar wrote:
On 29-11-23, 13:42, Cornelia Huck wrote:
On Wed, Nov 29 2023, Viresh Kumar wrote:
On 29-11-23, 18:31, Haixu Cui wrote:
Hi Viresh,
Thank you for your helpful comments. In next patch, I will clearly point
this out:
Great, finally we are on the same page. Thanks Haixu.
"For full-duplex read and write transfer, both \field{tx_buf} and
\field{rx_buf} are used and the buffer size of \field{tx_buf} must be same
as \field{rx_buf}."
Suggest rewriting as:
In full-duplex transfer mode, both \field{tx_buf} and \field{rx_buf} are sent by
the driver, \field{tx_buf} followed by \field{rx_buf}. The length of both the
buffers MUST be same.
Is that in a non-normative section? (Sorry, I've lost track here...)
Hi Viresh，
I think yes, though I am not sure where Haixu will put it eventually :)
I would like to put it in normative section, both for driver and device.
If
so, I would say:
"The length of both buffers has to be the same."
That's better. Thanks.
device MUST fail the transfer and notify the driver.
"notify the driver" == "set an appropriate error value"?
Can this be covered by one of the existing error values?
I think yes, this can be handled by the Param error.
Yes, this seems still in scope of parameter checking.
Thanks & Best Regards
Haixu Cui
-
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
[virtio-dev] Re: [virtio-comment] [PATCH] [PATCH v5] virtio-spi: add the device specification
Hi Huck,
On 11/29/2023 8:42 PM, Cornelia Huck wrote:
On Wed, Nov 29 2023, Viresh Kumar wrote:
On 29-11-23, 18:31, Haixu Cui wrote:
Hi Viresh,
Thank you for your helpful comments. In next patch, I will clearly point
this out:
Great, finally we are on the same page. Thanks Haixu.
"For full-duplex read and write transfer, both \field{tx_buf} and
\field{rx_buf} are used and the buffer size of \field{tx_buf} must be same
as \field{rx_buf}."
Suggest rewriting as:
In full-duplex transfer mode, both \field{tx_buf} and \field{rx_buf} are sent by
the driver, \field{tx_buf} followed by \field{rx_buf}. The length of both the
buffers MUST be same.
Is that in a non-normative section? (Sorry, I've lost track here...) If
so, I would say:
"The length of both buffers has to be the same."
This is non-normative section.
And in drivernormative section, I will add a requirement:
"For full-duplex transfer, Virtio SPI driver MUST guarantee the write
transfer size is equal to the read transfer size"
Maybe:
drivernormative:
In full-duplex transfer mode, the Virtio SPI driver MUST guarantee that the
length of both \field{tx_buf} and \field{rx_buf} are same.
s/are same/is the same/
devicenormative:
In full-duplex transfer mode, the Virtio SPI device MUST verify that the length
of both \field{tx_buf} and \field{rx_buf} are same. In case of any mismatch, the
s/are same/is the same/
device MUST fail the transfer and notify the driver.
"notify the driver" == "set an appropriate error value"?
Can this be covered by one of the existing error values?
I'd like to use VIRTIO_SPI_PARAM_ERR to indicates the buffer size
inequality issue here because this is in the scope of parameter checking.
Thanks & BR
Haixu Cui
-
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
[virtio-dev] Re: [virtio-comment] [PATCH] [PATCH v5] virtio-spi: add the device specification
On 11/29/2023 6:00 PM, Viresh Kumar wrote:
On 29-11-23, 16:54, Haixu Cui wrote:
On 11/29/2023 4:33 PM, Cornelia Huck wrote:
On Wed, Nov 29 2023, Haixu Cui wrote:
On 11/29/2023 3:30 PM, Viresh Kumar wrote:
On 28-11-23, 20:58, Haixu Cui wrote:
On 11/27/2023 6:17 PM, Viresh Kumar wrote:
Hmm, I worked with a SPI controller over a decade ago, and I must be forgetting
something here I guess. But from whatever little I remember, with full-duplex
transfer, data flows on both MOSI and MISO lines as soon as clock signal is
applied. And so amount of data sent is always be equal to amount of data
received by both sides.
Also if I see Linux's implementation of the `struct spi_transfer` [1], I see
`tx_buf`, `rx_buf` and a single `len` field, which applies to both the buffers.
Which I guess is indicating that both buffers are supposed to be of same length.
What am I missing ?
Oh so sorry for that. And I don't make it clear. Yes, tx_buf and rx_buf
have the same size, Linux has such restriction. Just as you mention,
kernel level spi_transfer has single "len", the same for
spi_ioc_transfer passed from the userland.
But I am not sure if this is in the scope of the spec. Because this is
ensured by Linux, but Virtio SPI driver won't also can't verify this.
This is a prerequisite for virtio spi processing requests.
I don't think this is a Linux only thing. This is how the SPI protocol is
designed to begin with. A clock is applied, data from FIFOs of both master and
slaves gets exchanged over the MOSI and MISO lines... And the length is _always_
the same. We are talking about the full-duplex mode of the hardware here and
this is how it works AFAICT.
So the spec should clearly point this out to avoid any mistakes. Or if you have
a usecase where you can have different lengths for tx and rx buffers, that I am
not aware of ?
Hi Viresh,
Thank you for your helpful comments. In next patch, I will clearly
point this out:
"For full-duplex read and write transfer, both \field{tx_buf} and
\field{rx_buf} are used and the buffer size of \field{tx_buf} must be
same as \field{rx_buf}."
And in drivernormative section, I will add a requirement:
"For full-duplex transfer, Virtio SPI driver MUST guarantee the
write transfer size is equal to the read transfer size"
In fact, in my prototype, I only perform the transfers with same
tx/rx length.
Much appreciated.
Best Regards
Haixu Cui
What is your suggestion? How about adding some descriptions here, like
"for full-duplex, tx_buf and rx_buf are same in size, this is guaranteed
by the kernel"?
We must not really make any assumptions in the spec about concrete
implementations (here, the Linux kernel), as someone implementing it in
a different environment will need to make explicit choices.
I agree. I pointed this out since this is how the protocol works.
So, if tx_buf and rx_buf are required to be of the same size, it needs
to be explicitly stated in the spec, or an implementation might choose
to do it differently.
--
Viresh
-
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
[virtio-dev] Re: [virtio-comment] [PATCH] [PATCH v5] virtio-spi: add the device specification
On 11/29/2023 4:33 PM, Cornelia Huck wrote:
On Wed, Nov 29 2023, Haixu Cui wrote:
Hi Viresh,
On 11/29/2023 3:30 PM, Viresh Kumar wrote:
On 28-11-23, 20:58, Haixu Cui wrote:
On 11/27/2023 6:17 PM, Viresh Kumar wrote:
On 24-11-23, 15:20, Haixu Cui wrote:
+For half-duplex read transfer, \field{rx_buf} is filled by Virtio SPI device
and consumed
+by Virtio SPI driver. For half-duplex write transfer, \field{tx_buf} is filled
by Virtio
+SPI driver and consumed by Virtio SPI device. And for full-duplex read and
write transfer,
+both \field{tx_buf} and \field{rx_buf} are used.
Should the length of both the buffers in full-duplex mode be same ? If yes, then
this should be mentioned (in case it is not).
No, there is no such limitation. Write and read buffers may be different is
size.
Hmm, I worked with a SPI controller over a decade ago, and I must be forgetting
something here I guess. But from whatever little I remember, with full-duplex
transfer, data flows on both MOSI and MISO lines as soon as clock signal is
applied. And so amount of data sent is always be equal to amount of data
received by both sides.
Also if I see Linux's implementation of the `struct spi_transfer` [1], I see
`tx_buf`, `rx_buf` and a single `len` field, which applies to both the buffers.
Which I guess is indicating that both buffers are supposed to be of same length.
What am I missing ?
Oh so sorry for that. And I don't make it clear. Yes, tx_buf and rx_buf
have the same size, Linux has such restriction. Just as you mention,
kernel level spi_transfer has single "len", the same for
spi_ioc_transfer passed from the userland.
But I am not sure if this is in the scope of the spec. Because this is
ensured by Linux, but Virtio SPI driver won't also can't verify this.
This is a prerequisite for virtio spi processing requests.
What is your suggestion? How about adding some descriptions here, like
"for full-duplex, tx_buf and rx_buf are same in size, this is guaranteed
by the kernel"?
We must not really make any assumptions in the spec about concrete
implementations (here, the Linux kernel), as someone implementing it in
a different environment will need to make explicit choices.
So, if tx_buf and rx_buf are required to be of the same size, it needs
to be explicitly stated in the spec, or an implementation might choose
to do it differently.
Okay! Thanks Huck for guidance and thanks Viresh for pointing it out.
Much appreciated.
Best Regards
Haixu Cui
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-subscr...@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscr...@lists.oasis-open.org
List help: virtio-comment-h...@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-subscr...@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscr...@lists.oasis-open.org
List help: virtio-comment-h...@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/
-
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
[virtio-dev] Re: [virtio-comment] [PATCH] [PATCH v5] virtio-spi: add the device specification
Hi Viresh,
On 11/29/2023 3:30 PM, Viresh Kumar wrote:
On 28-11-23, 20:58, Haixu Cui wrote:
On 11/27/2023 6:17 PM, Viresh Kumar wrote:
On 24-11-23, 15:20, Haixu Cui wrote:
+For half-duplex read transfer, \field{rx_buf} is filled by Virtio SPI device
and consumed
+by Virtio SPI driver. For half-duplex write transfer, \field{tx_buf} is filled
by Virtio
+SPI driver and consumed by Virtio SPI device. And for full-duplex read and
write transfer,
+both \field{tx_buf} and \field{rx_buf} are used.
Should the length of both the buffers in full-duplex mode be same ? If yes, then
this should be mentioned (in case it is not).
No, there is no such limitation. Write and read buffers may be different is
size.
Hmm, I worked with a SPI controller over a decade ago, and I must be forgetting
something here I guess. But from whatever little I remember, with full-duplex
transfer, data flows on both MOSI and MISO lines as soon as clock signal is
applied. And so amount of data sent is always be equal to amount of data
received by both sides.
Also if I see Linux's implementation of the `struct spi_transfer` [1], I see
`tx_buf`, `rx_buf` and a single `len` field, which applies to both the buffers.
Which I guess is indicating that both buffers are supposed to be of same length.
What am I missing ?
Oh so sorry for that. And I don't make it clear. Yes, tx_buf and rx_buf
have the same size, Linux has such restriction. Just as you mention,
kernel level spi_transfer has single "len", the same for
spi_ioc_transfer passed from the userland.
But I am not sure if this is in the scope of the spec. Because this is
ensured by Linux, but Virtio SPI driver won't also can't verify this.
This is a prerequisite for virtio spi processing requests.
What is your suggestion? How about adding some descriptions here, like
"for full-duplex, tx_buf and rx_buf are same in size, this is guaranteed
by the kernel"?
+Virtio SPI device MUST NOT change the data in \field{tx_buf} if transfer type
is half-duplex write
+or full-duplex read and write.
The device MUST NOT change the contents of the tx_buf ever, i.e. for every mode
there is. In half-duplex read mode, there is no tx_buf, but just rx_buf.
Sorry I don'y understand here. In this statement, the transfer type is
either half-duplex write or full-duplex read and write. half-duplex read
type has no tx_buf, so I didn't mention it.
Sorry for not being clear earlier. I was suggesting you to just write this
instead:
The Virtio SPI device MUST NOT change the data in the \field{tx_buf} field.
You don't really need to specify the modes here, as we are talking about tx_buf,
which isn't available in the half-duplex read mode but all others.
OK, thank you for your explanation. I will remove the "if" statement here.
-- > Viresh
[1]
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/linux/spi/spi.h#n1031
Thanks again.
Best Regards
Haixu Cui
-
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
[virtio-dev] Re: [virtio-comment] [PATCH] [PATCH v5] virtio-spi: add the device specification
Hi Viresh,
Thank you for your comments and please refer to my replies below
each comment.
On 11/27/2023 6:17 PM, Viresh Kumar wrote:
Hi Haixu,
Cornelia has already covered most of the issues, I will try to add few more
things I noticed.
On 24-11-23, 15:20, Haixu Cui wrote:
virtio-spi is a virtual SPI (Serial Peripheral Interface) controller and it
allows
a guest to operate and use the host SPI controller.
This patch adds the specification for virtio-spi.
Signed-off-by: Haixu Cui
---
device-types/spi/description.tex| 281
device-types/spi/device-conformance.tex | 7 +
device-types/spi/driver-conformance.tex | 7 +
3 files changed, 295 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 000..8ca8c0d
--- /dev/null
+++ b/device-types/spi/description.tex
@@ -0,0 +1,281 @@
+\section{SPI Master Device}\label{sec:Device Types / SPI Master Device}
Not sure if we should use "Master" anywhere..
Maybe: s/SPI Master Device/SPI Device/ ?
Applies elsewhere too..
Master here shows the spec is for SPI master rather than SPI slave.
But Master is outdated term and will be replaced by "SPI controller
device" in next patch.
+
+virtio-spi is a virtual SPI (Serial Peripheral Interface) controller and it
allows
Maybe:
s/virtio-spi/The Virtio SPI device/ (this applies at multiple places)
s/and it allows/that allows/
?
Okay, "The Virtio SPI device" is much better than virtio-spi.
+a guest to operate and use the host SPI controller. Host SPI controller may be
a
Maybe: The host SPI controller ... ?
+physical controller, or a virtual one(e.g. controller emulated by the software
+running in the host).
+
+virtio-spi has a single virtqueue. SPI transfer requests are placed into
The Virtio SPI device..
Likewise.
+the virtqueue, and serviced by the host SPI controller.
+
+In a typical host and guest architecture with virtio-spi, Virtio SPI driver is
+the front-end running in the guest kernel, and Virtio SPI device acts as the
+back-end in the host.
+
+\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 Virtio
SPI driver.
+The config space shows the features and settings supported by the host SPI
controller.
+
+\begin{lstlisting}
+struct virtio_spi_config {
+ u8 chip_select_max_number;
+ u8 cs_change_supported;
+ u8 tx_nbits_supported;
+ u8 rx_nbits_supported;
+ le32 bits_per_word_mask;
+ le32 mode_func_supported;
+ le32 max_freq_hz;
+ le32 max_word_delay_ns;
+ le32 max_cs_setup_ns;
+ le32 max_cs_hold_ns;
+ le32 max_cs_inactive_ns;
+};
+\end{lstlisting}
+
+The \field{chip_select_max_number} is the maximum number of chipselect the
host SPI controller supports.
+
+The \field{cs_change_supported} indicates if the host SPI controller supports
to toggle chipselect
+after each transfer in one message:
+0: supported;
+1: unsupported, means chipselect will keep active when executing the
message transaction.
+Note: Message here contains a sequence of SPI transfer >
I would rather suggest using '1' for supported and '0' for unsupported, like you
have done for LSB first, loopback, etc. later..
OK, will update in next patch.
+The \field{tx_nbits_supported} indicates the supported number of bit for
writing:
+bit 0: 2-bit transfer, 0 for unsupported and 1 for supported;
+bit 1: 4-bit transfer, 0 for unsupported and 1 for supported;
+bit 2: 8-bit transfer, 0 for unsupported and 1 for supported;
Maybe you can mention first that, a set bit means feature is supported,
otherwise now. And then you can just write:
bit 0: 2-bit transfer
bit 1: 4-bit transfer
bit 2: 8-bit transfer
+other bits are reserved as 0, 1-bit transfer is always supported.
Maybe write as: other bits are reserved and MUST be set to 0 by the device.
Agree. Will update.
+
+The \field{rx_nbits_supported} indicates the supported number of bit for
reading:
+bit 0: 2-bit transfer, 0 for unsupported and 1 for supported;
+bit 1: 4-bit transfer, 0 for unsupported and 1 for supported;
+bit 2: 8-bit transfer, 0 for unsupported and 1 for supported;
+o
[virtio-dev] Re: [PATCH] [PATCH v5] virtio-spi: add the device specification
Hi Huck,
On 11/27/2023 10:26 PM, Cornelia Huck wrote:
On Mon, Nov 27 2023, Haixu Cui wrote:
On 11/24/2023 11:46 PM, Cornelia Huck wrote:
On Fri, Nov 24 2023, Haixu Cui wrote:
+The \field{chip_select_max_number} is the maximum number of chipselect the
host SPI controller supports.
"chipselect" is probably a known term for people familiar with SPI -- is
there any definition of those terms that the spec can point to?
Just as Mark said, there is no formal spec for SPI, so no standard spec
for such terms referring to. The same for CPHA/CPOL/LSB/MSB, please see
below.
If we have nothing to point to, it is probably best to simply
expand/explain the terms on their first usage.
OK, I will add description at where they are firstly used.
Can we point to some documentation that explains CPHA and CPOL?
Here. No standard SPI spec to point to. CPOL/CPHA have definitions in
wikipedia(Clock polarity and phase chapter):
https://en.wikipedia.org/wiki/Serial_Peripheral_Interface
How about copying some concise information from wikipedia as Note? Or is
referring to such webpage acceptable in this spec.
Not sure if we can do an outright copy (licence compatibility), but
paraphrasing should be fine. (I'd rather not directly reference the
site, because the content is not guaranteed to be stable, but we could
maybe add it as "further reading".)
+For each transfer request, Virtio SPI driver MUST check the fields in
structure \field{virtio_spi_transfer_head}
+and MUST reject the request if any filed is invalid or enabling the features
not supported by host.
s/filed/field/
s/host/device/
Also, isn't the rejecting supposed to be done by the device, as the
driver is the party enqueueing the requests? Or do I have some kind of
fundamental misunderstanding?
It may be better to filter some invalid requests by driver, as in the
request header there are many parameters, and some of them are not
supported by device, so it's quite possible that many requests invalid
for the device. So if driver can do the first filter, such invalid
requests will not be sent at all, this will conserve virtqueue and
system overhead.
And this is why exposing device supported features in the config space,
it ensures that almost all requests in virtqueue are nice to the backend.
device also will verify the requests again, as the following requirement:
Virtio SPI device MUST verify the parameters in
\field{virtio_spi_transfer_head} after receiving the request,
and MUST set \field{virtio_spi_transfer_result} as VIRTIO_SPI_PARAM_ERR
if not all parameters are valid or some device unsupported features are set.
Although checking the requests twice seems a little redundant, it is
more efficient comparing with sending some invalid requests to the device.
What is your opinion? Do you think it is acceptable?
Thanks for your explanation, I think we simply have some terminology
issues. In the virtio spec, "driver" refers to one side of the
driver/device pair, and is used to describe how to communicate with the
device. In this case, "driver" would be the entity interacting with the
device, regardless of how it is implemented, and would be responsible
for sending the requests. Any filtering that would be done in a concrete
implementation (i.e. if you have one component generating the requests,
and then another component filtering them before actually putting them
into the queue) is out of scope for this spec -- we can maybe specify
that the driver should not send invalid requests, but I'm not sure that
this is actually needed.
Got it. I agree with you, and I suggest that driver should do some
filter jobs to reduce the system overhead, but this should not be
compulsory for driver.
Thank you for your ideas.
Best Regards
Haixu Cui
Once again, thanks a lot for your support.
You're welcome!
-
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
[virtio-dev] Re: [virtio-comment] Re: [PATCH] [PATCH v5] virtio-spi: add the device specification
On 11/27/2023 10:33 PM, Cornelia Huck wrote:
On Mon, Nov 27 2023, Cornelia Huck wrote:
On Mon, Nov 27 2023, Haixu Cui wrote:
On 11/24/2023 11:46 PM, Cornelia Huck wrote:
On Fri, Nov 24 2023, Haixu Cui wrote:
+The \field{chip_select_max_number} is the maximum number of chipselect the
host SPI controller supports.
"chipselect" is probably a known term for people familiar with SPI -- is
there any definition of those terms that the spec can point to?
Just as Mark said, there is no formal spec for SPI, so no standard spec
for such terms referring to. The same for CPHA/CPOL/LSB/MSB, please see
below.
If we have nothing to point to, it is probably best to simply
expand/explain the terms on their first usage.
Can we point to some documentation that explains CPHA and CPOL?
Here. No standard SPI spec to point to. CPOL/CPHA have definitions in
wikipedia(Clock polarity and phase chapter):
https://en.wikipedia.org/wiki/Serial_Peripheral_Interface
How about copying some concise information from wikipedia as Note? Or is
referring to such webpage acceptable in this spec.
Not sure if we can do an outright copy (licence compatibility), but
paraphrasing should be fine. (I'd rather not directly reference the
site, because the content is not guaranteed to be stable, but we could
maybe add it as "further reading".)
Looking again, the kernel doc referenced by Mark
(https://www.kernel.org/doc/html/v6.6/driver-api/spi.html) might also be
a good candidate, especially as we can refer to a specific version.
This Linux doc is a good Normative References, but it doesn't have
definitions of the terms, like chipselect, CPOA, LSB...
I will add some concise descriptions on their first usage.
Best Regards
Thanks
Haixu Cui
-
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
[virtio-dev] Re: [PATCH] [PATCH v5] virtio-spi: add the device specification
Hi Huck,
Really appreciate for your comments and please refer to my replies
below each comment.
On 11/24/2023 11:46 PM, Cornelia Huck wrote:
On Fri, Nov 24 2023, Haixu Cui wrote:
virtio-spi is a virtual SPI (Serial Peripheral Interface) controller and it
allows
a guest to operate and use the host SPI controller.
This patch adds the specification for virtio-spi.
As Mark has already reviewed it from the SPI POV (thanks!), I'm now
looking at the virtio side.
Signed-off-by: Haixu Cui
---
device-types/spi/description.tex| 281
device-types/spi/device-conformance.tex | 7 +
device-types/spi/driver-conformance.tex | 7 +
3 files changed, 295 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 000..8ca8c0d
--- /dev/null
+++ b/device-types/spi/description.tex
@@ -0,0 +1,281 @@
+\section{SPI Master Device}\label{sec:Device Types / SPI Master Device}
+
+virtio-spi is a virtual SPI (Serial Peripheral Interface) controller and it
allows
+a guest to operate and use the host SPI controller. Host SPI controller may be
a
+physical controller, or a virtual one(e.g. controller emulated by the software
Missing space before the opening bracket.
+running in the host).
+
+virtio-spi has a single virtqueue. SPI transfer requests are placed into
+the virtqueue, and serviced by the host SPI controller.
Is there any way to express all of this without referring to "host" and
"guest" here? (The paragraph below giving it as an example is fine.)
Something like "The virtio-spi device is a virtual SPI controller. It
allows the driver to operate and use an SPI controller under the control
of the device, either a physical controller, or an emulated one."
Okay, in next patch, guest&host will be replaced by driver&device.
+
+In a typical host and guest architecture with virtio-spi, Virtio SPI driver is
+the front-end running in the guest kernel, and Virtio SPI device acts as the
+back-end in the host.
+
+\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 Virtio
SPI driver.
+The config space shows the features and settings supported by the host SPI
controller.
+
+\begin{lstlisting}
+struct virtio_spi_config {
+ u8 chip_select_max_number;
+ u8 cs_change_supported;
+ u8 tx_nbits_supported;
+ u8 rx_nbits_supported;
+ le32 bits_per_word_mask;
+ le32 mode_func_supported;
+ le32 max_freq_hz;
+ le32 max_word_delay_ns;
+ le32 max_cs_setup_ns;
+ le32 max_cs_hold_ns;
+ le32 max_cs_inactive_ns;
+};
+\end{lstlisting}
+
+The \field{chip_select_max_number} is the maximum number of chipselect the
host SPI controller supports.
"chipselect" is probably a known term for people familiar with SPI -- is
there any definition of those terms that the spec can point to?
Just as Mark said, there is no formal spec for SPI, so no standard spec
for such terms referring to. The same for CPHA/CPOL/LSB/MSB, please see
below.
Also, it should be either "The field \field{whatever}" or
"\field{whatever}"; "The \field{whatever}" looks good in the LaTeX
source, but not in the end result.
Okay, use "\field{whatever}".
+
+The \field{cs_change_supported} indicates if the host SPI controller supports
to toggle chipselect
+after each transfer in one message:
+0: supported;
+1: unsupported, means chipselect will keep active when executing the
message transaction.
+Note: Message here contains a sequence of SPI transfer.
+
+The \field{tx_nbits_supported} indicates the supported number of bit for
writing:
+bit 0: 2-bit transfer, 0 for unsupported and 1 for supported;
+bit 1: 4-bit transfer, 0 for unsupported and 1 for supported;
+bit 2: 8-bit transfer, 0 for unsupported and 1 for supported;
+other bits are reserved as 0, 1-bit transfer is always supported.
+
+The \field{rx_nbits_supported} indicates the supported number of bit for
reading:
+bit 0: 2-bit transfer, 0 for unsupported and 1 for supported;
+bit 1: 4-bit transfer, 0 for unsupported and 1 for supported;
+bit 2: 8-bit transfer, 0 for unsupported and 1 for supported;
+other bits are r
[virtio-dev] Re: [PATCH] [PATCH v5] virtio-spi: add the device specification
Hi Mark, Thank you, really appreciate. Best Regards Haixu Cui On 11/24/2023 8:48 PM, Mark Brown wrote: On Fri, Nov 24, 2023 at 03:20:15PM +0800, Haixu Cui wrote: virtio-spi is a virtual SPI (Serial Peripheral Interface) controller and it allows a guest to operate and use the host SPI controller. This patch adds the specification for virtio-spi. This looks fine from a SPI point of view, I don't really have any idea about what makes sense or is idomatic at the virtio level so can't really review there: Reviewed-by: Mark Brown - To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
[virtio-dev] [PATCH] [PATCH v5] virtio-spi: add the device specification
virtio-spi is a virtual SPI (Serial Peripheral Interface) controller and it
allows
a guest to operate and use the host SPI controller.
This patch adds the specification for virtio-spi.
Signed-off-by: Haixu Cui
---
device-types/spi/description.tex| 281
device-types/spi/device-conformance.tex | 7 +
device-types/spi/driver-conformance.tex | 7 +
3 files changed, 295 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 000..8ca8c0d
--- /dev/null
+++ b/device-types/spi/description.tex
@@ -0,0 +1,281 @@
+\section{SPI Master Device}\label{sec:Device Types / SPI Master Device}
+
+virtio-spi is a virtual SPI (Serial Peripheral Interface) controller and it
allows
+a guest to operate and use the host SPI controller. Host SPI controller may be
a
+physical controller, or a virtual one(e.g. controller emulated by the software
+running in the host).
+
+virtio-spi has a single virtqueue. SPI transfer requests are placed into
+the virtqueue, and serviced by the host SPI controller.
+
+In a typical host and guest architecture with virtio-spi, Virtio SPI driver is
+the front-end running in the guest kernel, and Virtio SPI device acts as the
+back-end in the host.
+
+\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 Virtio
SPI driver.
+The config space shows the features and settings supported by the host SPI
controller.
+
+\begin{lstlisting}
+struct virtio_spi_config {
+ u8 chip_select_max_number;
+ u8 cs_change_supported;
+ u8 tx_nbits_supported;
+ u8 rx_nbits_supported;
+ le32 bits_per_word_mask;
+ le32 mode_func_supported;
+ le32 max_freq_hz;
+ le32 max_word_delay_ns;
+ le32 max_cs_setup_ns;
+ le32 max_cs_hold_ns;
+ le32 max_cs_inactive_ns;
+};
+\end{lstlisting}
+
+The \field{chip_select_max_number} is the maximum number of chipselect the
host SPI controller supports.
+
+The \field{cs_change_supported} indicates if the host SPI controller supports
to toggle chipselect
+after each transfer in one message:
+0: supported;
+1: unsupported, means chipselect will keep active when executing the
message transaction.
+Note: Message here contains a sequence of SPI transfer.
+
+The \field{tx_nbits_supported} indicates the supported number of bit for
writing:
+bit 0: 2-bit transfer, 0 for unsupported and 1 for supported;
+bit 1: 4-bit transfer, 0 for unsupported and 1 for supported;
+bit 2: 8-bit transfer, 0 for unsupported and 1 for supported;
+other bits are reserved as 0, 1-bit transfer is always supported.
+
+The \field{rx_nbits_supported} indicates the supported number of bit for
reading:
+bit 0: 2-bit transfer, 0 for unsupported and 1 for supported;
+bit 1: 4-bit transfer, 0 for unsupported and 1 for supported;
+bit 2: 8-bit transfer, 0 for unsupported and 1 for supported;
+other bits are reserved as 0, 1-bit transfer is always supported.
+
+The \field{bits_per_word_mask} is a mask indicating which values of
bits_per_word
+are supported. If not set, no limitation for bits_per_word.
+Note: bits_per_word corresponds to \field{bits_per_word} field in
+structure \field{virtio_spi_transfer_head}, see below.
+
+The \field{mode_func_supported} indicates the following features are supported
or not:
+bit 0-1: CPHA feature,
+0b00: supports CPHA=0 and CPHA=1;
+0b01: supports CPHA=0 only;
+0b10: supports CPHA=1 only;
+0b11: invalid, should support as least one CPHA setting.
+
+bit 2-3: CPOL feature,
+0b00: supports CPOL=0 and CPOL=1;
+0b01: supports CPOL=0 only;
+0b10: supports CPOL=1 only;
+0b11: invalid, should support as least one CPOL setting.
+
+bit 4: chipselect active high feature, 0 for unsupported and 1 for
supported,
+chipselect active low should always be supported.
+
+bit 5: LSB first feature, 0 for unsupported and 1 for supported, MSB
first should always be
+supported.
+
+bit 6: loopback mode feature, 0 for unsupported and 1 for supported,
normal mode
+should always be supported.
+
+The \field{max_freq_hz} is the maximum clock rate supported in Hz unit
Re: [virtio-dev] [PATCH v4] virtio-spi: add the device specification
On 11/9/2023 9:11 PM, Mark Brown wrote: On Thu, Nov 09, 2023 at 07:21:57PM +0800, Haixu Cui wrote: For checking the parameters above in virtio_spi_transfer_head, I'd like to add these field in config space: 5. freq_max_speed: if non-zero, maximum clock rate support, in Hz unit. if 0, no limitation. 6. max_word_delay_ns: if non-zero, the maximum word delay supported. if 0, word delay is not supported to introduce. 7. max_delay_after_cs_asserted: if non-zero, the maximum cs setup delay supported.if 0, cs setup delay is not supported to introduce 8. max_delay_before_cs_deassert: if non-zero, the maximum cs_delay_hold_ns delay supported.if 0, cs setup delay is not supported to introduce 9. max_delay_after_cs_deassert: if non-zero, the maximum cs_change_delay_inactive_ns delay supported.if 0, cs setup delay is not supported to introduce I think this all makes sense - for the above we probably also need to say that if the value requested by the client can't be met exactly we either treat it as a minimum or maximum depending on the delays and choose the next value (probably a maximum for the clock and minimum for the rest). So for example if the client requests 21MHz and the controller can only select 20MHz or 25MHz then it should pick 20MHz. Sure, I will update to make it more flexible. Thanks a lot. Best Regards Haixu Cui - To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
[virtio-dev] Re: [RFC PATCH v1 3/3] SPI: Add virtio SPI driver (V4 draft specification).
Hi Harald,
Please refer to my comments below.
On 10/28/2023 12:10 AM, Harald Mommer wrote:
From: Harald Mommer
This is the first public version of the virtio SPI Linux kernel driver
compliant to the "PATCH v4" draft virtio SPI specification.
Signed-off-by: Harald Mommer
---
drivers/spi/Kconfig | 10 +
drivers/spi/Makefile | 1 +
drivers/spi/spi-virtio.c | 513 +++
3 files changed, 524 insertions(+)
create mode 100644 drivers/spi/spi-virtio.c
diff --git a/drivers/spi/Kconfig b/drivers/spi/Kconfig
index 35dbfacecf1c..55f45c5a8d82 100644
--- a/drivers/spi/Kconfig
+++ b/drivers/spi/Kconfig
@@ -1125,6 +1125,16 @@ config SPI_UNIPHIER
If your SoC supports SCSSI, say Y here.
+config SPI_VIRTIO
+ tristate "Virtio SPI SPI Controller"
+ depends on VIRTIO
+ help
+ This enables the Virtio SPI driver.
+
+ Virtio SPI is an SPI driver for virtual machines using Virtio.
+
+ If your Linux is a virtual machine using Virtio, say Y here.
+
config SPI_XCOMM
tristate "Analog Devices AD-FMCOMMS1-EBZ SPI-I2C-bridge driver"
depends on I2C
diff --git a/drivers/spi/Makefile b/drivers/spi/Makefile
index 4ff8d725ba5e..ff2243e44e00 100644
--- a/drivers/spi/Makefile
+++ b/drivers/spi/Makefile
@@ -146,6 +146,7 @@ spi-thunderx-objs := spi-cavium.o
spi-cavium-thunderx.o
obj-$(CONFIG_SPI_THUNDERX)+= spi-thunderx.o
obj-$(CONFIG_SPI_TOPCLIFF_PCH)+= spi-topcliff-pch.o
obj-$(CONFIG_SPI_UNIPHIER)+= spi-uniphier.o
+obj-$(CONFIG_SPI_VIRTIO) += spi-virtio.o
obj-$(CONFIG_SPI_XCOMM) += spi-xcomm.o
obj-$(CONFIG_SPI_XILINX) += spi-xilinx.o
obj-$(CONFIG_SPI_XLP) += spi-xlp.o
diff --git a/drivers/spi/spi-virtio.c b/drivers/spi/spi-virtio.c
new file mode 100644
index ..12a4d96555f1
--- /dev/null
+++ b/drivers/spi/spi-virtio.c
@@ -0,0 +1,513 @@
+// SPDX-License-Identifier: GPL-2.0-only
+/*
+ * SPI bus driver for the Virtio SPI controller
+ * Copyright (C) 2023 OpenSynergy GmbH
+ */
+
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+
+/* SPI device queues */
+#define VIRTIO_SPI_QUEUE_RQ 0
+#define VIRTIO_SPI_QUEUE_COUNT 1
+
+/* virtio_spi private data structure */
+struct virtio_spi_priv {
+ /* The virtio device we're associated with */
+ struct virtio_device *vdev;
+ /* The virtqueues */
+ struct virtqueue *vqs[VIRTIO_SPI_QUEUE_COUNT];
+ /* I/O callback function pointers for the virtqueues */
+ vq_callback_t *io_callbacks[VIRTIO_SPI_QUEUE_COUNT];
+ /* Support certain delay timing settings */
+ bool support_delays;
+};
+
+/* Compare with file i2c_virtio.c structure virtio_i2c_req */
+struct virtio_spi_req {
+ struct completion completion;
+#ifdef DEBUG
+ unsigned int rx_len;
+#endif
+ // clang-format off
+ struct spi_transfer_head transfer_head cacheline_aligned;
+ const uint8_t *tx_buf cacheline_aligned;
+ uint8_t *rx_buf cacheline_aligned;
+ struct spi_transfer_result result cacheline_aligned;
+ // clang-format on
+};
+
+static struct spi_board_info board_info = {
+ .modalias = "spi-virtio",
+ .max_speed_hz = 12500, /* Arbitrary very high limit */
+ .bus_num = 0, /* Patched later during initialization */
+ .chip_select = 0, /* Patched later during initialization */
+ .mode = SPI_MODE_0,
+};
+
+/* Compare with file i2c_virtio.c structure virtio_i2c_msg_done */
+static void virtio_spi_msg_done(struct virtqueue *vq)
+{
+ struct virtio_spi_req *req;
+ unsigned int len;
+
+ while ((req = virtqueue_get_buf(vq, &len)))
+ complete(&req->completion);
+}
+
+static int virtio_spi_one_transfer(struct virtio_spi_req *spi_req,
+ struct spi_master *master,
+ struct spi_message *msg,
+ struct spi_transfer *xfer)
+{
+ struct virtio_spi_priv *priv = spi_master_get_devdata(master);
+ struct device *dev = &priv->vdev->dev;
+ struct virtqueue *vq = priv->vqs[VIRTIO_SPI_QUEUE_RQ];
+ struct spi_device *spi = msg->spi;
+ struct spi_transfer_head *th;
+ struct scatterlist sg_out_head, sg_out_payload;
+ struct scatterlist sg_in_result, sg_in_payload;
+ struct scatterlist *sgs[4];
+ unsigned int outcnt = 0u;
+ unsigned int incnt = 0u;
+ int ret;
+
+ th = &spi_req->transfer_head;
+
+ /* Fill struct spi_transfer_head */
+ th->slave_id = spi->chip_select;
+ th->bits_per_word = spi->bits_per_word;
+ th->cs_change = xfer->cs_change;
+ th->tx_nbits = xfer->tx_nbits;
+ th->rx_nbits = xfer->rx_nbits;
+ th->reserve
Re: [virtio-dev] [PATCH v4] virtio-spi: add the device specification
Hi Mark,
For the "le16" type and byte ordering issue, Harald replies in
another email, let's mainly discuss about checking parameters and
exposing the backend supported features.
struct virtio_spi_transfer_head {
u8 chip_select;
u8 bits_per_word;
u8 cs_change;
u8 tx_nbits;
u8 rx_nbits;
u8 reserved[3];
le32 mode;
le32 freq;
le32 word_delay_ns;
le32 cs_setup_ns;
le32 cs_delay_hold_ns;
le32 cs_change_delay_inactive_ns;
};
For checking the parameters above in virtio_spi_transfer_head, I'd
like to add these field in config space:
1. bits_per_word_mask, in Linux spi driver,
__spi_validate_bits_per_word will use this field to validate
bits_per_word parameters for each transfer
2. cs_change_supported, 0 for unsupported and 1 for supported
3. tx_nbits and rx_nbits:
bit 0: 2-bit transfer supported;
bit 1: 4-bit transfer supported;
bit 2: 8-bit transfer supported;
other bits reserved as 0, and 1-bit transfer should always
supported.
4. mode_feature_supported:
bit 0-1: CPHA supported,
0b00: supports CPHA=0 and CPHA=1
0b01: only supports CPHA=0
0b10: only supports CPHA=1
0b11: invalid, should support as least one CPHA setting
bit 2-3: CPOL supported
0b00: supports CPOL=0 and CPOL=1
0b01: only supports CPOL=0
0b10: only supports CPOL=1
0b11: invalid, should support as least one CPOL setting
bit 4: CS_HIGH, if 1, supports chipselect active high, else
only supports chepselect active low.
bit 3: LSB_FIRST, if 0, only supports MSB first transfer, if 1,
supports LSB first transfer
bit 4: LOOP, if 1, support loopback mode, if 0, only supports
normal mode.
5. freq_max_speed: if non-zero, maximum clock rate support, in Hz
unit. if 0, no limitation.
6. max_word_delay_ns: if non-zero, the maximum word delay supported.
if 0, word delay is not supported to introduce.
7. max_delay_after_cs_asserted: if non-zero, the maximum cs setup
delay supported.if 0, cs setup delay is not supported to
introduce
8. max_delay_before_cs_deassert: if non-zero, the maximum
cs_delay_hold_ns delay supported.if 0, cs setup delay is
not supported to introduce
9. max_delay_after_cs_deassert: if non-zero, the maximum
cs_change_delay_inactive_ns delay supported.if 0, cs
setup delay is not supported to introduce
Driver Requirement：
If Virtio SPI device announce it doesn't support any feature, Virtio SPI
driver MUST reject the request if the corresponding feature field in
request header is not zero.
Virtio SPI driver MUST reject the request if the freq exceeds the
non-zero value of freq_max_speed filed in config space.
If any delay field in config space is set as non-zero, Virtio SPI driver
MUST reject the request if the corresponding delay in request header
exceeds the value in config space.
Do you think this mechanism, backend exposing its supported features and
abilities through config space so Virtio SPI driver can filter and check
before sending requests, is reasonable? And seems much stronger. A rule
to validate seems necessary because the parameters in request header may
differ in each transfer.
Looking forward to your advice and suggestion, if you agree that this
mechanism is better, I will add it in next patch. Thank you so much.
Best Regard
Haixu Cui
On 11/9/2023 12:04 AM, Mark Brown wrote:
On Wed, Nov 08, 2023 at 11:42:40PM +0800, Haixu Cui wrote:
On 11/6/2023 9:33 PM, Mark Brown wrote:
On Tue, Oct 24, 2023 at 08:53:46PM +0800, Haixu Cui wrote:
+ le16 bus_num;
+ le16 chip_select_max_number;
That's a *lot* of potential buses and chip selects...
Here you mean the types of bus_num and chip_select_max_number are "le16"?
Here I use 16 bits because bus_num and num_chipselect in spi_controller
structure are both 16 bits.
Yeah, I think that's more for padding/alignment reasons than anything
else. TBH I wondered if just going for a standard int might be better,
it's the combination of picking a smaller type but one that's relatively
large for the domain.
The \field{cs_timing_setting_enable} indicates if the host SPI controller
supports cs delay setting when performing transfer:
bit 0: delay after cs asserted, 0 means doesn't support and 1
means support;
bit 1: delay before cs deasserted, 0 means doesn't support and 1
means support;
bit 2: delay after cs deasserted, 0 means doesn't support and 1
means support;
other bits
Re: [virtio-dev] [PATCH v4] virtio-spi: add the device specification
On 11/9/2023 11:39 AM, Qiang Zhang wrote:
On Thu, Nov 09, 2023 at 10:52:06AM +0800, Haixu Cui wrote:
On 11/7/2023 3:40 PM, Qiang Zhang wrote:
On Tue, Oct 24, 2023 at 08:53:46PM +0800, Haixu Cui wrote:
virtio-spi is a virtual SPI master and it allows a guest to operate and
use the physical SPI master controlled by the host.
This patch adds the specification for virtio-spi.
Signed-off-by: Haixu Cui
---
device-types/spi/description.tex| 206
device-types/spi/device-conformance.tex | 7 +
device-types/spi/driver-conformance.tex | 7 +
3 files changed, 220 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 000..5dbceaf
--- /dev/null
+++ b/device-types/spi/description.tex
@@ -0,0 +1,206 @@
+\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 controlled by the host.
+
+virtio-spi has a single virtqueue. SPI transfer requests are placed into
+the virtqueue, and serviced by the physical SPI master.
+
+In a typical host and guest architecture with virtio-spi, Virtio SPI driver is
+the front-end existing in the guest kernel, and Virtio SPI device acts as the
+back-end in the host platform.
+
+\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 Virtio
SPI driver.
+
+\begin{lstlisting}
+struct virtio_spi_config {
+ le16 bus_num;
+ le16 chip_select_max_number;
+ le8 cs_timing_setting_enable;
+ le8 reserved[3];
+};
+\end{lstlisting}
+
+The \field{bus_num} indicates the physical SPI master assigned to guest.
Does this assume that a Virtio SPI controller always corresponds to a physical
SPI controller?
What if the backend SPI controller and SPI devices are fully emulated or the
SPI devices under the Virtio SPI controller come from multiple physical SPI
controllers?
Regards,
Qiang
Hi Qiang,
It's quite possible the host SPI controller is not physical, but
virtualized controller. In next patch, I will use "host SPI controller" to
replace "physical SPI controller", "host SPI controller" represents all kinds
of controller controlled by the host, which is more appropriate.
I think the meaning of "Host Controller" is a little bit opaque and is not
really necessary.
Hypervisor doesn't need to give guest an "id" of the Virtio SPI controller,
since this can be achieved by ACPI/DT in guest.
If guest needs to aware the topology of the backend, it's better to use
other mechanisms becuase it is board or configuration specific.
Hi Qiang,
Yes, bus_num is not necessary, hypervisor can maintain the mapping
relationship between the frontend and backend without bus_num parameter.
I will remove it in next patch.
A Virtio SPI controller corresponds with a host SPI controller, and the
guest can only access the devices under this host SPI controller, with the
assigned cs. For devices under other host controllers, the guest cannot
access.
We should allow the backend to emulate a SPI controller attached with physical
SPI devices from multiple physical SPI controllers. Anyway, this depends on
the backend implementation. We just give enough flexibility.
Here I'd like to use term "host SPI controller" to indicates the SPI
controller controlled by the host and binded with the virtio SPI
controller meanwhile. It may be a actual physical controller or may be
an emulated one.
Do you think this term is appropriate, with the explanation above added
in the spec? Or the statement "host SPI controlled devices" just like
virtio-i2c used is more acceptable? Looking forware to your advice.
Thank you so much.
Best Regards
Haixu Cui
Regards,
Qiang
Thank you for your findings and comments.
Best Regards
Haixu Cui
+
+The \field{chip_select_max_number} is the maximum number of chipselect the
physical SPI master supports.
+
+The \field{cs_timing_setting_enable} indicates if the physical SPI master
supporting cs timing setting:
+ 0: physical SPI master doesn't support cs timing setting;
+ 1: physical SPI master supports cs timing setting.
+
+The \field{reserved} is for alignment p
Re: [virtio-dev] [PATCH v4] virtio-spi: add the device specification
On 11/7/2023 3:40 PM, Qiang Zhang wrote:
On Tue, Oct 24, 2023 at 08:53:46PM +0800, Haixu Cui wrote:
virtio-spi is a virtual SPI master and it allows a guest to operate and
use the physical SPI master controlled by the host.
This patch adds the specification for virtio-spi.
Signed-off-by: Haixu Cui
---
device-types/spi/description.tex| 206
device-types/spi/device-conformance.tex | 7 +
device-types/spi/driver-conformance.tex | 7 +
3 files changed, 220 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 000..5dbceaf
--- /dev/null
+++ b/device-types/spi/description.tex
@@ -0,0 +1,206 @@
+\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 controlled by the host.
+
+virtio-spi has a single virtqueue. SPI transfer requests are placed into
+the virtqueue, and serviced by the physical SPI master.
+
+In a typical host and guest architecture with virtio-spi, Virtio SPI driver is
+the front-end existing in the guest kernel, and Virtio SPI device acts as the
+back-end in the host platform.
+
+\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 Virtio
SPI driver.
+
+\begin{lstlisting}
+struct virtio_spi_config {
+ le16 bus_num;
+ le16 chip_select_max_number;
+ le8 cs_timing_setting_enable;
+ le8 reserved[3];
+};
+\end{lstlisting}
+
+The \field{bus_num} indicates the physical SPI master assigned to guest.
Does this assume that a Virtio SPI controller always corresponds to a physical
SPI controller?
What if the backend SPI controller and SPI devices are fully emulated or the
SPI devices under the Virtio SPI controller come from multiple physical SPI
controllers?
Regards,
Qiang
Hi Qiang,
It's quite possible the host SPI controller is not physical, but
virtualized controller. In next patch, I will use "host SPI controller"
to replace "physical SPI controller", "host SPI controller" represents
all kinds of controller controlled by the host, which is more appropriate.
A Virtio SPI controller corresponds with a host SPI controller, and
the guest can only access the devices under this host SPI controller,
with the assigned cs. For devices under other host controllers, the
guest cannot access.
Thank you for your findings and comments.
Best Regards
Haixu Cui
+
+The \field{chip_select_max_number} is the maximum number of chipselect the
physical SPI master supports.
+
+The \field{cs_timing_setting_enable} indicates if the physical SPI master
supporting cs timing setting:
+ 0: physical SPI master doesn't support cs timing setting;
+ 1: physical SPI master supports cs timing setting.
+
+The \field{reserved} is for alignment purpose, also for future extension.
+
+\subsection{Device Initialization}\label{sec:Device Types / SPI Master Device
/ Device Initialization}
+
+\begin{enumerate}
+\item The Virtio SPI driver configures and initializes the virtqueue.
+\end{enumerate}
+
+\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}
+
+Virtio SPI driver enqueues requests to the virtqueue, and they are used by
+Virtio SPI device. Each request represents one SPI tranfer and is of the form:
+
+\begin{lstlisting}
+struct virtio_spi_transfer_head {
+u8 slave_id;
+u8 bits_per_word;
+u8 cs_change;
+u8 tx_nbits;
+u8 rx_nbits;
+u8 reserved[3];
+le32 mode;
+le32 freq;
+le32 word_delay_ns;
+le32 cs_setup_ns;
+le32 cs_delay_hold_ns;
+le32 cs_change_delay_inactive_ns;
+};
+\end{lstlisting}
+
+\begin{lstlisting}
+struct virtio_spi_transfer_result {
+u8 result;
+};
+\end{lstlisting}
+
+\begin{lstlisting}
+struct virtio_spi_transfer_req {
+struct virtio_spi_transfer_head head;
+u8 tx_buf[];
+u8 rx_buf[];
+struct virtio_spi_transfer_result result;
+};
+\end{lstlisting}
+
+The \field{slave_id} indicates the chipselect index the SPI transfer used.
+
Re: [virtio-dev] [PATCH v4] virtio-spi: add the device specification
Hi Mark,
Thank you for your comments, my response is below each of your
comments.
On 11/6/2023 9:33 PM, Mark Brown wrote:
On Tue, Oct 24, 2023 at 08:53:46PM +0800, Haixu Cui wrote:
virtio-spi is a virtual SPI master and it allows a guest to operate and
use the physical SPI master controlled by the host.
It would be good to avoid introducing new uses of this outdated
terminology, terms like controller are better. This is especially true
for specifications.
Yes! Will use "controller" instead of "master" in next patch.
It would be good to be copied on future versions of this.
+\begin{lstlisting}
+struct virtio_spi_config {
+ le16 bus_num;
+ le16 chip_select_max_number;
That's a *lot* of potential buses and chip selects...
Here you mean the types of bus_num and chip_select_max_number are "le16"?
Here I use 16 bits because bus_num and num_chipselect in spi_controller
structure are both 16 bits.
+The \field{cs_timing_setting_enable} indicates if the physical SPI master
supporting cs timing setting:
+ 0: physical SPI master doesn't support cs timing setting;
+ 1: physical SPI master supports cs timing setting.
This is very vauge - what exactly is meant by "cs timing setting"? If
we're specifying anything about timing it should probably be specific
about which paramters might be controlled and the constraints on how
they can be set. It's also a bit surprising that the only parameter
here is around chip select, there's generally a lot more sensitivity
around the main clock.
Here I would like to say the support of 3 types of cs delay, that is,
delay after cs asserted, delay before cs deasserted, delay after cs
deasserted.
I will update as follows:
The \field{cs_timing_setting_enable} indicates if the host SPI
controller supports cs delay setting when performing transfer:
bit 0: delay after cs asserted, 0 means doesn't support and 1
means support;
bit 1: delay before cs deasserted, 0 means doesn't support and 1
means support;
bit 2: delay after cs deasserted, 0 means doesn't support and 1
means support;
other bits are reserved and always set as 0.
+\begin{lstlisting}
+struct virtio_spi_transfer_head {
+u8 slave_id;
More outdated terminology.
+u8 bits_per_word;
+u8 cs_change;
+u8 tx_nbits;
+u8 rx_nbits;
+u8 reserved[3];
Indentation issue?
Yes, will fix in next patch.
+le32 mode;
+le32 freq;
+le32 word_delay_ns;
+le32 cs_setup_ns;
+le32 cs_delay_hold_ns;
+le32 cs_change_delay_inactive_ns;
All these parameters depend on controller support but weren't included
in the feature enumeration above and nothing in the spec seems to cover
what happens when they can't be supported exactly.
Add another return value:
#define VIRTIO_SPI_PARAM_ERR1
If the parameters in \field{virtio_spi_transfer_head} are not all valid,
or some fields are set as non-zero values but the corresponding features
are not supported by host, then the backend return VIRTIO_SPI_PARAM_ERR
to the frontend.
+The \field{cs_change} indicates whether to deselect device before starting the
+next SPI transfer, 0 means chipselect keep asserted and 1 means chipselect
deasserted
+then asserted again.
Note that this is *not* how Linux implements things, and it doesn't
include any specification of timing constraints.
+The \field{tx_nbits} indicates bus width for write transfer:
+0,1: bus width is 1, also known as SINGLE;
+ 2 : bus width is 2, also known as DUAL;
+ 4 : bus width is 4, also known as QUAD;
+ 8 : bus width is 8, also known as OCTAL;
+ other values are invalid.
Width here being in terms of bits.
Updated as:
0,1: 1-bit transfer, also known as SINGLE;
...
+The \field{tx_buf} is the buffer for data sent to the device.
+
+The \field{rx_buf} is the buffer for data received to the device.
In what format are these buffers presented? I note that the spec
supports more than one byte per word (and non-integer number of bytes).
In spi_transfer struct:
@len: size of rx and tx buffers (in bytes)
Although the bits_per_word can be any value in 0..32, in-memory
wordsizes are powers of two bytes (e.g. 20 bit samples use 32 bits).
So:
0 < bits_per_word <=8: one word occupies 1 byte in memory;
8 < bits_per_word <=16: one word occupies 2 bytes in memory;
16 < bits_per_word <=32: one word occupies 4 bytes in memory.
In the spec, the format of buffers are u8 array,
u8 tx_buf[];
u8 rx_buf[];
Thanks again for your comments and ideas.
Best Regards
Haixu Cui
-
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
[virtio-dev] Re: [PATCH v4] virtio-spi: add the device specification
Hi Harald,
Please refer to my following replies to your comments. Thank you
very much.
On 10/27/2023 9:02 PM, Harald Mommer wrote:
Hello Haixu,
this delay stuff causes some headache.
On 24.10.23 14:53, Haixu Cui wrote:
virtio-spi is a virtual SPI master and it allows a guest to operate and
use the physical SPI master controlled by the host.
This patch adds the specification for virtio-spi.
Signed-off-by: Haixu Cui
---
device-types/spi/description.tex | 206
device-types/spi/device-conformance.tex | 7 +
device-types/spi/driver-conformance.tex | 7 +
3 files changed, 220 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 000..5dbceaf
--- /dev/null
+++ b/device-types/spi/description.tex
@@ -0,0 +1,206 @@
+\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 controlled by the
host.
+
+virtio-spi has a single virtqueue. SPI transfer requests are placed into
+the virtqueue, and serviced by the physical SPI master.
+
+In a typical host and guest architecture with virtio-spi, Virtio SPI
driver is
+the front-end existing in the guest kernel, and Virtio SPI device
acts as the
+back-end in the host platform.
+
+\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 Virtio SPI driver.
+
+\begin{lstlisting}
+struct virtio_spi_config {
+ le16 bus_num;
+ le16 chip_select_max_number;
+ le8 cs_timing_setting_enable;
The naming "cs_timing_setting_enable" may be sub-optimal as also timings
which have nothing to do with CS (chip select) are affected. See below
where it's discussed in more detail.
For delay parameters(including cs delay setting), see below, a big topic.
+ le8 reserved[3];
There is no "le8". This is "u8".
yes! u8, i made a mistake
BTW, I currently in my Linux driver code announce support for 8 and 16
bit SPI word length out of the blue, 12500 bps transfer speed out of
the blue not knowing what my back end device really supports. In struct
spi_master the mode member is set to all kinds of bits hoping for the
best without really knowing whether the virtio SPI device supports all
of this.
For a first specification version this may be acceptable that there is
announced something based on nothing but I already see that the
information provided in the config space will not be the last word for
all times looking at my code.
I also consider more fields in config space, or introduce another
virtqueue to exchange some information between front and back, this will
let front-end knows more about the virtio SPI device. And this needs
more investigation.
+};
+\end{lstlisting}
+
+The \field{bus_num} indicates the physical SPI master assigned to guest.
+
+The \field{chip_select_max_number} is the maximum number of
chipselect the physical SPI master supports.
+
+The \field{cs_timing_setting_enable} indicates if the physical SPI
master supporting cs timing setting:
+ 0: physical SPI master doesn't support cs timing setting;
+ 1: physical SPI master supports cs timing setting.
+
+The \field{reserved} is for alignment purpose, also for future
extension.
+
+\subsection{Device Initialization}\label{sec:Device Types / SPI
Master Device / Device Initialization}
+
+\begin{enumerate}
+\item The Virtio SPI driver configures and initializes the virtqueue.
+\end{enumerate}
+
+\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}
+
+Virtio SPI driver enqueues requests to the virtqueue, and they are
used by
+Virtio SPI device. Each request represents one SPI tranfer and is of
the form:
+
+\begin{lstlisting}
+struct virtio_spi_transfer_head {
+ u8 slave_id;
+ u8 bits_per_word;
+ u8 cs_change;
+ u8 tx_nbits;
+ u8 rx_nbits;
+ u8 reserved[3];
You may not see it in your E-Mail client, but there is a tab in front of
"u8 reserved[3];" instead of spaces. This destroys the formatting of the
genera
[virtio-dev] Re: [PATCH v4] virtio-spi: add the device specification
Hi Harald, Cornelia,
I submit this patch v4 with some updates according to Harald's
comments.
Can you please help review this patch. If there are no major
problems, I think this patch can be merged as the initial version. And I
will upstream kernel code after this patch gets merged.
Thank you very much for your advice and support.
Best Regards
Haixu Cui
On 10/24/2023 8:53 PM, Haixu Cui wrote:
virtio-spi is a virtual SPI master and it allows a guest to operate and
use the physical SPI master controlled by the host.
This patch adds the specification for virtio-spi.
Signed-off-by: Haixu Cui
---
device-types/spi/description.tex| 206
device-types/spi/device-conformance.tex | 7 +
device-types/spi/driver-conformance.tex | 7 +
3 files changed, 220 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 000..5dbceaf
--- /dev/null
+++ b/device-types/spi/description.tex
@@ -0,0 +1,206 @@
+\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 controlled by the host.
+
+virtio-spi has a single virtqueue. SPI transfer requests are placed into
+the virtqueue, and serviced by the physical SPI master.
+
+In a typical host and guest architecture with virtio-spi, Virtio SPI driver is
+the front-end existing in the guest kernel, and Virtio SPI device acts as the
+back-end in the host platform.
+
+\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 Virtio
SPI driver.
+
+\begin{lstlisting}
+struct virtio_spi_config {
+ le16 bus_num;
+ le16 chip_select_max_number;
+ le8 cs_timing_setting_enable;
+ le8 reserved[3];
+};
+\end{lstlisting}
+
+The \field{bus_num} indicates the physical SPI master assigned to guest.
+
+The \field{chip_select_max_number} is the maximum number of chipselect the
physical SPI master supports.
+
+The \field{cs_timing_setting_enable} indicates if the physical SPI master
supporting cs timing setting:
+ 0: physical SPI master doesn't support cs timing setting;
+ 1: physical SPI master supports cs timing setting.
+
+The \field{reserved} is for alignment purpose, also for future extension.
+
+\subsection{Device Initialization}\label{sec:Device Types / SPI Master Device
/ Device Initialization}
+
+\begin{enumerate}
+\item The Virtio SPI driver configures and initializes the virtqueue.
+\end{enumerate}
+
+\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}
+
+Virtio SPI driver enqueues requests to the virtqueue, and they are used by
+Virtio SPI device. Each request represents one SPI tranfer and is of the form:
+
+\begin{lstlisting}
+struct virtio_spi_transfer_head {
+u8 slave_id;
+u8 bits_per_word;
+u8 cs_change;
+u8 tx_nbits;
+u8 rx_nbits;
+u8 reserved[3];
+le32 mode;
+le32 freq;
+le32 word_delay_ns;
+le32 cs_setup_ns;
+le32 cs_delay_hold_ns;
+le32 cs_change_delay_inactive_ns;
+};
+\end{lstlisting}
+
+\begin{lstlisting}
+struct virtio_spi_transfer_result {
+u8 result;
+};
+\end{lstlisting}
+
+\begin{lstlisting}
+struct virtio_spi_transfer_req {
+struct virtio_spi_transfer_head head;
+u8 tx_buf[];
+u8 rx_buf[];
+struct virtio_spi_transfer_result result;
+};
+\end{lstlisting}
+
+The \field{slave_id} indicates the chipselect index the SPI transfer used.
+
+The \field{bits_per_word} indicates the number of bits in each SPI transfer
word.
+
+The \field{cs_change} indicates whether to deselect device before starting the
+next SPI transfer, 0 means chipselect keep asserted and 1 means chipselect
deasserted
+then asserted again.
+
+The \field{tx_nbits} indicates bus width for write transfer:
+0,1: bus width is 1, also known as SINGLE;
+ 2 : bus width is 2, also known as DUAL;
+ 4 : bus width is 4, also known as QUAD;
+ 8 : bus width is 8, also known as OCTAL;
+ other values are invalid.
+
+The \field{rx_nbits}
[virtio-dev] [PATCH v4] virtio-spi: add the device specification
virtio-spi is a virtual SPI master and it allows a guest to operate and
use the physical SPI master controlled by the host.
This patch adds the specification for virtio-spi.
Signed-off-by: Haixu Cui
---
device-types/spi/description.tex| 206
device-types/spi/device-conformance.tex | 7 +
device-types/spi/driver-conformance.tex | 7 +
3 files changed, 220 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 000..5dbceaf
--- /dev/null
+++ b/device-types/spi/description.tex
@@ -0,0 +1,206 @@
+\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 controlled by the host.
+
+virtio-spi has a single virtqueue. SPI transfer requests are placed into
+the virtqueue, and serviced by the physical SPI master.
+
+In a typical host and guest architecture with virtio-spi, Virtio SPI driver is
+the front-end existing in the guest kernel, and Virtio SPI device acts as the
+back-end in the host platform.
+
+\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 Virtio
SPI driver.
+
+\begin{lstlisting}
+struct virtio_spi_config {
+ le16 bus_num;
+ le16 chip_select_max_number;
+ le8 cs_timing_setting_enable;
+ le8 reserved[3];
+};
+\end{lstlisting}
+
+The \field{bus_num} indicates the physical SPI master assigned to guest.
+
+The \field{chip_select_max_number} is the maximum number of chipselect the
physical SPI master supports.
+
+The \field{cs_timing_setting_enable} indicates if the physical SPI master
supporting cs timing setting:
+ 0: physical SPI master doesn't support cs timing setting;
+ 1: physical SPI master supports cs timing setting.
+
+The \field{reserved} is for alignment purpose, also for future extension.
+
+\subsection{Device Initialization}\label{sec:Device Types / SPI Master Device
/ Device Initialization}
+
+\begin{enumerate}
+\item The Virtio SPI driver configures and initializes the virtqueue.
+\end{enumerate}
+
+\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}
+
+Virtio SPI driver enqueues requests to the virtqueue, and they are used by
+Virtio SPI device. Each request represents one SPI tranfer and is of the form:
+
+\begin{lstlisting}
+struct virtio_spi_transfer_head {
+u8 slave_id;
+u8 bits_per_word;
+u8 cs_change;
+u8 tx_nbits;
+u8 rx_nbits;
+u8 reserved[3];
+le32 mode;
+le32 freq;
+le32 word_delay_ns;
+le32 cs_setup_ns;
+le32 cs_delay_hold_ns;
+le32 cs_change_delay_inactive_ns;
+};
+\end{lstlisting}
+
+\begin{lstlisting}
+struct virtio_spi_transfer_result {
+u8 result;
+};
+\end{lstlisting}
+
+\begin{lstlisting}
+struct virtio_spi_transfer_req {
+struct virtio_spi_transfer_head head;
+u8 tx_buf[];
+u8 rx_buf[];
+struct virtio_spi_transfer_result result;
+};
+\end{lstlisting}
+
+The \field{slave_id} indicates the chipselect index the SPI transfer used.
+
+The \field{bits_per_word} indicates the number of bits in each SPI transfer
word.
+
+The \field{cs_change} indicates whether to deselect device before starting the
+next SPI transfer, 0 means chipselect keep asserted and 1 means chipselect
deasserted
+then asserted again.
+
+The \field{tx_nbits} indicates bus width for write transfer:
+0,1: bus width is 1, also known as SINGLE;
+ 2 : bus width is 2, also known as DUAL;
+ 4 : bus width is 4, also known as QUAD;
+ 8 : bus width is 8, also known as OCTAL;
+ other values are invalid.
+
+The \field{rx_nbits} indicates bus width for read transfer:
+0,1: bus width is 1, also known as SINGLE;
+ 2 : bus width is 2, also known as DUAL;
+ 4 : bus width is 4, also known as QUAD;
+ 8 : bus width is 8, also known as OCTAL;
+ other values are invalid.
+
+The \field{reserved} is for alignement, also for further extension.
+
+The \field{mode} indicates how data is clocked out and in. Bit definitions as
fo
[virtio-dev] [PATCH] [PATCH v3] virtio-spi: add the device specification
virtio-spi is a virtual SPI master and it allows a guest to operate and
use the physical SPI master controlled by the host.
This patch adds the specification for virtio-spi.
Signed-off-by: Haixu Cui
---
device-types/spi/description.tex| 206
device-types/spi/device-conformance.tex | 7 +
device-types/spi/driver-conformance.tex | 7 +
3 files changed, 220 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 000..5dbceaf
--- /dev/null
+++ b/device-types/spi/description.tex
@@ -0,0 +1,206 @@
+\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 controlled by the host.
+
+virtio-spi has a single virtqueue. SPI transfer requests are placed into
+the virtqueue, and serviced by the physical SPI master.
+
+In a typical host and guest architecture with virtio-spi, Virtio SPI driver is
+the front-end existing in the guest kernel, and Virtio SPI device acts as the
+back-end in the host platform.
+
+\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 Virtio
SPI driver.
+
+\begin{lstlisting}
+struct virtio_spi_config {
+ le16 bus_num;
+ le16 chip_select_max_number;
+ le8 cs_timing_setting_enable;
+ le8 reserved[3];
+};
+\end{lstlisting}
+
+The \field{bus_num} indicates the physical SPI master assigned to guest.
+
+The \field{chip_select_max_number} is the maximum number of chipselect the
physical SPI master supports.
+
+The \field{cs_timing_setting_enable} indicates if the physical SPI master
supporting cs timing setting:
+ 0: physical SPI master doesn't support cs timing setting;
+ 1: physical SPI master supports cs timing setting.
+
+The \field{reserved} is for alignment purpose, also for future extension.
+
+\subsection{Device Initialization}\label{sec:Device Types / SPI Master Device
/ Device Initialization}
+
+\begin{enumerate}
+\item The Virtio SPI driver configures and initializes the virtqueue.
+\end{enumerate}
+
+\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}
+
+Virtio SPI driver enqueues requests to the virtqueue, and they are used by
+Virtio SPI device. Each request represents one SPI tranfer and is of the form:
+
+\begin{lstlisting}
+struct virtio_spi_transfer_head {
+u8 slave_id;
+u8 bits_per_word;
+u8 cs_change;
+u8 tx_nbits;
+u8 rx_nbits;
+ u8 reserved[3];
+le32 mode;
+le32 freq;
+le32 word_delay_ns;
+le32 cs_setup_ns;
+le32 cs_delay_hold_ns;
+le32 cs_change_delay_inactive_ns;
+};
+\end{lstlisting}
+
+\begin{lstlisting}
+struct virtio_spi_transfer_result {
+u8 result;
+};
+\end{lstlisting}
+
+\begin{lstlisting}
+struct virtio_spi_transfer_req {
+struct virtio_spi_transfer_head head;
+u8 tx_buf[];
+u8 rx_buf[];
+struct virtio_spi_transfer_result result;
+};
+\end{lstlisting}
+
+The \field{slave_id} indicates the chipselect index the SPI transfer used.
+
+The \field{bits_per_word} indicates the number of bits in each SPI transfer
word.
+
+The \field{cs_change} indicates whether to deselect device before starting the
+next SPI transfer, 0 means chipselect keep asserted and 1 means chipselect
deasserted
+then asserted again.
+
+The \field{tx_nbits} indicates bus width for write transfer:
+0,1: bus width is 1, also known as SINGLE;
+ 2 : bus width is 2, also known as DUAL;
+ 4 : bus width is 4, also known as QUAD;
+ 8 : bus width is 8, also known as OCTAL;
+ other values are invalid.
+
+The \field{rx_nbits} indicates bus width for read transfer:
+0,1: bus width is 1, also known as SINGLE;
+ 2 : bus width is 2, also known as DUAL;
+ 4 : bus width is 4, also known as QUAD;
+ 8 : bus width is 8, also known as OCTAL;
+ other values are invalid.
+
+The \field{reserved} is for alignement, also for further extension.
+
+The \field{mode} indicates how data is clocked out and in. Bit definitions as
fo
[virtio-dev] Re: [PATCH v3] virtio-spi: add the device specification
Hello Harald Mommer,
Thank you so much for your comments and please refer to my
following reply.
On 9/6/2023 9:50 PM, Harald Mommer wrote:
Hello Haixu Cui,
On 01.09.23 05:29, Haixu Cui wrote:
virtio-spi is a virtual SPI master and it allows a guset to operate and
guest
Yes, spell error.
use the physical SPI master controlled by the host.
This patch adds the specification for virtio-spi.
Signed-off-by: Haixu Cui
---
device-types/spi/description.tex | 191
device-types/spi/device-conformance.tex | 7 +
device-types/spi/driver-conformance.tex | 7 +
3 files changed, 205 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 000..c35826b
--- /dev/null
+++ b/device-types/spi/description.tex
@@ -0,0 +1,191 @@
+\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 controlled by the
host.
+
+virtio-spi has a single virtqueue. SPI transfer requests are placed into
+the virtqueue, and serviced by the physical SPI master.
+
+In a typical host and guest architecture with virtio-spi, Virtio SPI
driver is
+the front-end existing in the guest kernel, and Virtio SPI device
acts as the
+back-end in the host platform.
+
+\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 Virtio SPI driver.
+
+\begin{lstlisting}
+struct virtio_spi_config {
+ le32 bus_num;
Just a remark: In some environments (Linux) not the complete value range
of bus_num can be used. For example in Linux 0 <= bus_num <= S16_MAX.
+ le32 chip_select_max_number;
Just a remark: In some environments (Linux) not the complete value range
of chip_select_max_number can be used. For example in Linux 0 <= bus_num
<= U16_MAX.
And subsequently slave_id is an u8 and must be in the range
0..chip_select_max_number - 1.
If wanted, a le16 for both fields may be considered sufficient. We are
hopefully not this scarce on bytes, so it does not really matter. I just
wanted to mention especially for the 2nd field here.
In spi_controller structure, bus_num and number_chipselect are both 16
bits, so le16 is enough. Will update.
+};
+\end{lstlisting}
+
+The \field{bus_num} indicates the physical SPI master assigned to
guset, and this is SOC-specific.
guest. And why is this SOC-specific? On Linux this is the 1234 in
/dev/spidev1234.x when bus_num is set to 1234 by the virtio device. So
it's purpose is to distinguish the different /dev/spidev when more than
only a single virtio SPI device is provided to the driver guest. But
SOC-specific?
Yes, this is set by the back-end. "SOC-specific" is not appropriate.
Will remove it.
+
+The \field{chip_select_max_number} is the maximum number of
chipselect the physical SPI master supports.
Was without "maximum" in the text of the last version. What should
happen in my Linux driver implementation is that there should be exactly
this number of /dev/spidev1234.x device files. with x =
0..chip_select_max_number -1.
Well, so if your back-end set this filed to 1, then your virtual spi is
/dev/spidev1234.1?
But how do you know spi master supports how many chipselect lines? I
think num_chipselect in spi_controller must be set correctly otherwise
it will return -EINVAL when running spi_register_controller.
+
+\subsection{Device Initialization}\label{sec:Device Types / SPI
Master Device / Device Initialization}
+
+\begin{enumerate}
+\item The Virtio SPI driver configures and initializes the virtqueue.
+\end{enumerate}
+
+\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}
+
+Virtio SPI driver enqueues requests to the virtqueue, and they are
used by
+Virtio SPI device. Each request represents one SPI tranfer and is of
the form:
+
+\begin{lstlisting}
+struct virtio_spi_transfer_head {
+ u8 slave_id;
+ u8 bits_per_word;
+ u8 cs_change;
+ u8 tx_nbits;
+ u8 rx_nbits;
As already mentioned, u8 reserved[3] missing here not necessarily for
[virtio-dev] [PATCH v3] virtio-spi: add the device specification
virtio-spi is a virtual SPI master and it allows a guset to operate and
use the physical SPI master controlled by the host.
This patch adds the specification for virtio-spi.
Signed-off-by: Haixu Cui
---
device-types/spi/description.tex| 191
device-types/spi/device-conformance.tex | 7 +
device-types/spi/driver-conformance.tex | 7 +
3 files changed, 205 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 000..c35826b
--- /dev/null
+++ b/device-types/spi/description.tex
@@ -0,0 +1,191 @@
+\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 controlled by the host.
+
+virtio-spi has a single virtqueue. SPI transfer requests are placed into
+the virtqueue, and serviced by the physical SPI master.
+
+In a typical host and guest architecture with virtio-spi, Virtio SPI driver is
+the front-end existing in the guest kernel, and Virtio SPI device acts as the
+back-end in the host platform.
+
+\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 Virtio
SPI driver.
+
+\begin{lstlisting}
+struct virtio_spi_config {
+ le32 bus_num;
+ le32 chip_select_max_number;
+};
+\end{lstlisting}
+
+The \field{bus_num} indicates the physical SPI master assigned to guset, and
this is SOC-specific.
+
+The \field{chip_select_max_number} is the maximum number of chipselect the
physical SPI master supports.
+
+\subsection{Device Initialization}\label{sec:Device Types / SPI Master Device
/ Device Initialization}
+
+\begin{enumerate}
+\item The Virtio SPI driver configures and initializes the virtqueue.
+\end{enumerate}
+
+\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}
+
+Virtio SPI driver enqueues requests to the virtqueue, and they are used by
+Virtio SPI device. Each request represents one SPI tranfer and is of the form:
+
+\begin{lstlisting}
+struct virtio_spi_transfer_head {
+u8 slave_id;
+u8 bits_per_word;
+u8 cs_change;
+u8 tx_nbits;
+u8 rx_nbits;
+le32 mode;
+le32 freq;
+le32 word_delay_ns;
+le32 cs_setup_ns;
+le32 cs_delay_hold_ns;
+le32 cs_change_delay_inactive_ns;
+};
+\end{lstlisting}
+
+\begin{lstlisting}
+struct virtio_spi_transfer_result {
+u8 result;
+};
+\end{lstlisting}
+
+\begin{lstlisting}
+struct virtio_spi_transfer_req {
+struct virtio_spi_transfer_head head;
+u8 tx_buf[];
+u8 rx_buf[];
+struct virtio_spi_transfer_result result;
+};
+\end{lstlisting}
+
+The \field{slave_id} indicates the chipselect index the SPI transfer used.
+
+The \field{bits_per_word} indicates the number of bits in each SPI transfer
word.
+
+The \field{cs_change} indicates whether to deselect device before starting the
+next SPI transfer, 0 means chipselect keep asserted and 1 means chipselect
deasserted
+then asserted again.
+
+The \field{tx_nbits} indicates bus width for write transfer:
+0,1: bus width is 1, also known as SINGLE;
+ 2 : bus width is 2, also known as DUAL;
+ 4 : bus width is 4, also known as QUAD;
+ 8 : bus width is 8, also known as OCTAL;
+ other values are invalid.
+
+The \field{rx_nbits} indicates bus width for read transfer:
+0,1: bus width is 1, also known as SINGLE;
+ 2 : bus width is 2, also known as DUAL;
+ 4 : bus width is 4, also known as QUAD;
+ 8 : bus width is 8, also known as OCTAL;
+ other values are invalid.
+
+The \field{mode} indicates how data is clocked out and in. Bit definitions as
follows:
+bit 0: CPHA, determines the timing (i.e. phase) of the data bits
+ relative to the clock pulses.
+bit 1: CPOL, determines the polarity of the clock.
+bit 2: CS_HIGH, if 1, chipselect active high, else active low.
+ bit 3: LSB_FIRST, determines per-word bits-on-wire, if 0, MSB
+ first, else LSB first.
+ bit 4: LOOP, if 1, device is in loopback mode, else normal mode.
+
+The
Re: [virtio-dev][PATCH 2/2] virtio-spi: add the device specification
Hi Harald Mommer,
Thank you for your comments and please refer to my following replies.
On 8/10/2023 6:40 PM, Harald Mommer wrote:
Hello,
a quick incomplete on. I'm currently with both hands in an attempt to
implement a virtio SPI device for our proprietary hypervisor based on
the draft specification and your E-Mail. Means I see now some more
things while implementing.
u32 len; /* @len: transfer length.*/
is this a byte or a word count?
The comment in Linux for the length field in struct spi_ioc_transfer is
/* @len: Length of tx and rx buffers, in bytes. */ so I assume this here
is also a byte count.
As we have only one len I think it's still needed to look at the device
readable and device writable descriptor sizes to decide on half duplex
read, half duplex write or full duplex. Having still to do this the
transfer length in the len field may be redundant (superfluous)
information.
"len" is byte count.
You are right, "len" parameter seems redundant. Virtqueue used to pass
parameters between front-end and back-end and its descriptor is defined
as follows(refer to:
https://docs.oasis-open.org/virtio/virtio/v1.2/csd01/listings/virtio_queue.h):
struct virtq_desc {
/* Address (guest-physical). */
le64 addr;
/* Length. */
le32 len;
/* The flags as indicated above. */
le16 flags;
/* We chain unused descriptors via this, too */
le16 next;
};
For the rx_buf or tx_buf descriptor, len member shows the transfer
length, so it is not necessary to pass "len" in the head structure.
I will remove "len" in next version.
No problem with this, I'm now only at a point where I want to be sure
whether this is meant as a byte length (vs. a word length).
Then there is no u32. There is le32. Only RPMB uses be32 but they have a
special reason to do this. The byte order must be defined for 16 and 32
bit values!
Yes! Use "le32" instead of "u32" in next patch.
On 20.07.23 09:50, Haixu Cui wrote:
Hi Harald Mommer,
Thank you so much for all your helpful advice and info!
I have updated the transfer request as follows:
struct spi_transfer_head {
u8 slave_id;
u8 bits_per_word;
u8 cs_change;
u8 tx_nbits;
u8 rx_nbits;
u8 reserved[3];
u32 len;
u32 mode;
u32 freq;
u32 word_delay_ns;
u32 cs_setup_ns;
u32 cs_delay_hold_ns;
u32 cs_change_delay_inactive_ns;
};
struct spi_transfer_end {
u8 result;
};
May become "struct spi_transfer_result result" for naming reasons with
same content, see below. Just a proposal which may not be followed, see
below.
struct virtio_spi_transfer_req {
struct spi_transfer_head head;
u8 rx_buf[];
u8 tx_buf[];
struct spi_end end;
Above this was "struct spi_transfer_end"
};
Agreed! Will change to "struct spi_transfer_result".
Device readable must go before device writable. So rx_buf[] and tx_buf[]
still have to be swapped.
Yes, rx_buf and tx_buf should be swapped.
I need to separate struct virtio_spi_transfer_req in my C implementation to
struct virtio_spi_transfer_req_out { /* Device readable */
struct spi_transfer_head head;
u8 tx_buf[]; /* Variable array at the end of the structure, gcc is
happy */
};
struct virtio_spi_transfer_req_in { /* Device writable */
u8 rx_buf[];
/* "struct spi_transfer_end result;" is behind rx_buf but variable
array must be last element for gcc for reasons */
};
Means you have to calculate the address where the result code is to be
written from some length information. Can be done. But then I should be
sure about the address. And this I can only be after all the length
information (head, device writable) are checked for consistency. Clumsy
and asking for mistakes.
However what also could be done (but you may have to obey alignment
requirement for rx_buf[] when words are transferred and may have to add
some padding in "struct spi_transfer_result", I don't know this currently):
struct virtio_spi_transfer_req_in { /* Device writable */
struct spi_transfer_result result; /* The result code is the 1st
device writable byte */
u8 rx_buf[];
};
With this definition there was no need to calculate the address of the
result byte. Just a thought to make life easier.
As I just mentioned, front-end sends the buffer base address and
transfer length to the back-end using virtq_desc structure, rather than
sending the data directly.
And the virtq_desc length is always 16 bytes, so there has nothing to do
with the sending order.
Also I add the member and field definition as follows:
@slave_id: chipselect index the SPI transfer used.
@bits_per_word: the number of bits in each SPI
Re: [virtio-dev][PATCH 2/2] virtio-spi: add the device specification
Hello Harald Mommer, I've searched but didn't found opensource virtio SPI Linux driver or any document/spec about this. We implement the virtio SPI prototype, based on the third-party non-opensource hypervisor. Thanks & Best Regards Haixu Cui On 7/21/2023 9:50 PM, Harald Mommer wrote: Hello, is there already some virtio SPI Linux driver published to the public to have a chance to look at? Same question for the device side. Is there a qemu device (or something for a different virtualization environment like kvmtool) already published to the public anywhere? The spec made the impression that it's in an early stage so I expect there is nothing yet but I may be wrong with my assumption. 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 Regards Harald Mommer - To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
Re: [virtio-dev][PATCH 2/2] virtio-spi: add the device specification
Hi Harald Mommer,
Thank you so much for all your helpful advice and info!
I have updated the transfer request as follows:
struct spi_transfer_head {
u8 slave_id;
u8 bits_per_word;
u8 cs_change;
u8 tx_nbits;
u8 rx_nbits;
u8 reserved[3];
u32 len;
u32 mode;
u32 freq;
u32 word_delay_ns;
u32 cs_setup_ns;
u32 cs_delay_hold_ns;
u32 cs_change_delay_inactive_ns;
};
struct spi_transfer_end {
u8 result;
};
struct virtio_spi_transfer_req {
struct spi_transfer_head head;
u8 rx_buf[];
u8 tx_buf[];
struct spi_end end;
};
Also I add the member and field definition as follows:
@slave_id: chipselect index the SPI transfer used.
@bits_per_word: the number of bits in each SPI transfer word.
@cs_change: whether to deselect device after finishing this transfer
before starting the next transfer, 0 means cs keep asserted and
1 means cs deasserted then asserted again.
@tx_nbits: bus width for write transfer.
0,1: bus width is 1, also known as SINGLE
2 : bus width is 2, also known as DUAL
4 : bus width is 4, also known as QUAD
8 : bus width is 8, also known as OCTAL
other values are invalid.
@rx_nbits: bus width for read transfer.
0,1: bus width is 1, also known as SINGLE
2 : bus width is 2, also known as DUAL
4 : bus width is 4, also known as QUAD
8 : bus width is 8, also known as OCTAL
other values are invalid.
@reserved: for future use.
@len: transfer length.
@mode: SPI transfer mode.
bit 0: CPHA, determines the timing (i.e. phase) of the data
bits relative to the clock pulses.For CPHA=0, the
"out" side changes the data on the trailing edge of the
preceding clock cycle, while the "in" side captures the data
on (or shortly after) the leading edge of the clock cycle.
For CPHA=1, the "out" side changes the data on the leading
edge of the current clock cycle, while the "in" side
captures the data on (or shortly after) the trailing edge of
the clock cycle.
bit 1: CPOL, determines the polarity of the clock. CPOL=0 is a
clock which idles at 0, and each cycle consists of a pulse
of 1. CPOL=1 is a clock which idles at 1, and each cycle
consists of a pulse of 0.
bit 2: CS_HIGH, if 1, chip select active high, else active low.
bit 3: LSB_FIRST, determines per-word bits-on-wire, if 0, MSB
first, else LSB first.
bit 4: LOOP, loopback mode.
@freq: the transfer speed in Hz.
@word_delay_ns: delay to be inserted between consecutive words of a
transfer, in ns unit.
@cs_setup_ns: delay to be introduced after CS is asserted, in ns
unit.
@cs_delay_hold_ns: delay to be introduced before CS is deasserted
for each transfer, in ns unit.
@cs_change_delay_inactive_ns: delay to be introduced after CS is
deasserted and before next asserted, in ns unit.
Could you please help review the transfer request above again to
check if the interface is clear and enough for back-end to perform SPI
transfers. Thank you again for your comments.
Best Regards
Haixu Cui
On 7/19/2023 2:25 AM, Harald Mommer wrote:
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 000..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 ad
Re: [virtio-dev][PATCH 2/2] virtio-spi: add the device specification
Hi Jonathon Reinhart,
Thank you very much for your guidance. It is indeed an excellent
idea to combine the parameters which take effect at the same phase.
So the front-end & back-end interface updated as follows:
struct spi_transfer_head {
u8 slave_id;
u8 bits_per_word;
u8 cs_change;
u8 tx_nbits;
u8 rx_nbits;
u8 reserved[3];
u32 len;
u32 mode;
u32 freq;
u32 word_delay_ns;
u32 cs_setup_ns;
u32 cs_delay_hold_ns;
u32 cs_change_delay_inactive_ns;
};
@cs_delay_hold_ns: delay to be introduced before CS is deasserted
for each transfer, in ns unit. (spi_device->cs_hold and
spi_transfer->delay added up)
@cs_change_delay_inactive_ns: delay to be introduced after CS is
deasserted and before next asserted, in ns unit. It will be executed
only if the cs_change is set and the transfer is not the last one.
(spi_device->cs_inactive and spi_transfer->cs_change_delay added up)
Best Regards & Thanks
Haixu Cui
On 7/18/2023 12:19 AM, Jonathon Reinhart wrote:
On Mon, Jul 17, 2023 at 10:53 AM Haixu Cui wrote:
Hi Jonathon Reinhart,
Thank you very much for your comments.
On 7/11/2023 12:42 AM, Jonathon Reinhart wrote:
On Fri, Jul 7, 2023 at 3:21 AM Haixu Cui wrote:
Hi Jonathon Reinhart,
Thank you so much for all your helpful advice and info!
I took a look at latest Linux SPI driver and found, for
cs_setup/cs_hold/cs_inactive set in device-tree, there are following two
conditions:
1) if SPI controller supports CS timing configuration and CS is not
using a GPIO line, then the SPI driver set the
cs_setup/cs_hold/ca_inactive values into the corresponding SPI CS registers;
2) if CS is using a GPIO line, or SPI controller doesn't support CS
timing configuration, it is the software to perform the
cs_setup/cs_hold/cs_inactive delays, which is implemented in function
spi_set_cs in driver/spi/spi.c.
So I agree it is necessary to pass cs_setup/cs_hold/cs_inactive to
the host for each transfer.
For condition 1, host should set these values into the CS timing
registers. And as you mentioned "one might require different CS
setup/hold times, depending on which slave_id they are talking to (on
the same bus)", if so, host need to overwrite the CS timing registers
between the two transfers talking to different salve_id.
For condition 2, SPI driver running in the host performing the
cs_setup/cs_hold/cs_inactive delays seems more accurate, compared with
performing delays in guest.
And the latest virtio spi transfer structure is defined as follows:
struct spi_transfer_head {
u8 slave_id;
u8 bits_per_word;
u8 cs_change;
u8 tx_nbits;
u8 rx_nbits;
u8 reserved[3];
u32 mode;
u32 freq;
u32 word_delay_ns;
u32 delay_ns;
u32 cs_change_delay_ns;
u32 cs_setup_ns;
u32 cs_hold_ns;
u32 cs_inactive_ns;
};
Hello Haixu Cui,
I think there may be some unnecessary redundancy in these fields. See below.
@slave_id: chipselect index the SPI transfer used
@bits_per_word: the number of bits in each SPI transfer word
@cs_change: True to deselect device before starting the next transfer
@tx_nbits: number of bits used for writing
@rx_nbits: number of bits used for reading
@reserved: reserved for future use
@mode: the spi mode defines how data is clocked out and in
@freq: transfer speed
@word_delay_ns: delay to be inserted between consecutive words of
a transfer, in ns unit
@cs_setup_ns: delay to be introduced by the controller after CS is
asserted, in ns unit
(I am reordering these in my quoted text to be grouped appropriately.)
@delay_ns: delay to be introduced after this transfer before
(optionally) changing the chipselect status, in ns unit
@cs_hold_ns: delay to be introduced by the controller before CS is
deasserted, in ns unit
Aren't @delay_ns and @cs_hold_ns specifying the same thing?
I think they are not the same thing, delay_ns is the spi transfer
property while cs_hold_ns is the spi device property， although they take
effect at the same stage.
I see. I think we have differing perspectives here.
I assume that you are looking at this from the perspective of a Linux
guest on a Linux host, where virtio-spi is connecting a virtual spi
driver in the guest to a hardware spi driver on the host. In this
case, it makes sense to have parity between the fields in Linux
spi_device / spi_transfer and the fields in the virtio
spi_transfer_head. It makes the implementation easier if there is a
simple 1:1 mapping between them, even if you have to copy some
spi_transfer_head fields to spi_device (like the cs_ fields).
My
Re: [virtio-dev][PATCH 2/2] virtio-spi: add the device specification
Hi Jonathon Reinhart,
Thank you very much for your comments.
On 7/11/2023 12:42 AM, Jonathon Reinhart wrote:
On Fri, Jul 7, 2023 at 3:21 AM Haixu Cui wrote:
Hi Jonathon Reinhart,
Thank you so much for all your helpful advice and info!
I took a look at latest Linux SPI driver and found, for
cs_setup/cs_hold/cs_inactive set in device-tree, there are following two
conditions:
1) if SPI controller supports CS timing configuration and CS is not
using a GPIO line, then the SPI driver set the
cs_setup/cs_hold/ca_inactive values into the corresponding SPI CS registers;
2) if CS is using a GPIO line, or SPI controller doesn't support CS
timing configuration, it is the software to perform the
cs_setup/cs_hold/cs_inactive delays, which is implemented in function
spi_set_cs in driver/spi/spi.c.
So I agree it is necessary to pass cs_setup/cs_hold/cs_inactive to
the host for each transfer.
For condition 1, host should set these values into the CS timing
registers. And as you mentioned "one might require different CS
setup/hold times, depending on which slave_id they are talking to (on
the same bus)", if so, host need to overwrite the CS timing registers
between the two transfers talking to different salve_id.
For condition 2, SPI driver running in the host performing the
cs_setup/cs_hold/cs_inactive delays seems more accurate, compared with
performing delays in guest.
And the latest virtio spi transfer structure is defined as follows:
struct spi_transfer_head {
u8 slave_id;
u8 bits_per_word;
u8 cs_change;
u8 tx_nbits;
u8 rx_nbits;
u8 reserved[3];
u32 mode;
u32 freq;
u32 word_delay_ns;
u32 delay_ns;
u32 cs_change_delay_ns;
u32 cs_setup_ns;
u32 cs_hold_ns;
u32 cs_inactive_ns;
};
Hello Haixu Cui,
I think there may be some unnecessary redundancy in these fields. See below.
@slave_id: chipselect index the SPI transfer used
@bits_per_word: the number of bits in each SPI transfer word
@cs_change: True to deselect device before starting the next transfer
@tx_nbits: number of bits used for writing
@rx_nbits: number of bits used for reading
@reserved: reserved for future use
@mode: the spi mode defines how data is clocked out and in
@freq: transfer speed
@word_delay_ns: delay to be inserted between consecutive words of
a transfer, in ns unit
@cs_setup_ns: delay to be introduced by the controller after CS is
asserted, in ns unit
(I am reordering these in my quoted text to be grouped appropriately.)
@delay_ns: delay to be introduced after this transfer before
(optionally) changing the chipselect status, in ns unit
@cs_hold_ns: delay to be introduced by the controller before CS is
deasserted, in ns unit
Aren't @delay_ns and @cs_hold_ns specifying the same thing?
I think they are not the same thing, delay_ns is the spi transfer
property while cs_hold_ns is the spi device property， although they take
effect at the same stage.
I list 4 conditions, here transfer cs delay including
spi_transfer->delay and spi_transfer->cs_change_delay, and device cs
delay including spi_device->cs_hold, spi_device->cs_setup and
spi_device->cs_inactive.
condition 1:
virtio-spi controller only has transfer_one interface but no
transfer_one_message interface, and spi_transfer_one_message is the
default transfer_one_message interface of virtio-spi controller.
Hardware SPI controller doesn't support CS timing configuration.
In this case, both transfer cs delay and device cs delay are
executed by software in spi_transfer_one_message function in guest Linux
OS. So guest doesn't need pass these cs timing parameters to host.
condition 2:
virtio-spi controller only has transfer_one interface but no
transfer_one_message interface, and spi_transfer_one_message is the
default transfer_one_message interface of virtio-spi controller.
Hardware SPI controller supports device CS timing configuration,
which means it has registers to hold these configuration values.
In this case, transfer cs delay is executed in
spi_transfer_one_message function, and guest need pass device cs delay
to host. Because one SPI number may have more than one slave, these
slaves also may have different device cs delay values, so for each
transfer, guest should pass device cs delay along with the slave_id to
host to overwrite the corresponding registers.
condition 3:
virtio-spi controller has transfer_one_message interface but no
transfer_one interface.
Hardware SPI controller doesn't support CS timing configuration.
In this case, host SPI driver should implement all cs delay
operations with the transfer cs delay and device cs delay received from
the g
Re: [virtio-dev][PATCH 1/2] virtio-spi: define the DEVICE ID for virtio SPI master
Hi Michael S. Tsirkin, Cornelia Huck,
I have created an issue
https://github.com/oasis-tcs/virtio-spec/issues/174 to request Device ID
45 for SPI master. Please help to deal with it, thank you very much.
Best Regards
Haixu Cui
On 6/30/2023 10:57 PM, Michael S. Tsirkin wrote:
On Mon, Apr 17, 2023 at 10:03:52PM +0800, Haixu Cui wrote:
Define the DEVICE ID of virtio SPI master device as 45.
It does not looks like patch 2 will make it in time for 1.3
but should we vote on reserving device id maybe?
If yes pls create a github issue and request vote on list.
---
content.tex | 2 ++
1 file changed, 2 insertions(+)
diff --git a/content.tex b/content.tex
index cff548a..29f2859 100644
--- a/content.tex
+++ b/content.tex
@@ -682,6 +682,8 @@ \chapter{Device Types}\label{sec:Device Types}
\hline
44 & ISM device \\
\hline
+45 & SPI master \\
+\hline
\end{tabular}
Some of the devices above are unspecified by this document,
--
2.17.1
-
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
-
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
Re: [virtio-dev][PATCH 2/2] virtio-spi: add the device specification
Hi Jonathon Reinhart,
Thank you so much for all your helpful advice and info!
I took a look at latest Linux SPI driver and found, for
cs_setup/cs_hold/cs_inactive set in device-tree, there are following two
conditions:
1) if SPI controller supports CS timing configuration and CS is not
using a GPIO line, then the SPI driver set the
cs_setup/cs_hold/ca_inactive values into the corresponding SPI CS registers;
2) if CS is using a GPIO line, or SPI controller doesn't support CS
timing configuration, it is the software to perform the
cs_setup/cs_hold/cs_inactive delays, which is implemented in function
spi_set_cs in driver/spi/spi.c.
So I agree it is necessary to pass cs_setup/cs_hold/cs_inactive to
the host for each transfer.
For condition 1, host should set these values into the CS timing
registers. And as you mentioned "one might require different CS
setup/hold times, depending on which slave_id they are talking to (on
the same bus)", if so, host need to overwrite the CS timing registers
between the two transfers talking to different salve_id.
For condition 2, SPI driver running in the host performing the
cs_setup/cs_hold/cs_inactive delays seems more accurate, compared with
performing delays in guest.
And the latest virtio spi transfer structure is defined as follows:
struct spi_transfer_head {
u8 slave_id;
u8 bits_per_word;
u8 cs_change;
u8 tx_nbits;
u8 rx_nbits;
u8 reserved[3];
u32 mode;
u32 freq;
u32 word_delay_ns;
u32 delay_ns;
u32 cs_change_delay_ns;
u32 cs_setup_ns;
u32 cs_hold_ns;
u32 cs_inactive_ns;
};
@slave_id: chipselect index the SPI transfer used
@bits_per_word: the number of bits in each SPI transfer word
@cs_change: True to deselect device before starting the next transfer
@tx_nbits: number of bits used for writing
@rx_nbits: number of bits used for reading
@reserved: reserved for future use
@mode: the spi mode defines how data is clocked out and in
@freq: transfer speed
@word_delay_ns: delay to be inserted between consecutive words of
a transfer, in ns unit
@delay_ns: delay to be introduced after this transfer before
(optionally) changing the chipselect status, in ns unit
@cs_change_delay_ns: delay between cs deassert and assert when
cs_change is set, in ns unit
@cs_setup_ns: delay to be introduced by the controller after CS is
asserted, in ns unit
@cs_hold_ns: delay to be introduced by the controller before CS is
deasserted, in ns unit
@cs_inactive_ns: delay to be introduced by the controller after CS
is deasserted, in ns unit
Could you please help check if this new structure contains enough
information. Really appreciate for kind help.
Best Regards
Haixu Cui
On 7/1/2023 5:59 AM, Jonathon Reinhart wrote:
Hi @jrreinh...@google.com,
Thank you very much for your helpful comments.
I missed the delay and cs_change_delay parameters. I will add both
of them, although cs_change_delay can not be set from userspace, but can
be set in kernel space.
For CS delays such as PRE_DELAY/POST_DELAY, it seems that they are
defined in structure spi_device:
@cs_setup: delay to be introduced by the controller after CS is
asserted.
@cs_hold: delay to be introduced by the controller before CS is
deasserted.
@cs_inactive: delay to be introduced by the controller after CS is
deasserted. If @cs_change_delay is used from @spi_transfer, then the
two delays will be added up.
They show the SPI controller ability to control the CS
assertion/deassertion timing and should not be changed for each transfer
(because thay can be updated by setting structure spi_transfer or
structure spi_ioc_transfer). I think it better to define these parameter
in host OS rather than in guest OS since it's the host OS to operate the
hardware SPI controller directly. Besides, it can also avoid passing the
same values from guest to host time after time.
What's your opinion on this topic? Again, thank you very much.
Hi Haixu,
I took another look at the Linux structures and attempted to map up the
delay parameters to the various points in a SPI sequence. Please correct
me if I'm wrong about any of this.
Consider this diagram where CS# is an active-low chip select, and SCLK
is the serial clock:
___. ._.
CS#|___| |___
. . .
. . .
SCLK _________________
. .. . . . . . .
Delays: +-A-++B+ +--
Re: [virtio-dev][PATCH 2/2] virtio-spi: add the device specification
Hi @jrreinh...@google.com,
Thank you very much for your helpful comments.
I missed the delay and cs_change_delay parameters. I will add both
of them, although cs_change_delay can not be set from userspace, but can
be set in kernel space.
For CS delays such as PRE_DELAY/POST_DELAY, it seems that they are
defined in structure spi_device:
@cs_setup: delay to be introduced by the controller after CS is
asserted.
@cs_hold: delay to be introduced by the controller before CS is
deasserted.
@cs_inactive: delay to be introduced by the controller after CS is
deasserted. If @cs_change_delay is used from @spi_transfer, then the
two delays will be added up.
They show the SPI controller ability to control the CS
assertion/deassertion timing and should not be changed for each transfer
(because thay can be updated by setting structure spi_transfer or
structure spi_ioc_transfer). I think it better to define these parameter
in host OS rather than in guest OS since it's the host OS to operate the
hardware SPI controller directly. Besides, it can also avoid passing the
same values from guest to host time after time.
What's your opinion on this topic? Again, thank you very much.
Best Regards
Haixu Cui
On 6/28/2023 1:06 AM, jrreinh...@google.com wrote:
Hi Haixu,
+The \field{word_delay} defines how long to wait between words within
one SPI transfer,
+in ns unit.
I'm a little surprised to see a word_delay but no frame_delay or
transfer_delay.
For example, many SPI peripherals require a delay after CS is asserted,
but before the first SCLK edge, allowing them to prepare to send data.
(E.g. an ADC might begin taking a sample.)
The linux struct spi_transfer has three delay fields:
* @cs_change_delay: delay between cs deassert and assert when
* @cs_change is set and @spi_transfer is not the last in
* @spi_message
* @delay: delay to be introduced after this transfer before
* (optionally) changing the chipselect status, then starting the
* next transfer or completing this @spi_message.
* @word_delay: inter word delay to be introduced after each word size
* (set by bits_per_word) transmission.
The userspace spidev.h API has only two:
* @delay_usecs: If nonzero, how long to delay after the last bit
* transfer before optionally deselecting the device before the
* next transfer.
* @word_delay_usecs: If nonzero, how long to wait between words within
* one transfer. This property needs explicit support in the SPI
* controller, otherwise it is silently ignored.
The NXP i.MX RT500 SPI (master) controller, for example, has four
configurable delays:
- PRE_DELAY: After CS assertion, before first SCLK edge.
- POST_DELAY: After a transfer, before CS deassertion.
- FRAME_DELAY: Between frames (which are arbitrarily defined by
software).
- TRANSFER_DELAY: Minimum CS deassertion time between transfers.
The NVIDIA Tegra114 SPI controller has:
- nvidia,cs-setup-clk-count: CS setup timing parameter.
- nvidia,cs-hold-clk-count: CS hold timing parameter.
I understand that accurately representing all possible delays might be
difficult or futile, but I'm curious to understand why, of all the
possible delays, inter-word delay was chosen for inclusion.
In a microcontroller, delays around CS (de)assertion can be customized
by using a GPIO -- rather than the hardware SPI block -- to drive the CS
signal. This way, delays can be inserted where needed. To do so with a
virtualized SPI controller might prove difficult however, as the virtual
channel carrying a CS GPIO signal might not be synchronized to the
channel carrying the SPI data.
Curious to hear your thoughts.
Thanks,
Jonathon Reinhart
-
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
[virtio-dev][PATCH 1/2] virtio-spi: define the DEVICE ID for virtio SPI master
Define the DEVICE ID of virtio SPI master device as 45.
---
content.tex | 2 ++
1 file changed, 2 insertions(+)
diff --git a/content.tex b/content.tex
index d2ab9eb..0a62dce 100644
--- a/content.tex
+++ b/content.tex
@@ -737,6 +737,8 @@ \chapter{Device Types}\label{sec:Device Types}
\hline
44 & ISM device \\
\hline
+45 & SPI master \\
+\hline
\end{tabular}
Some of the devices above are unspecified by this document,
--
2.17.1
-
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
[virtio-dev][PATCH 2/2] virtio-spi: add the device specification
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| 152
device-types/spi/device-conformance.tex | 7 ++
device-types/spi/driver-conformance.tex | 7 ++
3 files changed, 166 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 000..62fcb63
--- /dev/null
+++ b/device-types/spi/description.tex
@@ -0,0 +1,152 @@
+\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, Virtio SPI device acts as
+the back-end and exists in the host.
+
+\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.
+\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;
+};
+\end{lstlisting}
+
+\begin{lstlisting}
+struct virtio_spi_transfer_end {
+u8 status;
+};
+\end{lstlisting}
+
+\begin{lstlisting}
+struct virtio_spi_req {
+struct virtio_spi_transfer_head head;
+u8 *rx_buf;
+u8 *tx_buf;
+struct virtio_spi_transfer_end end;
+};
+\end{lstlisting}
+
+The \field{mode} defines the SPI transfer mode.
+
+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.
+
+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_ERR1
+\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.
+
+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
[virtio-dev][PATCH 0/2] virtio-spi: add virtual SPI master
virtio-spi is a virtual SPI(Serial Peripheral Interface) master and it allows a guset to operate and use the physical SPI master controlled by the host. Patch summary: patch 1 define the DEVICE ID for virtio-spi patch 2 add the specification for virtio-spi Haixu Cui (2): virtio-spi: define the DEVICE ID for virtio SPI master virtio-spi: add the device specification content.tex | 2 + device-types/spi/description.tex| 152 device-types/spi/device-conformance.tex | 7 ++ device-types/spi/driver-conformance.tex | 7 ++ 4 files changed, 168 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 -- 2.17.1 - To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
Re: [virtio-dev][PATCH 2/2] virtio-spi: add the device specification
Hello Cornelia Huck,
Thank you so much for your comments. I respond these comments,
could you please help check again. Really appreciate.
I will raise next proposal to fix these comments.
Best Regards
Haixu Cui
On 4/18/2023 5:10 PM, Cornelia Huck wrote:
On Mon, Apr 17 2023, Haixu Cui wrote:
Meta comment: I think you want to send to virtio-comment (feel free to
keep virtio-dev on cc:).
Yes, I will send to virtio-comment and cc to virtio-dev in subsequent
commits.
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 000..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
Nit: missing blank after "SPI"
Got it. Will add blank after SPI.
s/it//
+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.
Can we rewrite this paragraph without relying on the host/guest
terminology? Does
"allows a driver to operate and use the physical SPI master devices
controlled by the device"
capture the essence of what this is doing?
I don't quite understand the second sentence, maybe someone familiar
with SPI can come up with something.
This statement is referred to the Virtio-I2C Chapter, because Virtio-SPI
is very similar to Virtio-SPI in architecture. The guest can communicate
through the physical SPI master without operating the hardware directly,
but calling the physical SPI master driver running on the host. So the
physical SPI driver on the host doesn't need changes any more.
+
+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
s/guest kernel/guest/ ?
Yes, I will update in next commit.
+the back-end and exists in the host. And VirtQueue is used for communication
+between the front-end and the back-end.
"A virtqueue is used for communication between the front-end and the
back-end." ?
[I *think* "virtqueue" is the term we've agreed on?]
Yes, I will remove this line.
+
+\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.
Maybe better "the physical SPI master controled by the device"?
Because this item is set by host and used by guest, so it seems that
this is assigned to the guset by the host.
+
+\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.
What does this mean? Shouldn't we rather only require the driver to set
up the virtqueue and leave details on how to operate beyond the device
<-> driver interface to the implementation?
Yes, I will remove this line in next commit.
+\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 an
[virtio-dev] Re: [PATCH] virtio-spi: add the device specification
Hi Cornelia Huck,
Thank you so much for your helpful comments. I have them fixed in
another submission.
Best Regards
Haixu Cui
On 3/27/2023 7:35 PM, Cornelia Huck wrote:
On Fri, Mar 24 2023, 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.
Please spell out what SPI is the first time you use it.
I explain SPI is the abbreviation of Serial Peripheral Interface.
Also, please remember to post the separate patch that reserves the ID
for it.
I have another patch for DEVICE ID for virtio-spi.
Signed-off-by: Haixu Cui
---
conformance.tex | 12 +-
content.tex | 1 +
device-types/spi/description.tex| 153
device-types/spi/device-conformance.tex | 7 ++
device-types/spi/driver-conformance.tex | 7 ++
5 files changed, 176 insertions(+), 4 deletions(-)
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 000..0b69700
--- /dev/null
+++ b/device-types/spi/description.tex
@@ -0,0 +1,153 @@
+\section{SPI Master Device}\label{sec:Device Types / SPI Master Device}
+
+virtio-spi is a virtual SPI master and it allows a guest to operate and use
+the physical SPI master devices controlled by the host.
Here as well; it's even more important that the acronym is expanded at
least once in the spec.
Also, does this mean that the device is supposed to be an interface to
physical SPI master devices? It would be good if this could be framed
without guest/host terminology (although this can be used as an
example.) Maybe something like
"The virtio SPI master device is a virtual SPI (Serial Peripheral
Interface) master device, potentially interfacing to another SPI master
device. It allows, for example, for a host to expose access to a
physical SPI master device controlled by the host to a guest."
virtio-spi is similar to virtio-i2c, so I update the description
referring to the virtio-i2c specification.
+
+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 VirtQueues assist Virtio SPI driver
+and Virtio SPI device in perform VRing operations for communication between
+the front-end and the back-end.
I'm not sure I can parse this properly -- does this mean that a
virtqueue is used for communication between a front-end and a back-end?
yes, I also update the expression more clear.
(Didn't look at the remainder of the patch yet.)
-
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
[virtio-dev][PATCH 2/2] virtio-spi: add the device specification
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 000..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;
+};
+\end{lstlisting}
+
+\begin{lstlisting}
+struct virtio_spi_transfer_end {
+u8 status;
+};
+\end{lstlisting}
+
+\begin{lstlisting}
+struct virtio_spi_req {
+struct virtio_spi_transfer_head head;
+u8 *rx_buf;
+u8 *tx_buf;
+struct virtio_spi_transfer_end end;
+};
+\end{lstlisting}
+
+The \field{mode} defines the SPI transfer mode.
+
+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.
+
+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_ERR1
+\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.
+
+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 a
[virtio-dev][PATCH 1/2] virtio-spi: define the DEVICE ID for virtio SPI master
Define the DEVICE ID of virtio SPI master device as 45.
---
content.tex | 2 ++
1 file changed, 2 insertions(+)
diff --git a/content.tex b/content.tex
index cff548a..29f2859 100644
--- a/content.tex
+++ b/content.tex
@@ -682,6 +682,8 @@ \chapter{Device Types}\label{sec:Device Types}
\hline
44 & ISM device \\
\hline
+45 & SPI master \\
+\hline
\end{tabular}
Some of the devices above are unspecified by this document,
--
2.17.1
-
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
[virtio-dev][PATCH 0/2] virtio-spi: add virtual SPI master
virtio-spi is a virtual SPI(Serial Peripheral Interface) master and it allows a guset to operate and use the physical SPI master controlled by the host. Patch summary: patch 1 define the DEVICE ID for virtio-spi patch 2 add the specification for virtio-spi Haixu Cui (2): virtio-spi: define the DEVICE ID for virtio SPI master virtio-spi: add the device specification content.tex | 2 + device-types/spi/description.tex| 155 device-types/spi/device-conformance.tex | 7 ++ device-types/spi/driver-conformance.tex | 7 ++ 4 files changed, 171 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 -- 2.17.1 - To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
Re: [virtio-dev] [PATCH] virtio-spi: add the device specification
Hi Cornelia Huck,
Thank you for your comments.
SPI here means 'Serial Peripheral Interface'. And according to your
suggestion, I submit again to remove the introduction of Virtio ID.
Best Regards
Haixu Cui
On 3/15/2023 9:31 PM, Cornelia Huck wrote:
On Mon, Feb 27 2023, 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.
Signed-off-by: Haixu Cui
---
content.tex | 2 +
device-types/spi/description.tex| 153
device-types/spi/device-conformance.tex | 7 ++
device-types/spi/driver-conformance.tex | 7 ++
4 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/content.tex b/content.tex
index 0c7cdf8..86bf709 100644
--- a/content.tex
+++ b/content.tex
@@ -2994,6 +2994,8 @@ \chapter{Device Types}\label{sec:Device Types}
\hline
44 & ISM device \\
\hline
+45 & SPI Master \\
What is 'SPI'? 'Serial Peripheral Interface', I guess?
Introduction of the ID should be split out into a separate patch; if
people agree that this is a useful thing to add, please open a github
issue and request a vote.
+\hline
\end{tabular}
-
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
[virtio-dev] [PATCH] virtio-spi: add the device specification
virtio-spi is a virtual SPI master and it allows a guset to operate and
use the physical SPI master controlled by the host.
Signed-off-by: Haixu Cui
---
conformance.tex | 12 +-
content.tex | 1 +
device-types/spi/description.tex| 153
device-types/spi/device-conformance.tex | 7 ++
device-types/spi/driver-conformance.tex | 7 ++
5 files changed, 176 insertions(+), 4 deletions(-)
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/conformance.tex b/conformance.tex
index 01ccd69..a91c40a 100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -32,8 +32,9 @@ \section{Conformance Targets}\label{sec:Conformance /
Conformance Targets}
\ref{sec:Conformance / Driver Conformance / Memory Driver Conformance},
\ref{sec:Conformance / Driver Conformance / I2C Adapter Driver Conformance},
\ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance},
-\ref{sec:Conformance / Driver Conformance / GPIO Driver Conformance} or
-\ref{sec:Conformance / Driver Conformance / PMEM Driver Conformance}.
+\ref{sec:Conformance / Driver Conformance / GPIO Driver Conformance},
+\ref{sec:Conformance / Driver Conformance / PMEM Driver Conformance} or
+\ref{sec:Conformance / Driver Conformance / SPI Master Driver Conformance}.
\item Clause \ref{sec:Conformance / Legacy Interface: Transitional Device
and Transitional Driver Conformance}.
\end{itemize}
@@ -59,8 +60,9 @@ \section{Conformance Targets}\label{sec:Conformance /
Conformance Targets}
\ref{sec:Conformance / Device Conformance / Memory Device Conformance},
\ref{sec:Conformance / Device Conformance / I2C Adapter Device Conformance},
\ref{sec:Conformance / Device Conformance / SCMI Device Conformance},
-\ref{sec:Conformance / Device Conformance / GPIO Device Conformance} or
-\ref{sec:Conformance / Device Conformance / PMEM Device Conformance}.
+\ref{sec:Conformance / Device Conformance / GPIO Device Conformance},
+\ref{sec:Conformance / Device Conformance / PMEM Device Conformance} or
+\ref{sec:Conformance / Device Conformance / SPI Master Device Conformance}.
\item Clause \ref{sec:Conformance / Legacy Interface: Transitional Device
and Transitional Driver Conformance}.
\end{itemize}
@@ -152,6 +154,7 @@ \section{Conformance Targets}\label{sec:Conformance /
Conformance Targets}
\input{device-types/scmi/driver-conformance.tex}
\input{device-types/gpio/driver-conformance.tex}
\input{device-types/pmem/driver-conformance.tex}
+\input{device-types/spi/driver-conformance.tex}
\conformance{\section}{Device Conformance}\label{sec:Conformance / Device
Conformance}
@@ -238,6 +241,7 @@ \section{Conformance Targets}\label{sec:Conformance /
Conformance Targets}
\input{device-types/scmi/device-conformance.tex}
\input{device-types/gpio/device-conformance.tex}
\input{device-types/pmem/device-conformance.tex}
+\input{device-types/spi/device-conformance.tex}
\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
diff --git a/content.tex b/content.tex
index cff548a..d257793 100644
--- a/content.tex
+++ b/content.tex
@@ -710,6 +710,7 @@ \chapter{Device Types}\label{sec:Device Types}
\input{device-types/scmi/description.tex}
\input{device-types/gpio/description.tex}
\input{device-types/pmem/description.tex}
+\input{device-types/spi/description.tex}
\chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
diff --git a/device-types/spi/description.tex b/device-types/spi/description.tex
new file mode 100644
index 000..0b69700
--- /dev/null
+++ b/device-types/spi/description.tex
@@ -0,0 +1,153 @@
+\section{SPI Master Device}\label{sec:Device Types / SPI Master Device}
+
+virtio-spi is a virtual SPI master and it allows a guest to operate and use
+the physical SPI master devices controlled by the host.
+
+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 VirtQueues assist Virtio SPI driver
+and Virtio SPI device in perform VRing operations 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
[virtio-dev] [PATCH] virtio-spi: add the device specification
virtio-spi is a virtual SPI master and it allows a guset to operate and
use the physical SPI master controlled by the host.
Signed-off-by: Haixu Cui
---
content.tex | 2 +
device-types/spi/description.tex| 153
device-types/spi/device-conformance.tex | 7 ++
device-types/spi/driver-conformance.tex | 7 ++
4 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/content.tex b/content.tex
index 0c7cdf8..86bf709 100644
--- a/content.tex
+++ b/content.tex
@@ -2994,6 +2994,8 @@ \chapter{Device Types}\label{sec:Device Types}
\hline
44 & ISM device \\
\hline
+45 & SPI Master \\
+\hline
\end{tabular}
Some of the devices above are unspecified by this document,
diff --git a/device-types/spi/description.tex b/device-types/spi/description.tex
new file mode 100644
index 000..0b69700
--- /dev/null
+++ b/device-types/spi/description.tex
@@ -0,0 +1,153 @@
+\section{SPI Master Device}\label{sec:Device Types / SPI Master Device}
+
+virtio-spi is a virtual SPI master and it allows a guest to operate and use
+the physical SPI master devices controlled by the host.
+
+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 VirtQueues assist Virtio SPI driver
+and Virtio SPI device in perform VRing operations 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;
+};
+\end{lstlisting}
+
+\begin{lstlisting}
+struct virtio_spi_transfer_end {
+u8 status;
+};
+\end{lstlisting}
+
+\begin{lstlisting}
+struct virtio_spi_req {
+struct virtio_spi_transfer_head head;
+u8 *rx_buf;
+u8 *tx_buf;
+struct virtio_spi_transfer_end end;
+};
+\end{lstlisting}
+
+The \field{mode} defines the SPI transfer mode.
+
+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.
+
+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_ERR1
+\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_tran
