diff mbox series

[BlueZ] test-runner: Add documentation

Message ID 20230706231000.451145-1-luiz.dentz@gmail.com
State New
Headers show
Series [BlueZ] test-runner: Add documentation | expand

Commit Message

Luiz Augusto von Dentz July 6, 2023, 11:10 p.m. UTC 
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>

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

Comments

patchwork-bot+bluetooth@kernel.org July 10, 2023, 7:40 p.m. UTC | #1 
Hello:

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

On Thu,  6 Jul 2023 16:10:00 -0700 you wrote:
> From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
> 
> 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.
> 
> [...]

Here is the summary with links:
  - [BlueZ] test-runner: Add documentation
    https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=c96eb3ea5537

You are awesome, thank you!
diff mbox series

Patch

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@intel.com>
+: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]