[PATCH BlueZ v1] doc/test-functional: Document PCIe controller passthrough

[PATCH BlueZ v1] doc/test-functional: Document PCIe controller passthrough

[Luiz Augusto von Dentz]

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

The tests needing a real controller can now use a PCIe one with --pcie
and --force-pcie, in the same way --usb and --force-usb use an USB one.

Unlike an USB controller, which only needs its device node to be
readable, a PCIe controller is bound to vfio-pci while a VM host uses
it, so the tests have to be run as root and the controller has to be
alone in its IOMMU group.

The model wrote the option handling in pytest-bluezenv and this section;
it was reviewed and tested by the author.

Assisted-by: Claude:claude-opus-5
---
 doc/test-functional.rst | 51 +++++++++++++++++++++++++++++++++++++----
 1 file changed, 46 insertions(+), 5 deletions(-)

diff --git a/doc/test-functional.rst b/doc/test-functional.rst
index 4a784e7850a3..3ffcbf6dec5c 100644
--- a/doc/test-functional.rst
+++ b/doc/test-functional.rst
@@ -107,6 +107,20 @@ The following additional options apply:
 ``--force-usb``
         Force tests to use USB controllers instead of `btvirt`.
 
+``--pcie=hci0,hci1``
+        PCIe controllers to use in tests that require use of
+	real controllers.
+
+	If not provided, value from `FUNCTIONAL_TESTING_CONTROLLERS`
+	environment variable is used. If none, all PCIe controllers
+	are considered.
+
+	Passing a PCIe controller through binds it to vfio-pci for
+	the time a VM host uses it, which requires running as root.
+
+``--force-pcie``
+        Force tests to use PCIe controllers instead of `btvirt`.
+
 ``--bluez-build-dir=<path>``
         Path to build directory where to search for BlueZ
         executables.
@@ -139,7 +153,7 @@ The following additional options apply:
         Git branch to build from.
 
 
-Tests that require kernel image or USB controllers are skipped if none
+Tests that require kernel image or real controllers are skipped if none
 are available. Normally, tests use `btvirt`.
 
 VM instances share a directory ``/run/shared`` with host machine,
@@ -224,10 +238,10 @@ socket, also bridging the air interface between them::
 
 See **test-runner(1)** for how the socket is attached to the VM.
 
