[virtio-dev] [PATCH 1/1] RFC: virtio-bt: add virtio BT device specification

[Igor Skalkin <Igor.Skalkin@opensynergy.com>]

This PR is aimed as review for comments(RFC) purpose.

* Initial draft version.

Signed-off-by: Igor Skalkin <Igor.Skalkin@opensynergy.com>
---
 conformance.tex                        |  12 ++-
 content.tex                            |   1 +
 device-types/bt/description.tex        | 112 +++++++++++++++++++++++++
 device-types/bt/device-conformance.tex |   8 ++
 device-types/bt/driver-conformance.tex |   8 ++
 5 files changed, 137 insertions(+), 4 deletions(-)
 create mode 100644 device-types/bt/description.tex
 create mode 100644 device-types/bt/device-conformance.tex
 create mode 100644 device-types/bt/driver-conformance.tex

diff --git a/conformance.tex b/conformance.tex
index 01ccd69..a69eb47 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 / BT 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 / BT 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/bt/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/bt/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 0c7cdf8..3723ec8 100644
--- a/content.tex
+++ b/content.tex
@@ -3022,6 +3022,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/bt/description.tex}
 
 \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
 
diff --git a/device-types/bt/description.tex b/device-types/bt/description.tex
new file mode 100644
index 0000000..3ce265d
--- /dev/null
+++ b/device-types/bt/description.tex
@@ -0,0 +1,112 @@
+\section{BT Device}\label{sec:Device Types / BT Device}
+
+The virtio-bt device provides an HCI (Host Control Interface) over VirtIO
+link between the guest HCI device and the host HCI backend.
+Also, the device can inform the guest driver which vendor-specific command
+set it supports.
+Host Control Interface is described in Bluetooth Core Specification:
+\newline\url{https://www.bluetooth.com/specifications/specs/core-specification-5-4/}\\
+
+\subsection{Device ID}\label{sec:Device Types / BT Device / Device ID}
+
+40
+
+\subsection{Virtqueues}\label{sec:Device Types / BT Device / Virtqueues}
+
+\begin{description}
+\item[0] transmitq
+\item[1] receiveq
+\end{description}
+
+\subsection{Feature bits}\label{sec:Device Types / BT Device / Feature bits}
+
+\begin{description}
+\item[VIRTIO_BT_F_VND_HCI (0)]  Indicates vendor command support.
+\item[VIRTIO_BT_F_MSFT_EXT (1)] Indicates MSFT vendor support.
+\item[VIRTIO_BT_F_AOSP_EXT (2)] Indicates AOSP vendor support.
+\item[VIRTIO_BT_F_CONFIG_V2 (3)] The device uses the second version of the
+configuration space structure.
+\end{description}
+
+\devicenormative{\subsubsection}{Feature bits}{Device Types / BT Device / Feature bits}
+
+The device MUST require the driver to accept the VIRTIO_BT_F_CONFIG_V2 feature
+bit, i.e. not set FEATURES_OK without it, and use the second version
+(struct virtio_bt_config_v2) of the configuration layout, because the
+first one (struct virtio_bt_config) is unaligned, which violates the
+specification.
+
+The device should offer VIRTIO_BT_F_MSFT_EXT or VIRTIO_BT_F_AOSP_EXT feature bit
+if it supports correspondingly MSFT or AOSP extension command sets. In case of
+VIRTIO_BT_F_MSFT_EXT, device should also set configuration \field{msft_opcode}.
+
+The device should offer VIRTIO_BT_F_VND_HCI feature bit and set \field{vendor}
+to the VIRTIO_BT_CONFIG_VENDOR_ZEPHYR, VIRTIO_BT_CONFIG_VENDOR_INTEL or
+VIRTIO_BT_CONFIG_VENDOR_REALTEK, if it supports corresponding vendor extensions.
+
+\drivernormative{\subsubsection}{Feature bits}{Device Types / BT Device / Feature bits}
+
+The driver MUST accept VIRTIO_BT_F_CONFIG_V2 feature bit if offered by the device.
+
+The driver SHOULD accept any of the  VIRTIO_BT_F_VND_HCI, VIRTIO_BT_F_MSFT_EXT
+or VIRTIO_BT_F_AOSP_EXT feature bits if offered by the device.
+
+\subsection{Device configuration layout}\label{sec:Device Types / BT Device / Device configuration layout}
+
+
+The first version:
+\begin{lstlisting}
+struct virtio_bt_config {
+	u8 type;
+	le16 vendor;
+	le16 msft_opcode;
+} __attribute__((packed));
+\end{lstlisting}
+
+is deprecated, new devices must use the second one:
+\begin{lstlisting}
+struct virtio_bt_config_v2 {
+	u8 type;
+	u8 alignment;
+	le16 vendor;
+	le16 msft_opcode;
+};
+\end{lstlisting}
+
+\devicenormative{\subsubsection}{Device configuration layout}{Device Types / BT Device / Device configuration layout}
+The device MUST NOT present a value different than
+\begin{lstlisting}
+	VIRTIO_BT_CONFIG_TYPE_PRIMARY = 0,
+	VIRTIO_BT_CONFIG_TYPE_AMP = 1,
+\end{lstlisting}
+in \field{type}.
+
+The values 1..3 of the \field{vendor} are already reserved for vendor extensions listed below:
+\begin{lstlisting}
+	VIRTIO_BT_CONFIG_VENDOR_NONE = 0
+	VIRTIO_BT_CONFIG_VENDOR_ZEPHYR = 1
+	VIRTIO_BT_CONFIG_VENDOR_INTEL = 2
+	VIRTIO_BT_CONFIG_VENDOR_REALTEK = 3
+\end{lstlisting}
+
+If value of the \field{vendor} is not VIRTIO_BT_CONFIG_VENDOR_NONE, device MUST
+offer VIRTIO_BT_F_VND_HCI feature bit.
+
+\drivernormative{\subsubsection}{Driver configuration layout}{Device Types / BT Device / Driver configuration layout}
+All configuration fields are read-only for the driver.
+
+\subsection{Device initialization}\label{sec:Device Types / BT Device / Device initialization}
+
+The virtqueues are initialized.
+
+\subsection{Device operations}\label{sec:Device Types / BT Device / Device operations}
+
+The driver SHOULD populate the receive queue with at least one buffer of at
+least 258 bytes to contain 1 byte "packet type" and HCI event packet (2 bytes
+of HCI event packet header and up to 255 bytes payload).
+Synchronous and asynchronous data packets that are longer than the provided
+buffer will be fragmented.
+
+The driver sends to the transmit queue all (command and data) packets, received
+from the guest HCI device, and transfers to the guest HCI device all (event and
+data) HCI packets, received from the receive queue.
diff --git a/device-types/bt/device-conformance.tex b/device-types/bt/device-conformance.tex
new file mode 100644
index 0000000..7b73f4a
--- /dev/null
+++ b/device-types/bt/device-conformance.tex
@@ -0,0 +1,8 @@
+\conformance{\subsection}{Bluetooth Device Conformance}\label{sec:Conformance / Device Conformance / Bluetooth Device Conformance}
+
+A BT device MUST conform to the following normative statements:
+
+\begin{itemize}
+\item \ref{devicenormative:Device Types / BT Device / Feature bits}
+\item \ref{devicenormative:Device Types / BT Device / Device configuration layout}
+\end{itemize}
diff --git a/device-types/bt/driver-conformance.tex b/device-types/bt/driver-conformance.tex
new file mode 100644
index 0000000..2264a79
--- /dev/null
+++ b/device-types/bt/driver-conformance.tex
@@ -0,0 +1,8 @@
+\conformance{\subsection}{BT Driver Conformance}\label{sec:Conformance / Driver Conformance / BT Driver Conformance}
+
+A BT driver MUST conform to the following normative statements:
+
+\begin{itemize}
+\item \ref{drivernormative:Device Types / BT Device / Feature bits}
+\item \ref{drivernormative:Device Types / BT Device / Driver configuration layout}
+\end{itemize}
-- 
2.37.2


---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org