[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: 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 <quic_haixcui@quicinc.com> --- 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 0000000..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, QiangHi 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, QiangThank 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. + +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 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 \field{freq} indicates the SPI transfer speed in Hz. + +The \field{word_delay_ns} indicates delay to be inserted between consecutive +words of a transfer, in ns unit. + +The \field{cs_setup_ns} indicates delay to be introduced after chipselect +is asserted, in ns unit. + +The \field{cs_delay_hold_ns} indicates delay to be introduced before chipselect +is deasserted, in ns unit. + +The \field{cs_change_delay_inactive_ns} indicates delay to be introduced after +chipselect is deasserted and before next asserted, in ns unit. + +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. + +The final \field{result} is the transfer result, either VIRTIO_SPI_TRANS_OK for success +or VIRTIO_SPI_TRANS_ERR for error. + +\begin{lstlisting} +#define VIRTIO_SPI_TRANS_OK 0 +#define VIRTIO_SPI_TRANS_ERR 1 +\end{lstlisting} + +\subsubsection{Device Operation: Operation Status}\label{sec:Device Types / SPI Master Device / Device Operation: Operation Status} + +Fields in structure \field{virtio_spi_transfer_head} are written by Virtio SPI driver, while +\field{result} in structure \field{virtio_spi_transfer_result} is written by 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 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. + +\drivernormative{\subsubsection}{Device Operation}{Device Types / SPI Master Device / Device Operation} + +The Virtio SPI driver MUST send transfer requests on the requestq virtqueue. + +Fields in structure \field{virtio_spi_transfer_head} MUST be filled by Virtio SPI driver +and MUST be readable for Virtio SPI device. + +Structure \field{virtio_spi_transfer_result} MUST be filled by Virtio SPI device +and MUST be writable for Virtio SPI device. + +For half-duplex read, Virtio SPI driver MUST send structure \field{virtio_spi_transfer_head}, +\field{rx_buf} and structure \field{virtio_spi_transfer_result} to SPI Virtio Device in order. + +For half-duplex write, Virtio SPI driver MUST send structure \field{virtio_spi_transfer_head}, +\field{tx_buf} and structure \field{virtio_spi_transfer_result} to SPI Virtio Device in order. + +For full-duplex read and write, Virtio SPI driver MUST send structure \field{virtio_spi_transfer_head}, +\field{tx_buf}, \field{rx_buf} and structure \field{virtio_spi_transfer_result} to SPI Virtio Device in order. + +For half-duplex write or full-duplex read and write transfer, Virtio SPI driver MUST not use \field{rx_buf} +if the \field{result} returned from Virtio SPI device is VIRTIO_SPI_TRANS_ERR. + +If \field{cs_timing_setting_enable} in structure \field{virtio_spi_config} is 0, while \field{cs_setup_ns}, +\field{cs_setup_ns} and \field{cs_change_delay_inactive_ns} of the transfer are not all zero, Virtio +SPI driver MUST print a warning log to alert that the cs timing won't be set as expected. + +\devicenormative{\subsubsection}{Device Operation}{Device Types / SPI Master Device / Device Operation} + +Virtio SPI device MUST set all the fields of the structure \field{virtio_spi_config} before +they are read by Virtio SPI driver. + +Virtio SPI device MUST set the structure \field{virtio_spi_transfer_result} before sending +it back to Virtio SPI driver. + +Virtio SPI device MUST be able to identify the transfer type according to the received +virtqueue descriptors. + +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. diff --git a/device-types/spi/device-conformance.tex b/device-types/spi/device-conformance.tex new file mode 100644 index 0000000..3e771bc --- /dev/null +++ b/device-types/spi/device-conformance.tex @@ -0,0 +1,7 @@ +\conformance{\subsection}{SPI Master Device Conformance}\label{sec:Conformance / Device Conformance / SPI Master Device Conformance} + +An SPI Master device MUST conform to the following normative statements: + +\begin{itemize} +\item \ref{devicenormative:Device Types / SPI Master Device / Device Operation} +\end{itemize} diff --git a/device-types/spi/driver-conformance.tex b/device-types/spi/driver-conformance.tex new file mode 100644 index 0000000..3c965ef --- /dev/null +++ b/device-types/spi/driver-conformance.tex @@ -0,0 +1,7 @@ +\conformance{\subsection}{SPI Master Driver Conformance}\label{sec:Conformance / Driver Conformance / SPI Master Driver Conformance} + +An SPI Master driver MUST conform to the following normative statements: + +\begin{itemize} +\item \ref{drivernormative:Device Types / SPI Master Device / Device Operation} +\end{itemize} -- 2.17.1 --------------------------------------------------------------------- To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]