From: Luiz Augusto von Dentz <luiz.von.dentz@xxxxxxxxx> This adds test-runner.rst documentation with a few examples of how it can be used to run kernel testers like mgmt-tester and also bluetoothd, audio and Bluetooth controller plugged in the host system which is quite useful when trying experimental features such LE Audio, etc. --- tools/test-runner.rst | 200 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 200 insertions(+) create mode 100644 tools/test-runner.rst diff --git a/tools/test-runner.rst b/tools/test-runner.rst new file mode 100644 index 000000000000..ac3986ab14c0 --- /dev/null +++ b/tools/test-runner.rst @@ -0,0 +1,200 @@ +=========== +test-runner +=========== + +------------------ +Kernel test runner +------------------ + +:Authors: - Luiz Augusto Von Dentz <luiz.von.dentz@xxxxxxxxx> +:Version: BlueZ +:Copyright: Free use of this software is granted under ther terms of the GNU + Lesser General Public Licenses (LGPL). +:Date: Jul 6, 2023 +:Manual section: 1 +:Manual group: Linux System Administration + +SYNOPSIS +======== + +**test-runner** [*OPTIONS*] -- <test-name> + +DESCRIPTION +=========== + +**test-runner(1)** is used to test Kernel changes to the Bluetooth subsystem, +it lunches a virtual machine using the local filesystem. + +OPTIONS +======= + +-a, --auto Find tests and run them + +-b, --dbus Start D-Bus system daemon + +-s, --dbus-session Start D-Bus session daemon + +-d, --daemon Start bluetoothd + +-m, --monitor Start btmon + +-l, --emulator Start btvirt + +-A, --audio[=path] Start audio server + +-u, --unix [path] Provide serial device + +-q, --qemu <path> QEMU binary + +-k, --kernel <image> Kernel image (bzImage) + +-h, --help Show help options + +Kernel +====== + +The test-runner tool requires a kernel that is at least build with these +minimal options for a successful boot. These options should be installed as +.config in the kernel source directory followed by: + +.. code-block:: + + make olddefconfig + +After that a default kernel with the required options can be built. More +option (like the Bluetooth subsystem) can be enabled on top of this. + +.. code-block:: + + CONFIG_VIRTIO=y + CONFIG_VIRTIO_PCI=y + + CONFIG_NET=y + CONFIG_INET=y + + CONFIG_NET_9P=y + CONFIG_NET_9P_VIRTIO=y + + CONFIG_9P_FS=y + CONFIG_9P_FS_POSIX_ACL=y + + CONFIG_SERIAL_8250=y + CONFIG_SERIAL_8250_CONSOLE=y + CONFIG_SERIAL_8250_PCI=y + CONFIG_SERIAL_8250_NR_UARTS=4 + + CONFIG_TMPFS=y + CONFIG_TMPFS_POSIX_ACL=y + CONFIG_TMPFS_XATTR=y + + CONFIG_DEVTMPFS=y + CONFIG_DEBUG_FS=y + +Bluetooth +--------- + +.. code-block:: + + CONFIG_BT=y + CONFIG_BT_BREDR=y + CONFIG_BT_RFCOMM=y + CONFIG_BT_BNEP=y + CONFIG_BT_HIDP=y + CONFIG_BT_LE=y + + CONFIG_BT_HCIUART=y + CONFIG_BT_HCIUART_H4=y + CONFIG_BT_HCIVHCI=y + + CONFIG_CRYPTO_CMAC=y + CONFIG_CRYPTO_USER_API=y + CONFIG_CRYPTO_USER_API_HASH=y + CONFIG_CRYPTO_USER_API_SKCIPHER=y + + CONFIG_UNIX=y + + CONFIG_UHID=y + +Lock debuging +------------- + +To catch locking related issues the following set of kernel config +options may be useful: + +.. code-block:: + + CONFIG_DEBUG_KERNEL=y + CONFIG_LOCKDEP_SUPPORT=y + CONFIG_DEBUG_SPINLOCK=y + CONFIG_DEBUG_LOCK_ALLOC=y + CONFIG_DEBUG_ATOMIC_SLEEP=y + CONFIG_PROVE_LOCKING=y + CONFIG_PROVE_RCU=y + CONFIG_LOCKDEP=y + CONFIG_DEBUG_MUTEXES=y + +EXAMPLES +======== + +Running mgmt-tester +------------------- + +.. code-block:: + + $ tools/test-runner -k /pathto/bzImage -- tools/mgmt-tester + +Running a specific test of mgmt-tester +-------------------------------------- + +.. code-block:: + + $ tools/test-runner -k /pathto/bzImage -- tools/mgmt-tester -s "<name>" + +Running bluetoothctl with emulated controller +--------------------------------------------- + +.. code-block:: + + $ tools/test-runner -l -d -k /pathto/bzImage -- client/bluetoothctl + [CHG] Controller 00:AA:01:00:00:00 Pairable: yes + [bluetooth]# + +Running bluetoothctl with emulated controller and audio support +--------------------------------------------------------------- + +.. code-block:: + + $ tools/test-runner -l -d -A -k /pathto/bzImage -- client/bluetoothctl + [CHG] Controller 00:AA:01:00:00:00 Pairable: yes + [bluetooth]# + [CHG] Controller 00:AA:01:00:00:00 Pairable: yes + [CHG] Controller 00:AA:01:00:00:00 Class: 0x00600000 (6291456) + [CHG] Controller 00:AA:01:00:00:00 UUIDs: 0000110e-0000-1000-8000-00805f9b34fb + [CHG] Controller 00:AA:01:00:00:00 UUIDs: 0000111f-0000-1000-8000-00805f9b34fb + [CHG] Controller 00:AA:01:00:00:00 UUIDs: 00001200-0000-1000-8000-00805f9b34fb + [CHG] Controller 00:AA:01:00:00:00 UUIDs: 0000110b-0000-1000-8000-00805f9b34fb + [CHG] Controller 00:AA:01:00:00:00 UUIDs: 0000110a-0000-1000-8000-00805f9b34fb + [CHG] Controller 00:AA:01:00:00:00 UUIDs: 0000110c-0000-1000-8000-00805f9b34fb + [CHG] Controller 00:AA:01:00:00:00 UUIDs: 00001800-0000-1000-8000-00805f9b34fb + [CHG] Controller 00:AA:01:00:00:00 UUIDs: 00001801-0000-1000-8000-00805f9b34fb + [CHG] Controller 00:AA:01:00:00:00 UUIDs: 0000180a-0000-1000-8000-00805f9b34fb + [CHG] Controller 00:AA:01:00:00:00 UUIDs: 0000111e-0000-1000-8000-00805f9b34fb + [CHG] Controller 00:AA:01:00:00:00 Class: 0x006c0000 (7077888) + [CHG] Controller 00:AA:01:00:00:00 UUIDs: 0000110e-0000-1000-8000-00805f9b34fb + [CHG] Controller 00:AA:01:00:00:00 UUIDs: 0000111f-0000-1000-8000-00805f9b34fb + [CHG] Controller 00:AA:01:00:00:00 UUIDs: 00001200-0000-1000-8000-00805f9b34fb + [CHG] Controller 00:AA:01:00:00:00 UUIDs: 0000110b-0000-1000-8000-00805f9b34fb + [CHG] Controller 00:AA:01:00:00:00 UUIDs: 0000110a-0000-1000-8000-00805f9b34fb + [CHG] Controller 00:AA:01:00:00:00 UUIDs: 0000110c-0000-1000-8000-00805f9b34fb + [CHG] Controller 00:AA:01:00:00:00 UUIDs: 00001800-0000-1000-8000-00805f9b34fb + [CHG] Controller 00:AA:01:00:00:00 UUIDs: 00001801-0000-1000-8000-00805f9b34fb + [CHG] Controller 00:AA:01:00:00:00 UUIDs: 0000180a-0000-1000-8000-00805f9b34fb + [CHG] Controller 00:AA:01:00:00:00 UUIDs: 0000111e-0000-1000-8000-00805f9b34fb + +Running shell with host controller using btproxy +------------------------------------------------ + +.. code-block:: + + $ tools/btproxy -u [1] + $ tools/test-runner -u -d -k /pathto/bzImage -- /bin/bash [2] -- 2.40.1
