[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: [PATCH v2 1/1] RFC: virtio-bt: add virtio BT device specification
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]