bluetooth: samples: Add hci_uart_async

This sample is an alternative implementation of hci_uart. The new sample
differs from the existing sample in that it uses the async UART API
instead of the interrupt driven API.

Included in this commit is a new test for HCI UART flow control. It's
enabled for hci_uart_async. The test can excercise also the existing
hci_uart sample (with some minimal changes to allow compiling in the
mock controller and test suite). The existing hci_uart sample currently
fails the flow control test.

Signed-off-by: Aleksander Wasaznik <aleksander.wasaznik@nordicsemi.no>

samples/bluetooth/hci_uart_async/CMakeLists.txt

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20.0)
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+
+project(hci_uart_async)
+target_sources(app PRIVATE
+        src/hci_uart_async.c
+        src/main.c
+)

samples/bluetooth/hci_uart_async/README.rst

@@ -0,0 +1,158 @@
+.. _bluetooth-hci-uart-async-sample:
+
+Bluetooth: HCI UART based on ASYNC UART
+#######################################
+
+Expose a Zephyr Bluetooth Controller over a standard Bluetooth HCI UART interface.
+
+This sample performs the same basic function as the HCI UART sample, but it uses the UART_ASYNC_API
+instead of UART_INTERRUPT_DRIVEN API. Not all boards implement both UART APIs, so the board support
+of the HCI UART sample may be different.
+
+Requirements
+************
+
+* A board with BLE support
+
+Default UART settings
+*********************
+
+By default the controller builds use the following settings:
+
+* Baudrate: 1Mbit/s
+* 8 bits, no parity, 1 stop bit
+* Hardware Flow Control (RTS/CTS) enabled
+
+Building and Running
+********************
+
+This sample can be found under :zephyr_file:`samples/bluetooth/hci_uart_async`
+in the Zephyr tree and is built as a standard Zephyr application.
+
+Using the controller with emulators and BlueZ
+*********************************************
+
+The instructions below show how to use a Nordic nRF5x device as a Zephyr BLE
+controller and expose it to Linux's BlueZ.
+
+First, make sure you have a recent BlueZ version installed by following the
+instructions in the :ref:`bluetooth_bluez` section.
+
+Now build and flash the sample for the Nordic nRF5x board of your choice.
+All of the Nordic Development Kits come with a Segger IC that provides a
+debugger interface and a CDC ACM serial port bridge. More information can be
+found in :ref:`nordic_segger`.
+
+For example, to build for the nRF52832 Development Kit:
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/bluetooth/hci_uart_async
+   :board: nrf52dk_nrf52832
+   :goals: build flash
+
+.. _bluetooth-hci-uart-async-qemu-posix:
+
+Using the controller with QEMU and Native POSIX
+===============================================
+
+In order to use the HCI UART controller with QEMU or Native POSIX you will need
+to attach it to the Linux Host first. To do so simply build the sample and
+connect the UART to the Linux machine, and then attach it with this command:
+
+.. code-block:: console
+
+   sudo btattach -B /dev/ttyACM0 -S 1000000 -R
+
+.. note::
+   Depending on the serial port you are using you will need to modify the
+   ``/dev/ttyACM0`` string to point to the serial device your controller is
+   connected to.
+
+.. note::
+   The ``-R`` flag passed to ``btattach`` instructs the kernel to avoid
+   interacting with the controller and instead just be aware of it in order
+   to proxy it to QEMU later.
+
+If you are running :file:`btmon` you should see a brief log showing how the
+Linux kernel identifies the attached controller.
+
+Once the controller is attached follow the instructions in the
+:ref:`bluetooth_qemu_posix` section to use QEMU with it.
+
+.. _bluetooth-hci-uart-async-bluez:
+
+Using the controller with BlueZ
+===============================
+
+In order to use the HCI UART controller with BlueZ you will need to attach it
+to the Linux Host first. To do so simply build the sample and connect the
+UART to the Linux machine, and then attach it with this command:
+
+.. code-block:: console
+
+   sudo btattach -B /dev/ttyACM0 -S 1000000
+
+.. note::
+   Depending on the serial port you are using you will need to modify the
+   ``/dev/ttyACM0`` string to point to the serial device your controller is
+   connected to.
+
+If you are running :file:`btmon` you should see a comprehensive log showing how
+BlueZ loads and initializes the attached controller.
+
+Once the controller is attached follow the instructions in the
+:ref:`bluetooth_ctlr_bluez` section to use BlueZ with it.
+
+Debugging the controller
+========================
+
+The sample can be debugged using RTT since the UART is reserved used by this
+application. To enable debug over RTT the debug configuration file can be used.
+
+.. code-block:: console
+
+   west build samples/bluetooth/hci_uart_async -- -DEXTRA_CONFIG='debug.mixin.conf'
+
+Then attach RTT as described here: :ref:`Using Segger J-Link <Using Segger J-Link>`
+
+Using the controller with the Zephyr host
+=========================================
+
+This describes how to hook up a board running this sample to a board running
+an application that uses the Zephyr host.
+
+On the controller side, the `zephyr,bt-c2h-uart` DTS property (in the `chosen`
+block) is used to select which uart device to use. For example if we want to
+keep the console logs, we can keep console on uart0 and the HCI on uart1 like
+so:
+
+.. code-block:: dts
+
+   / {
+      chosen {
+         zephyr,console = &uart0;
+         zephyr,shell-uart = &uart0;
+         zephyr,bt-c2h-uart = &uart1;
+      };
+   };
+
+On the host application, some config options need to be used to select the H4
+driver instead of the built-in controller:
+
+.. code-block:: kconfig
+
+   CONFIG_BT_HCI=y
+   CONFIG_BT_CTLR=n
+   CONFIG_BT_H4=y
+
+Similarly, the `zephyr,bt-uart` DTS property selects which uart to use:
+
+.. code-block:: dts
+
+   / {
+      chosen {
+         zephyr,console = &uart0;
+         zephyr,shell-uart = &uart0;
+         zephyr,bt-uart = &uart1;
+      };
+   };

