[PATCH] virtio-sdhci: add the device specification

[Mikhail Krasheninnikov <krashmisha@gmail.com>]

virtio-sdhci is a virtual SDHCI (Secure Digital Host Controller Interface) device.
It allows the guest to work with virtualized SD/MMC cards.

This patch adds the specification for virtio-sdhci.

Signed-off-by: Mikhail Krasheninnikov <krashmisha@gmail.com>
CC: Matwey Kornilov <matwey.kornilov@gmail.com>
---
 conformance.tex                           |  12 +-
 content.tex                               |   3 +
 device-types/sdhci/description.tex        | 216 ++++++++++++++++++++++
 device-types/sdhci/device-conformance.tex |   8 +
 device-types/sdhci/driver-conformance.tex |   8 +
 5 files changed, 243 insertions(+), 4 deletions(-)
 create mode 100644 device-types/sdhci/description.tex
 create mode 100644 device-types/sdhci/device-conformance.tex
 create mode 100644 device-types/sdhci/driver-conformance.tex

diff --git a/conformance.tex b/conformance.tex
index 183c059..a268dda 100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -34,8 +34,9 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
 \ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance},
 \ref{sec:Conformance / Driver Conformance / GPIO Driver Conformance},
 \ref{sec:Conformance / Driver Conformance / PMEM Driver Conformance},
-\ref{sec:Conformance / Driver Conformance / CAN Driver Conformance} or
-\ref{sec:Conformance / Driver Conformance / SPI Controller Driver Conformance}.
+\ref{sec:Conformance / Driver Conformance / CAN Driver Conformance},
+\ref{sec:Conformance / Driver Conformance / SPI Controller Driver Conformance} or
+\ref{sec:Conformance / Driver Conformance / SDHCI Driver Conformance}.
 
     \item Clause \ref{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}.
   \end{itemize}
@@ -63,8 +64,9 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
 \ref{sec:Conformance / Device Conformance / SCMI Device Conformance},
 \ref{sec:Conformance / Device Conformance / GPIO Device Conformance},
 \ref{sec:Conformance / Device Conformance / PMEM Device Conformance},
-\ref{sec:Conformance / Device Conformance / CAN Device Conformance} or
-\ref{sec:Conformance / Device Conformance / SPI Controller Device Conformance}.
+\ref{sec:Conformance / Device Conformance / CAN Device Conformance},
+\ref{sec:Conformance / Device Conformance / SPI Controller Device Conformance} or
+\ref{sec:Conformance / Device Conformance / SDHCI Driver Conformance}.
 
     \item Clause \ref{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}.
   \end{itemize}
@@ -159,6 +161,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
 \input{device-types/pmem/driver-conformance.tex}
 \input{device-types/can/driver-conformance.tex}
 \input{device-types/spi/driver-conformance.tex}
+\input{device-types/sdhci/driver-conformance.tex}
 
 \conformance{\section}{Device Conformance}\label{sec:Conformance / Device Conformance}
 
@@ -248,6 +251,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
 \input{device-types/pmem/device-conformance.tex}
 \input{device-types/can/device-conformance.tex}
 \input{device-types/spi/device-conformance.tex}
