[PATCH BlueZ v1 10/27] doc: Add btvirt documentation

[Luiz Augusto von Dentz <luiz.dentz@gmail.com>]

From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>

Document the btvirt options, the ways it exposes the emulated
controllers and which of them share the emulated air interface.

Assisted-by: Claude:claude-opus-5-5
---
 Makefile.am    |   1 +
 doc/btvirt.rst | 153 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 154 insertions(+)
 create mode 100644 doc/btvirt.rst

diff --git a/Makefile.am b/Makefile.am
index f742458d113e..26884a54ea06 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -494,6 +494,7 @@ EXTRA_DIST += SECURITY.md
 EXTRA_DIST += doc/assigned-numbers.rst doc/supported-features.txt \
 				doc/test-coverage.txt \
 				doc/test-runner.rst \
+				doc/btvirt.rst \
 				doc/test-functional.rst \
 				doc/functional-testing.rst \
 				doc/functional-a2dp.rst \
diff --git a/doc/btvirt.rst b/doc/btvirt.rst
new file mode 100644
index 000000000000..2e016406a4fc
--- /dev/null
+++ b/doc/btvirt.rst
@@ -0,0 +1,153 @@
+======
+btvirt
+======
+
+-----------------------------
+Bluetooth controller emulator
+-----------------------------
+
+:Version: BlueZ
+:Copyright: Free use of this software is granted under the terms of the GNU
+            Lesser General Public Licenses (LGPL).
+:Date: October 2026
+:Manual section: 1
+:Manual group: Linux System Administration
+
+SYNOPSIS
+========
+
+**btvirt** [*OPTIONS*]
+
+DESCRIPTION
+===========
+
+**btvirt(1)** emulates Bluetooth controllers in software. It is used to test
+the kernel Bluetooth subsystem and BlueZ without real hardware, most notably
+by **test-runner(1)** and **test-functional(1)**.
+
+The controllers are implemented by the BlueZ emulator (``emulator/btdev.c``)
+and speak HCI. They can be exposed to a Bluetooth stack in several ways:
+
+- as local virtual controllers through ``/dev/vhci`` (**-l**), which then
+  appear as ``hciN`` on the machine running btvirt;
+- as H:4 streams on Unix socket servers (**-s**) or a TCP server (**-t**),
+  one controller per client connection;
+- as an H:4 stream on a pseudo terminal (**-S**).
+
+All controllers created by one btvirt process share an emulated air
+interface: they can discover, connect to and exchange data with each other,
+regardless of how each one is exposed. Controllers in different btvirt
+processes cannot see each other, except for the test LE controllers created
+with **-U**, see below.
+
+btvirt runs until it receives **SIGINT** or **SIGTERM**.
+
+OPTIONS
+=======
+
+At least one of **-l**, **-s**, **-t**, **-S** or **-U** must be given.
+Optional arguments must be attached to the option, as in **-l2**,
+**-t45551** or **--server=/tmp/bt**.
+
+-l[num], --local[=num]      Create *num* local virtual controllers through
+                            ``/dev/vhci`` (default: 1). Requires access to
+                            ``/dev/vhci``. The controller type is selected
+                            with **-L**, **-B**, **-A** or **-C**.
+
+-s[path], --server[=path]   Create Unix socket servers in the directory
+                            *path* (default: ``/tmp``). Each client that
+                            connects gets a new controller of the server's
+                            type, attached as an H:4 stream. The following
+                            sockets are created:
+
+                            ``bt-server-bredrle``
+                                BR/EDR/LE controllers, of the version given
+                                with **-C**
+                            ``bt-server-bredr``
+                                BR/EDR-only controllers
+                            ``bt-server-le``
+                                LE-only controllers
+                            ``bt-server-amp``
+                                AMP controllers
+                            ``bt-server-mon``
+                                monitor socket, no controller is created
+
+-t[port], --tcp[=port]      Create a TCP server on *port* (default: 45550).
+                            Each client that connects gets a new BR/EDR/LE
+                            controller, of the version given with **-C**,
+                            attached as an H:4 stream. The server listens on
+                            127.0.0.1 only.
+
+-S, --serial                Create a pseudo terminal with a BR/EDR/LE
+                            controller attached as an H:4 stream. The path of
+                            the terminal is printed on startup; attach it
+                            with **btattach(1)**.
+
+-U[num], --letest[=num]     Create *num* test LE controllers (default: 1)
+                            through ``/dev/vhci``. Unlike the other
+                            controllers, these exchange radio traffic with
+                            test LE controllers in other btvirt processes,
+                            using UDP broadcasts on port 45023.
+
+-L, --le                    Make the controllers created with **-l** LE-only.
+
+-B, --bredr                 Make the controllers created with **-l**
+                            BR/EDR-only.
+
+-A, --amp                   Make the controllers created with **-l** AMP
+                            controllers.
+
+-C version, --core=version  Core Specification version of the BR/EDR/LE
+                            controllers created with **-l**, **-s** (on
+                            ``bt-server-bredrle``) and **-t**. Supported
+                            values are ``5.0``, ``5.2``, ``6.0`` and ``6.2``
+                            (default).
+
+-d, --debug                 Enable debug output for the **-l** and **-s**
+                            controllers.
+
+-v, --version               Show version.
+
+-h, --help                  Show help options.
+
+VENDOR COMMANDS
+===============
+
+Controllers created with **-l** answer two vendor commands, so the kernel
+treats them as supporting the corresponding extensions:
+
+- opcode ``0xfc10``: emulator-specific vendor command;
+- opcode ``0xfc1e``: Microsoft vendor extension (MSFT).
+
+EXAMPLES
+========
+
+Create two local controllers, which show up as ``hciN`` and can connect to
+each other::
+
+    $ sudo btvirt -l2
+
+Serve controllers to virtual machines, one per connecting VM, the way
+**test-functional(1)** does::
+
+    $ btvirt --server=/tmp/bt
+    $ test-runner -u/tmp/bt/bt-server-bredrle -k bzImage -- ...
+
+Emulate a Bluetooth 5.2 controller over TCP::
+
+    $ btvirt -C 5.2 -t
+
+RESOURCES
+=========
+
+http://www.bluez.org
+
+REPORTING BUGS
+==============
+
+linux-bluetooth@vger.kernel.org
+
+SEE ALSO
+========
+
+**test-runner(1)**, **test-functional(1)**, **btattach(1)**
-- 
2.56.0