samples/bluetooth/hci_uart_async/app.overlay

@@ -0,0 +1,31 @@
+/* This is the default app device tree overlay. This file is ignored if
+ * there is a board-specific overlay in `./boards`.
+ *
+ * Most boards define a convenient `&uart0`. It's used here to make the
+ * sample 'just work' automatically for those boards.
+ */
+
+bt_c2h_uart: &uart0 {
+        status = "okay";
+        current-speed = <1000000>;
+	hw-flow-control;
+};
+
+/ {
+        chosen {
+                zephyr,bt-c2h-uart = &bt_c2h_uart;
+        };
+};
+
+/* Some boards are by default assigning the &uart0 to these other
+ * functions. Removing the assignments will ensure a compilation error
+ * instead of accidental interference.
+ */
+/ {
+        chosen {
+                 /delete-property/ zephyr,console;
+                 /delete-property/ zephyr,shell-uart;
+                 /delete-property/ zephyr,uart-mcumgr;
+                 /delete-property/ zephyr,bt-mon-uart;
+        };
+};

samples/bluetooth/hci_uart_async/debug.mixin.conf

@@ -0,0 +1,15 @@
+CONFIG_ASSERT_ON_ERRORS=y
+CONFIG_ASSERT=y
+CONFIG_DEBUG_INFO=y
+CONFIG_DEBUG_OPTIMIZATIONS=y
+CONFIG_DEBUG_THREAD_INFO=y
+
+# Enable RTT console
+CONFIG_RTT_CONSOLE=y
+
+CONFIG_LOG=y
+CONFIG_LOG_BUFFER_SIZE=10000
+
+# This outputs all HCI traffic to a separate RTT channel. Use `btmon
+# --jlink` to read it out. Add `--priority 7` for debug logs.
+CONFIG_BT_DEBUG_MONITOR_RTT=y

samples/bluetooth/hci_uart_async/prj.conf

@@ -0,0 +1,25 @@
+# hci_uart_async
+CONFIG_SERIAL=y
+CONFIG_UART_ASYNC_API=y
+
+# hci_raw (dependency of hci_uart)
+CONFIG_BT=y
+CONFIG_BT_HCI_RAW=y
+CONFIG_BT_HCI_RAW_H4=y
+CONFIG_BT_HCI_RAW_H4_ENABLE=y
+
+# Controller configuration. Modify these for your application's needs.
+CONFIG_BT_MAX_CONN=16
+CONFIG_BT_BUF_ACL_RX_SIZE=255
+CONFIG_BT_BUF_CMD_TX_SIZE=255
+CONFIG_BT_BUF_EVT_DISCARDABLE_SIZE=255
+
+# Send an initial HCI_Command_Complete event on boot without waiting for
+# HCI_Reset. Make sure to use the same value for this setting in your
+# host application.
+#CONFIG_BT_WAIT_NOP=y
+
+# See `overlay.app`. The 'zephyr,console' chosen node is deleted there
+# in case it has a interfering default. Those same boards set this
+# config and it must be undone or the build will fail.
+CONFIG_UART_CONSOLE=n