+\input{device-types/sdhci/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 d7d544e..56d5c0c 100644
--- a/content.tex
+++ b/content.tex
@@ -743,6 +743,8 @@ \chapter{Device Types}\label{sec:Device Types}
 \hline
 47         &   CPU balloon device \\
 \hline
+48         &   SDHCI device \\
+\hline
 \end{longtable}
 
 Some of the devices above are unspecified by this document,
@@ -773,6 +775,7 @@ \chapter{Device Types}\label{sec:Device Types}
 \input{device-types/pmem/description.tex}
 \input{device-types/can/description.tex}
 \input{device-types/spi/description.tex}
+\input{device-types/sdhci/description.tex}
 
 \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
 
diff --git a/device-types/sdhci/description.tex b/device-types/sdhci/description.tex
new file mode 100644
index 0000000..425f444
--- /dev/null
+++ b/device-types/sdhci/description.tex
@@ -0,0 +1,216 @@
+\section{SDHCI Device}\label{sec:Device Types / SDHCI Device}
+
+The virtio SDHCI (SD Host Controller Interface) driver provides
+a virtualized interface for MMC/SD card devices in guest systems.
+This driver emulates the functionality of a physical SDHCI controller,
+enabling guest operating systems to interact with virtual MMC/SD
+storage as if they were physical devices.
+
+\subsection{Device ID}\label{sec:Device Types / SDHCI Device / Device ID}
+  48
+
+\subsection{Virtqueues}\label{sec:Device Types / SDHCI Device / Virtqueues}
+\begin{description}
+\item[0] requestq
+\end{description}
+
+\subsection{Feature bits}\label{sec:Device Types / SDHCI Device / Feature bits}
+
+None currently defined.
+
+\subsection{Device configuration layout}\label{sec:Device Types / SDHCI Device / Device configuration layout}
+
+None currently defined.
+
+\subsection{Device Initialization}\label{sec:Device Types / SDHCI Device / Device Initialization}
+
+\begin{enumerate}
+\item The virtqueue is initialized
+\end{enumerate}
+
+\subsection{Driver Operation}\label{sec:Device Types / SDHCI Device / Driver Operation}
+
+The driver enqueues requests to the virtqueues, and they are processed
+by the device. Each MMC request is of the form:
+
+\begin{lstlisting}
+struct virtio_mmc_request {
+        u8 flags;
+
+        struct mmc_req request;
+
+        u8 buf[4096];
+        le32 buf_len;
+
+        struct mmc_req stop_req;
+        struct mmc_req sbc_req;
+};
+\end{lstlisting}
+
+The \field{flags} field indicates the type of MMC request. The following flags are defined:
+
+\begin{lstlisting}
+#define VIRTIO_MMC_REQUEST_DATA  BIT(1)
+#define VIRTIO_MMC_REQUEST_WRITE BIT(2)
+#define VIRTIO_MMC_REQUEST_STOP  BIT(3)
+#define VIRTIO_MMC_REQUEST_SBC   BIT(4)
+\end{lstlisting}
+
+\begin{itemize}
+\item VIRTIO_MMC_REQUEST_DATA (BIT(1)): Indicates that the request includes a data phase.
+\item VIRTIO_MMC_REQUEST_WRITE (BIT(2)): Indicates a write operation.
+\item VIRTIO_MMC_REQUEST_STOP (BIT(3)): Indicates a stop command.
+\item VIRTIO_MMC_REQUEST_SBC (BIT(4)): Indicates a Set Block Count (SBC) command.
+\end{itemize}
+
+The \field{request} field is a structure of type \field{mmc_req} representing the primary MMC command:
+
+\begin{lstlisting}
+struct mmc_req {
+        le32 opcode;
+        le32 arg;
+};
+\end{lstlisting}
+
+\begin{itemize}
+        \item \field{opcode}: A 32-bit little-endian value representing the MMC command opcode.
+        \item \field{arg}: A 32-bit little-endian value representing the argument to the MMC command.
+\end{itemize}
+
+The \field{buf} field is a 4096-byte buffer used for data transfer, and \field{buf_len}
+is a 32-bit little-endian value specifying the length of the data in buf.
+
+The \field{stop_req} field is an optional \field{mmc_req} structure used if the request
+includes a stop command, and \field{sbc_req} is an optional \field{mmc_req} structure
+used if the request includes an SBC command.
+
+\drivernormative{\subsubsection}{Device Operation}{Device Types / SDHCI Device / Device Operation}
+
+The driver SHOULD verify the content of the flags field for validity before submitting a request.
+
+A driver MUST NOT submit a request with the buf_len field exceeding 4096 bytes.
+
+A driver MUST set the buf_len field to 0 for requests without the VIRTIO_MMC_REQUEST_DATA flag.
+
+A driver MUST set the buf field to contain valid data for write operations, indicated by
+the VIRTIO_MMC_REQUEST_WRITE flag.
+
+A driver SHOULD ensure the opcode and arg fields in mmc_req structures are correctly set
+according to the MMC command specification.
+
+For a request with the VIRTIO_MMC_REQUEST_STOP flag, the stop_req field MUST be populated
+with a valid stop command.
+
+For a request with the VIRTIO_MMC_REQUEST_SBC flag, the sbc_req field MUST be populated
+with a valid Set Block Count (SBC) command.
+
+The length of data in the buf field MUST be a multiple of the block size for read and write
+operations.
+
+A driver MUST ensure that opcode and arg values comply with the MMC command set and do not
+cause undefined behavior.
+
+The flags field MUST be set correctly to reflect the intended operation (data transfer, write,
+stop, SBC).
+
+The request, stop_req, and sbc_req fields MUST be set to valid mmc_req structures appropriate
+for the MMC commands being issued.
+
+The driver SHOULD handle errors returned by the device and take appropriate action based on
+the status of the request.
+
+The driver SHOULD verify the content of the cmd_resp field upon receiving a response.
+
+A driver MUST handle the cmd_resp_len field correctly, ensuring it processes only the valid
+part of the command response.
+
+A driver SHOULD use the data in the buf field if the request was a read operation.
+
+A driver MUST handle errors indicated by the command response and take appropriate action.
+
+A driver SHOULD validate the length and content of the cmd_resp field according to the MMC
+command specification.
+
+A driver MUST ensure that the buf field is processed correctly and data integrity is maintained.
+
+The driver SHOULD log any errors or anomalies found in the response for debugging and maintenance
+purposes.
+
+\subsection{Device Operation}\label{sec:Device Types / SDHCI Device / Device Operation}
+
+Each response from the device is of the following form:
+
+\begin{lstlisting}
+struct virtio_mmc_response {
+        __le32 cmd_resp[4];
+        uint8_t cmd_resp_len;
+        uint8_t buf[4096];
+};
+\end{lstlisting}
+
+\begin{itemize}
+        \item \field{cmd_resp}: An array of four 32-bit little-endian values representing the
+        command response from the MMC device.
+        \item \field{cmd_resp_len}: An 8-bit value indicating the length of the command response.
+        \item \field{buf}: A 4096-byte buffer for data transfer from the device to the driver.
+\end{itemize}
+
+\devicenormative{\subsubsection}{Device Operation}{Device Types / SDHCI Device / Device Operation}
+
+The device SHOULD verify the content of the flags field for validity before processing a request.
+
+A device MUST NOT process a request if the buf_len field exceeds 4096 bytes.
+
+A device MUST ignore the buf field for requests without the VIRTIO_MMC_REQUEST_DATA flag.
+
+A device MUST use the buf field data for write operations, indicated by the
+VIRTIO_MMC_REQUEST_WRITE flag.
+
+A device MUST validate the opcode and arg fields in mmc_req structures according to
+the MMC command specification.
+
+For a request with the VIRTIO_MMC_REQUEST_STOP flag, the stop_req field MUST be used
+to process a valid stop command.
+
+For a request with the VIRTIO_MMC_REQUEST_SBC flag, the sbc_req field MUST be used to
+process a valid Set Block Count (SBC) command.
+
+The length of data in the buf field MUST be a multiple of the block size for read and
+write operations.
+
+The device SHOULD handle configuration change notifications and adjust its behavior accordingly.
+
+A device MUST ensure that opcode and arg values comply with the MMC command set and
+do not cause undefined behavior.
+
+The flags field MUST be processed correctly to reflect the intended operation (data
+transfer, write, stop, SBC).
+
+The request, stop_req, and sbc_req fields MUST be validated as mmc_req structures
+appropriate for the MMC commands being issued.
+
+The device SHOULD report errors to the driver and provide appropriate status for
+the request.
+
+The device MUST ensure data integrity and correctness when processing read and write operations.
+
+The device SHOULD log and handle invalid requests gracefully, without causing a crash
+or undefined behavior.
+
+The device MUST populate the cmd_resp field with valid command response values
+according to the MMC specification.
+
+The device MUST set the cmd_resp_len field to indicate the length of the command response.
+
+For read operations, the device MUST populate the buf field with the requested data.
+
+The device SHOULD handle errors internally and populate the cmd_resp field with
+appropriate error codes.
+
+The device MUST ensure that the length of the command response does not exceed
+the maximum allowed by cmd_resp_len.
+
+The device MUST maintain data integrity and correctness when writing to the buf field.
+
+The device SHOULD log and handle invalid responses gracefully, without causing a crash
+or undefined behavior.
\ No newline at end of file
diff --git a/device-types/sdhci/device-conformance.tex b/device-types/sdhci/device-conformance.tex
new file mode 100644
index 0000000..cc12806
--- /dev/null
+++ b/device-types/sdhci/device-conformance.tex
@@ -0,0 +1,8 @@
+\conformance{\subsection}{SDHCI Device Conformance}\label{sec:Conformance / Device Conformance / SDHCI Device Conformance}
+
+A SDHCI device MUST conform to the following normative statements:
+
+\begin{itemize}
+\item \ref{devicenormative:Device Types / SDHCI Device / Device Initialization}
+\item \ref{devicenormative:Device Types / SDHCI Device / Device Operation}
+\end{itemize}
diff --git a/device-types/sdhci/driver-conformance.tex b/device-types/sdhci/driver-conformance.tex
new file mode 100644
index 0000000..47cd855
--- /dev/null
+++ b/device-types/sdhci/driver-conformance.tex
@@ -0,0 +1,8 @@
+\conformance{\subsection}{SDHCI Driver Conformance}\label{sec:Conformance / Driver Conformance / SDHCI Driver Conformance}
+
+A SDHCI driver MUST conform to the following normative statements:
+
+\begin{itemize}
+\item \ref{drivernormative:Device Types / SDHCI Device / Device Initialization}
+\item \ref{drivernormative:Device Types / SDHCI Device / Device Operation}
+\end{itemize}
-- 
2.39.3 (Apple Git-146)