-With ``--usb`` the ``btvirt`` process is not started; each VM host gets a
-real USB controller passed through instead, and the VMs talk over the
-actual radio.  Tests still prefer ``btvirt`` unless ``--force-usb`` is
-given.
+With ``--usb`` or ``--pcie`` the ``btvirt`` process is not started; each
+VM host gets a real USB or PCIe controller passed through instead, and the
+VMs talk over the actual radio.  Tests still prefer ``btvirt`` unless
+``--force-usb`` or ``--force-pcie`` is given.
 
 Writing test code that runs in the VM, and the available VM-side
 facilities, are documented by `pytest-bluezenv
@@ -306,6 +320,17 @@ USB
 
 Some tests may require a hardware controller instead of the virtual `btvirt` one.
 
+PCIe
+----
+
+A PCIe controller may be used instead of a USB one. It is bound to
+vfio-pci for the time a VM host uses it, and bound back to its own
+driver afterwards, which requires running the tests as root.
+
+The IOMMU has to be enabled on the host, and the controller has to be
+alone in its IOMMU group. See **test-runner(1)** for the kernel config
+the passed through controller needs.
+
 EXAMPLES
 ========
 
@@ -422,6 +447,22 @@ possible.  To force all tests use the USB controllers:
 
 	$ test/test-functional --usb=hci0,hci1 --force-usb
 
+Redirect PCIe devices
+---------------------
+
+.. code-block::
+
+	$ sudo test/test-functional --pcie=hci0,hci1
+
+Unlike USB controllers, this requires running as root, as the controller
+is bound to vfio-pci while a VM host uses it.
+
+To force all tests use the PCIe controllers:
+
+.. code-block::
+
+	$ sudo test/test-functional --pcie=hci0,hci1 --force-pcie
+
 Run tests in parallel
 ---------------------
 
-- 
2.55.0

RE: [BlueZ,v1] doc/test-functional: Document PCIe controller passthrough

[bluez.test.bot]

[-- Attachment #1: Type: text/plain, Size: 3738 bytes --]

This is automated email and please do not reply to this email!

Dear submitter,

Thank you for submitting the patches to the linux bluetooth mailing list.
This is a CI test results with your patch series:
PW Link:https://patchwork.kernel.org/series/1165941/

---Test result---

Test Summary:
CheckPatch                    PASS      0.32 seconds
GitLint                       PASS      0.25 seconds
BuildEll                      PASS      15.84 seconds
BluezMake                     PASS      276.90 seconds
MakeCheck                     PASS      13.46 seconds
MakeDistcheck                 PASS      118.63 seconds
CheckValgrind                 PASS      197.52 seconds
CheckSmatch                   PASS      209.66 seconds
bluezmakeextell               PASS      78.72 seconds
TestFunctional                FAIL      940.94 seconds
IncrementalBuild              PASS      283.90 seconds
ScanBuild                     PASS      812.82 seconds

Details
##############################
Test: TestFunctional - FAIL
Desc: Run test-functional
Output:
FAIL functional.test_bap::test_bass_past_transport_acquire[hosts6-vm2]: pytest_bluezenv.rpc.RemoteError: <pexpect.popen_spawn.PopenSpawn object at 0x7fdddfacea50>
    searcher: searcher_re:
        0: re.compile(b'Acquire successful: fd \\d+ MTU \\d+:\\d+')
        1: re.compile(b'Transport /org/bluez/hci0/dev_00_AA_01_00_00_42/bis1/fd0 State: active')
    <pexpect.popen_spawn.PopenSpawn object at 0x7fdddfacea50>
    searcher: searcher_re:
        0: re.compile(b'Acquire successful: fd \\d+ MTU \\d+:\\d+')
        1: re.compile(b'Transport /org/bluez/hci0/dev_00_AA_01_00_00_42/bis1/fd0 State: active')
    Remote traceback:
        Traceback (most recent call last):
          File "/usr/local/lib/python3.14/dist-packages/pytest_bluezenv/../pytest_bluezenv/rpc.py", line 102, in server_stream
            result = method(*msg["a"], **msg["kw"])
          File "/usr/local/lib/python3.14/dist-packages/pytest_bluezenv/../pytest_bluezenv/env.py", line 256, in call_plugin
            return getattr(self.plugins[name], method)(*a, **kw)
                   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^
          File "/usr/local/lib/python3.14/dist-packages/pytest_bluezenv/../pytest_bluezenv/host_plugins.py", line 441, in expect
            ret = ctl.expect(*a, **kw)
          File "/usr/lib/python3/dist-packages/pexpect/spawnbase.py", line 354, in expect
            return self.expect_list(compiled_pattern_list,
                   ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^
                    timeout, searchwindowsize, async_)
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
          File "/usr/lib/python3/dist-packages/pexpect/spawnbase.py", line 383, in expect_list
            return exp.expect_loop(timeout)
                   ~~~~~~~~~~~~~~~^^^^^^^^^
          File "/usr/lib/python3/dist-packages/pexpect/expect.py", line 181, in expect_loop
            return self.timeout(e)
                   ~~~~~~~~~~~~^^^
          File "/usr/lib/python3/dist-packages/pexpect/expect.py", line 144, in timeout
            raise exc
        pexpect.exceptions.TIMEOUT: <pexpect.popen_spawn.PopenSpawn object at 0x7fdddfacea50>
        searcher: searcher_re:
            0: re.compile(b'Acquire successful: fd \\d+ MTU \\d+:\\d+')
            1: re.compile(b'Transport /org/bluez/hci0/dev_00_AA_01_00_00_42/bis1/fd0 State: active')
        <pexpect.popen_spawn.PopenSpawn object at 0x7fdddfacea50>
        searcher: searcher_re:
            0: re.compile(b'Acquire successful: fd \\d+ MTU \\d+:\\d+')
            1: re.compile(b'Transport /org/bluez/hci0/dev_00_AA_01_00_00_42/bis1/fd0 State: active')


https://github.com/bluez/bluez/pull/2532

---
Regards,
Linux Bluetooth

Re: [PATCH BlueZ v1] doc/test-functional: Document PCIe controller passthrough

[patchwork-bot+bluetooth]

Hello:

This patch was applied to bluetooth/bluez.git (master)
by Luiz Augusto von Dentz <luiz.von.dentz@intel.com>:

On Tue, 15 Sep 2026 17:44:10 -0400 you wrote:
> From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
> 
> The tests needing a real controller can now use a PCIe one with --pcie
> and --force-pcie, in the same way --usb and --force-usb use an USB one.
> 
> Unlike an USB controller, which only needs its device node to be
> readable, a PCIe controller is bound to vfio-pci while a VM host uses
> it, so the tests have to be run as root and the controller has to be
> alone in its IOMMU group.
> 
> [...]

Here is the summary with links:
  - [BlueZ,v1] doc/test-functional: Document PCIe controller passthrough
    https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=1effba22606a

You are awesome, thank you!
-- 
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html