+
+ 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.
+
+Note: LSB first indicates that data is transferred least significant
bit first, and MSB first
+indicates that data is transferred most significant bit first.
+
+\field{max_freq_hz} is the maximum clock rate supported in Hz unit, 0
means no limitation
+for transfer speed.
+
+\field{max_word_delay_ns} is the maximum word delay supported in ns
unit, 0 means word delay
+feature is unsupported.
+
+Note: Just as one message contains a sequence of transfers, one
transfer may contain
+a sequence of words.
+
+\field{max_cs_setup_ns} is the maximum delay supported after
chipselect is asserted, in ns unit,
+0 means delay is not supported to introduce after chipselect is
asserted.
+
+\field{max_cs_hold_ns} is the maximum delay supported before
chipselect is deasserted, in ns unit,
+0 means delay is not supported to introduce before chipselect is
deasserted.
+
+\field{max_cs_incative_ns} is the maximum delay supported after
chipselect is deasserted, in ns unit,
+0 means delay is not supported to introduce after chipselect is
deasserted.
+
+\subsection{Device Initialization}\label{sec:Device Types / SPI
Controller 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 Controller
Device / Device Operation}
+
+\subsubsection{Device Operation: Request Queue}\label{sec:Device
Types / SPI Controller Device / Device Operation: Request Queue}
+
+The Virtio SPI driver enqueues requests to the virtqueue, and they
are used by the Virtio SPI device.
+Each request represents one SPI transfer and is of the form:
+
+\begin{lstlisting}
+struct virtio_spi_transfer_head {
+ u8 chip_select_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}
+
+\field{chip_select_id} indicates the chipselect index to use for the
SPI transfer.
+
+\field{bits_per_word} indicates the number of bits in each SPI
transfer word.
+
+\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.
+
+\field{tx_nbits} and \field{rx_nbits} indicate n-bit transfer mode
for writing and reading:
+ 0,1: SINGLE;
+ 2 : DUAL;
+ 4 : QUAD;
+ 8 : OCTAL;
+ other values are invalid.
+
+\field{reserved} is currently unused and might be used for further
extensions in the future.
+
+\field{mode} indicates some transfer settings. 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.
+
+\field{freq} indicates the SPI transfer speed in Hz.
+
+\field{word_delay_ns} indicates delay to be inserted between
consecutive words of a transfer,
+in ns unit.
+
+\field{cs_setup_ns} indicates delay to be introduced after chipselect
is asserted, in ns unit.
+
+\field{cs_delay_hold_ns} indicates delay to be introduced before
chipselect is deasserted,
+in ns unit.
+
+\field{cs_change_delay_inactive_ns} indicates delay to be introduced
after chipselect is
+deasserted and before next asserted, in ns unit.
+
+\field{tx_buf} is the buffer for data sent to the device.
+
+\field{rx_buf} is the buffer for data received from the device.
+
+\field{result} is the transfer result, it may be one of the following
values:
+
+\begin{lstlisting}
+#define VIRTIO_SPI_TRANS_OK 0
+#define VIRTIO_SPI_PARAM_ERR 1
+#define VIRTIO_SPI_TRANS_ERR 2
+\end{lstlisting}
+
+VIRTIO_SPI_TRANS_OK indicates successful completion of the transfer.
+
+VIRTIO_SPI_PARAM_ERR indicates a parameter error, which means the
parameters in
+\field{struct 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
device.
+In particular, for full-duplex transfer, VIRTIO_SPI_PARAM_ERR can
also indicate that
+\field{tx_buf} and \field{rx_buf} are not of the same length.
+
+VIRTIO_SPI_TRANS_ERR indicates a transfer error, which means that the
parameters are all
+valid but the trasnfer process failed.
+
+\subsubsection{Device Operation: Operation Status}\label{sec:Device
Types / SPI Controller Device / Device Operation: Operation Status}
+
+Fields in \field{struct virtio_spi_transfer_head} are written by the
Virtio SPI driver, while
+\field{result} in \field{struct virtio_spi_transfer_result} is
written by the Virtio SPI device.
+
+virtio-spi supports three transfer types:
+\begin{itemize}
+\item half-duplex read;
+\item half-duplex write;
+\item full-duplex transfer.
+\end{itemize}
+
+For half-duplex read and full-duplex transfer, \field{rx_buf} is
filled by the Virtio SPI device
+and consumed by the Virtio SPI driver. For half-duplex write and
full-duplex transfer, \field{tx_buf}
+is filled by the Virtio SPI driver and consumed by the Virtio SPI
device.
+
+\drivernormative{\subsubsection}{Device Operation}{Device Types / SPI
Controller Device / Device Operation}
+
+For half-duplex read, the Virtio SPI driver MUST send \field{struct
virtio_spi_transfer_head},
+\field{rx_buf} and \field{struct virtio_spi_transfer_result} to the
SPI Virtio Device in that order.
+
+For half-duplex write, the Virtio SPI driver MUST send \field{struct
virtio_spi_transfer_head},
+\field{tx_buf} and \field{struct virtio_spi_transfer_result} to the
SPI Virtio Device in that order.
+
+For full-duplex transfer, the Virtio SPI driver MUST send
\field{struct virtio_spi_transfer_head},
+\field{tx_buf}, \field{rx_buf} and \field{struct
virtio_spi_transfer_result} to the SPI Virtio Device
+in that order.
+
+For full-duplex transfer, the Virtio SPI driver MUST guarantee that
the buffer size of \field{tx_buf}
+and \field{rx_buf} is the same.
+
+The Virtio SPI driver MUST not use \field{rx_buf} if the
\field{result} returned from the Virtio SPI device is
+not VIRTIO_SPI_TRANS_OK.
+
+\devicenormative{\subsubsection}{Device Operation}{Device Types / SPI
Controller Device / Device Operation}
+
+The Virtio SPI device MUST set all the fields of \field{struct
virtio_spi_config} before they are
+read by the Virtio SPI driver.
+
+The Virtio SPI device MUST NOT change the data in \field{tx_buf}.
+
+The Virtio SPI device MUST verify the parameters in \field{struct
virtio_spi_transfer_head} after receiving
+the request, and MUST set \field{struct virtio_spi_transfer_result}
as VIRTIO_SPI_PARAM_ERR if not all
+parameters are valid or some device unsupported features are set.
+
+For full-duplex transfer, the Virtio SPI device MUST verify that the
buffer size of \field{tx_buf} is equal to
+that of \field{rx_buf}. If not, the Virtio SPI device MUST set
\field{struct virtio_spi_transfer_result}
+as VIRTIO_SPI_PARAM_ERR.
diff --git a/device-types/spi/device-conformance.tex
b/device-types/spi/device-conformance.tex
new file mode 100644
index 0000000..4509156
--- /dev/null
+++ b/device-types/spi/device-conformance.tex
@@ -0,0 +1,7 @@
+\conformance{\subsection}{SPI Controller Device
Conformance}\label{sec:Conformance / Device Conformance / SPI
Controller Device Conformance}
+
+An SPI Controller device MUST conform to the following normative
statements:
+
+\begin{itemize}
+\item \ref{devicenormative:Device Types / SPI Controller 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..bbd1967
--- /dev/null
+++ b/device-types/spi/driver-conformance.tex
@@ -0,0 +1,7 @@
+\conformance{\subsection}{SPI Controller Driver
Conformance}\label{sec:Conformance / Driver Conformance / SPI
Controller Driver Conformance}
+
+An SPI Controller driver MUST conform to the following normative
statements:
+
+\begin{itemize}
+\item \ref{drivernormative:Device Types / SPI Controller Device /
Device Operation}
+\end{itemize}
