[virtio-comment] [PATCH v2 0/1] Virtio-bt specification draft

[virtio-comment] [PATCH v2 0/1] Virtio-bt specification draft

[Igor Skalkin]

We have been using virtio bluetooth linux kernel driver and virtio bluetooth
devices for some time now, but it still has no spec.
This is the first attempt to start developing this specification.

v2->v1:
 - Few minor fixes.
 - Necessary reference links added to the "Normative References".

 - Changes in the configuration V2:
 - Field "type" had been removed, because Alternate MAC/PHYs (AMP) secondary
   controllers had been removed from the Bluetooth Core Specification since
   version 5.3. And this field is not used in the current virtio-bt Linux
   implementation.
 - Approach of the "vendor" field has been completely changed, now it uses
   documented manufacturer identifiers and does not force the driver to use
   the hard-coded dependencies between non-documented index value and
   vendor-specific parameters.

todo:
   - The main question - "Do we have devices based on original (version 1)
   configuration, or we can simple purge this version 1 configuration?" - still
   has no answer(.
   - SCO over HCI test still in process, it is not clear do we need to add
   separate queue for the out of band data.

Igor Skalkin (1):
  RFC: virtio-bt: add virtio BT device specification

 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

-- 
2.40.1


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

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

[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


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

Re: [virtio-comment] [PATCH v2 1/1] RFC: virtio-bt: add virtio BT device specification

[Cornelia Huck]

On Thu, Dec 07 2023, Igor Skalkin <Igor.Skalkin@opensynergy.com> wrote:

> 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.

Is there any good way to describe this without using guest/host
terminology while using the typical guest/host setup as an example
instead?

> +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.

ISTR that it was "violates the requirements for configuration space
accesses for some transports"? That might be a bit clearer.

And if that's the case, can we maybe require that the device MUST
require the driver to accept the feature bit if the transport the device
uses cannot deal with v1?

> +
> +The device should offer \field{VIRTIO_BT_F_MSFT_EXT} or

s/should offer/SHOULD offer the/

> +\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

"the device SHOULD also set the configuration field"

> +field \field{msft_opcode}.
> +
> +The device should offer \field{VIRTIO_BT_F_VND_HCI} feature bit and set

s/should offer/SHOULD offer the/
s/set/set the/

> +configuration field \field{vendor}, if it supports corresponding vendor

s/corresponding/the corresponding/

> +extensions. Also, in case of second configuration version, fields

s/in case of second configuration version/if VIRTIO_BT_F_CONFIG_V2 is negotiated/

> +\field{set_bdaddr_opcode} and \field{quirks} can be set according to this

MAY be set? Or SHOULD be set?

> +\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}.

Any MUST statement has to go into a normative section.


> +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.

All of the above should probably go into a "Note" statement, as it
basically explains why things are as they are?

> +\item[\field{msft_opcode}]
> +This field is used by the driver if device offers \field{VIRTIO_BT_F_MSFT_EXT}

s/device/the device/

> +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.

Again, MUST statements have to go into a normative section.

> +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}.

Some of this should be extracted into some kind of "Note" as well. IIUC,
the aim here is to specify what the Linux driver expects, so that people
can write devices that driver works with out of the box, and that
informs the specification here?

> +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}

s/fields/field/
s/device/the device/

> +feature bit.
> +\end{description}


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/