* [virtio-dev] [PATCH v2 1/1] RFC: virtio-bt: add virtio BT device specification
2023-12-07 16:37 [virtio-dev] [PATCH v2 0/1] Virtio-bt specification draft Igor Skalkin
@ 2023-12-07 16:37 ` Igor Skalkin
2024-01-15 15:09 ` [virtio-dev] Re: [virtio-comment] " Cornelia Huck
0 siblings, 1 reply; 3+ messages in thread
From: Igor Skalkin @ 2023-12-07 16:37 UTC (permalink / raw)
To: virtio-dev, virtio-comment, luiz.dentz, mst
Cc: marcel, johan.hedberg, jasowang, boris.le.labousse, Igor Skalkin
This PR is aimed as review for comments(RFC) purpose.
* Initial draft version.
---
conformance.tex | 12 +-
content.tex | 1 +
device-types/bt/description.tex | 158 +++++++++++++++++++++++++
device-types/bt/device-conformance.tex | 7 ++
device-types/bt/driver-conformance.tex | 7 ++
introduction.tex | 15 +++
6 files changed, 196 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 dc00e84..86c7db1 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 0a62dce..b67b3e5 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/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..98311f4
--- /dev/null
+++ b/device-types/bt/description.tex
@@ -0,0 +1,158 @@
+\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 operational system / vendor
+ specific HCI extensions it supports.
+Host Control Interface is described in Bluetooth Core Specification (see
+\hyperref[intro:bluetooth-core]{Bluetooth Core Specification}).
+
+\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)] The device supports vendor-specific HCI
+extensions.
+\item[VIRTIO_BT_F_MSFT_EXT (1)] The device supports Microsoft HCI Extensions.
+\item[VIRTIO_BT_F_AOSP_EXT (2)] The device supports Android HCI Extensions.
+\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 MAY require the driver to accept the \field{VIRTIO_BT_F_CONFIG_V2}
+feature bit and use the second version of the configuration layout, because the
+first one is unaligned, which violates the specification.
+
+The device should offer \field{VIRTIO_BT_F_MSFT_EXT} or
+\field{VIRTIO_BT_F_AOSP_EXT} feature bit if it supports correspondingly MSFT or
+AOSP extension command sets (see \hyperref[intro:bluetooth-aosp]{Bluetooth AOSP
+HCI Extensions}, \hyperref[intro:bluetooth-msft]{Bluetooth MSFT HCI Extensions}
+). In case of \field{VIRTIO_BT_F_MSFT_EXT}, device should also set configuration
+field \field{msft_opcode}.
+
+The device should offer \field{VIRTIO_BT_F_VND_HCI} feature bit and set
+configuration field \field{vendor}, if it supports corresponding vendor
+extensions. Also, in case of second configuration version, fields
+\field{set_bdaddr_opcode} and \field{quirks} can be set according to this
+\field{vendor}.
+
+\drivernormative{\subsubsection}{Feature bits}{Device Types / BT Device / Feature bits}
+
+The driver MUST accept \field{VIRTIO_BT_F_CONFIG_V2} feature bit if offered by
+the device.
+
+The driver SHOULD accept any of the \field{VIRTIO_BT_F_VND_HCI},
+\field{VIRTIO_BT_F_MSFT_EXT} or \field{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}
+BT device supports two versions of the configuration structure layout.
+\subsubsection{Device configuration layout: Version 1}\label{sec:Device Types / BT Device / Device configuration layout / Verion 1}
+
+All fields of this configuration are always available and read-only for the
+driver.
+\begin{lstlisting}
+struct virtio_bt_config {
+ u8 type;
+ le16 vendor;
+ le16 msft_opcode;
+} __attribute__((packed));
+\end{lstlisting}
+
+\begin{description}
+
+\item[\field{type}] indicates the type of the device, is it "Primary BR/EDR
+controller" or "Alternate MAC/PHYs (AMP) secondary controller" and can have the
+following values:
+\begin{lstlisting}
+#define VIRTIO_BT_CONFIG_TYPE_PRIMARY 0
+#define VIRTIO_BT_CONFIG_TYPE_AMP 1
+\end{lstlisting}
+
+\item[\field{vendor}]
+Indicates the vendor of the BT device and can have the following mutually
+exclusive values:
+\begin{lstlisting}
+#define VIRTIO_BT_CONFIG_VENDOR_NONE 0
+#define VIRTIO_BT_CONFIG_VENDOR_ZEPHYR 1
+#define VIRTIO_BT_CONFIG_VENDOR_INTEL 2
+#define VIRTIO_BT_CONFIG_VENDOR_REALTEK 3
+\end{lstlisting}
+The device MUST offer the \field{VIRTIO_BT_F_VND_HCI} feature bit if it sets
+\field{vendor} to any value other than \field{VIRTIO_BT_CONFIG_VENDOR_NONE}.
+In the current Linux implementation of virtio-bt, these values are simply
+hard-coded and point to the hard-coded (\field{manufacturer},
+\field{set_bdaddr_opcode}, \field{quirks}) parameters, there
+\field{manufacturer} is a "Company Identifier" from the
+\hyperref[intro:bluetooth-numbers]{Bluetooth Assigned Numbers}, Chapter 7
+(Company Identifiers).
+This approach is not extensible and has been replaced in the second version of
+the configuration.
+\item[\field{msft_opcode}]
+This field is used by the driver if device offers \field{VIRTIO_BT_F_MSFT_EXT}
+feature bit.
+\end{description}
+
+\subsubsection{Device configuration layout: Version 2}\label{sec:Device Types / BT Device / Device configuration layout / Version 2}
+All fields of this configuration are always available and read-only for the
+driver.
+\begin{lstlisting}
+struct virtio_bt_config_v2 {
+ le16 vendor;
+ le16 set_bdaddr_opcode;
+ le32 quirks;
+ le16 msft_opcode;
+};
+\end{lstlisting}
+
+\begin{description}
+
+\item[\field{vendor}] - Manufacturer identifier, for the possible values see
+\hyperref[intro:bluetooth-numbers]{Bluetooth Assigned Numbers}, Chapter 7
+(Company Identifiers).
+The device MUST offer the VIRTIO_BT_F_VND_HCI feature bit if it sets
+\field{vendor} to any value other than VIRTIO_BT_CONFIG_VENDOR_NONE.
+According to the Linux guest driver implementation, devices from different
+vendors can have different opcodes for the \field{set_bdaddr} (Bluetooth Device
+Address) command, and the different \field{quirks} bits (list and short
+description of these \field{quirks} you can find in
+\hyperref[intro:bluetooth-quirks]{Bluetooth HCI device quirks}.
+So, next two fields allow us to set these parameters.
+
+\item[\field{set_bdaddr_opcode}] - opcode for the set_bdaddr (Bluetooth Device
+Address) command.
+\item[\field{quirks}] - Quirks bits supported by the device.
+\hyperref[intro:bluetooth-quirks]{Bluetooth HCI device quirks}
+
+\item[\field{msft_opcode}]
+This fields is used by the driver if device offers \field{VIRTIO_BT_F_MSFT_EXT}
+feature bit.
+\end{description}
+
+\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 populates 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..283b0e1
--- /dev/null
+++ b/device-types/bt/device-conformance.tex
@@ -0,0 +1,7 @@
+\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}
+\end{itemize}
diff --git a/device-types/bt/driver-conformance.tex b/device-types/bt/driver-conformance.tex
new file mode 100644
index 0000000..80bb235
--- /dev/null
+++ b/device-types/bt/driver-conformance.tex
@@ -0,0 +1,7 @@
+\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}
+\end{itemize}
diff --git a/introduction.tex b/introduction.tex
index cfa6633..d524fce 100644
--- a/introduction.tex
+++ b/introduction.tex
@@ -145,6 +145,21 @@ \section{Normative References}\label{sec:Normative References}
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP
14, RFC 8174, DOI 10.17487/RFC8174, May 2017
\newline\url{http://www.ietf.org/rfc/rfc8174.txt}\\
+ \phantomsection\label{intro:bluetooth-core}\textbf{[BT Core]} &
+ Bluetooth Core Specification
+ \newline\url{http://www.bluetooth.com/specifications/specs/core-specification-5-4}\\
+ \phantomsection\label{intro:bluetooth-aosp}\textbf{[BT AOSP]} &
+ Bluetooth AOSP HCI Extensions
+ \newline\url{http://source.android.com/docs/core/connect/bluetooth/hci_requirements}\\
+ \phantomsection\label{intro:bluetooth-msft}\textbf{[BT MSFT]} &
+ Bluetooth Microsoft HCI Extensions
+ \newline\url{http://learn.microsoft.com/en-us/windows-hardware/drivers/bluetooth/microsoft-defined-bluetooth-hci-commands-and-events}\\
+ \phantomsection\label{intro:bluetooth-quirks}\textbf{[BT HCI quirks]} &
+ Bluetooth HCI device quirks
+ \newline\url{https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/net/bluetooth/hci.h}\\
+ \phantomsection\label{intro:bluetooth-numbers}\textbf{[BT vendors]} &
+ Bluetooth Assigned Numbers Document
+ \newline\url{https://www.bluetooth.com/specifications/assigned-numbers}\\
\end{longtable}
\section{Non-Normative References}
--
2.40.1
---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
^ permalink raw reply related [flat|nested] 3+ messages in thread