Bluetooth: Host: Add bt_taskq workqueue for quick non-blocking tasks

Add a new workqueue bt_taskq specifically designed for quick
non-blocking work items in the Bluetooth subsystem. This workqueue is
always available and does not depend on any Kconfig option.

Signed-off-by: Aleksander Wasaznik <[email protected]>

Author: alwa-nordic

subsys/bluetooth/host/CMakeLists.txt

@@ -14,6 +14,7 @@ zephyr_library_sources_ifdef(CONFIG_BT_LONG_WQ          long_wq.c)
 
 if(CONFIG_BT_HCI_HOST)
   zephyr_library_sources(
+    bt_taskq.c
     uuid.c
     addr.c
     buf.c

subsys/bluetooth/host/Kconfig

@@ -165,6 +165,7 @@ menu "Bluetooth Host"
 
 if BT_HCI_HOST
 
+rsource "Kconfig.bt_taskq"
 rsource "../mesh/Kconfig"
 rsource "../audio/Kconfig"
 

subsys/bluetooth/host/Kconfig.bt_taskq

@@ -0,0 +1,58 @@
+# bt_taskq configuration options
+
+# Copyright (c) 2025 Nordic Semiconductor
+# SPDX-License-Identifier: Apache-2.0
+
+choice BT_TASKQ_CONTEXT
+	prompt "bt_taskq thread selection"
+	# nRF51 is too small to have a dedicated thread
+	default BT_TASKQ_SYSTEM_WORKQUEUE if SOC_SERIES_NRF51X
+	default BT_TASKQ_DEDICATED
+	help
+	  Selects in which context the bt_taskq runs.
+
+	  bt_taskq work is quick and non-blocking and must not be
+	  blocked by other work. It should be on a work queue that
+	  is exclusively for non-blocking work.
+
+config BT_TASKQ_DEDICATED
+	bool "Dedicated thread"
+	help
+	  When this option is selected, the bt_taskq runs on a
+	  dedicated thread. This is the default and safe option.
+
+config BT_TASKQ_SYSTEM_WORKQUEUE
+	bool "System workqueue"
+	help
+	  When this option is selected, the bt_taskq is the system
+	  workqueue.
+
+	  WARNING: This is safe only if there is no blocking work on
+	  the system workqueue.
+
+	  This is currently NEVER SAFE to use as the Host itself
+	  puts blocking work on the system workqueue. For now, this
+	  option exists for users that need to free up RAM by not
+	  having an extra thread and are willing to accept the risk
+	  of deadlocks. When using this option, it is advised to
+	  have a watchdog to recover from deadlocks. Risk of
+	  deadlocks can be mitigated by being mindful of buffers and
+	  whole-system analysis.
+
+endchoice
+
+config BT_TASKQ_STACK_SIZE_WITH_PROMPT
+	bool "bt_taskq thread stack size override"
+	depends on BT_TASKQ_DEDICATED
+
+config BT_TASKQ_STACK_SIZE
+	int
+	default 1024
+	prompt "bt_taskq thread stack size" if BT_TASKQ_STACK_SIZE_WITH_PROMPT
+
+config BT_TASKQ_THREAD_PRIO
+    # Hidden option
+	int
+	# -1 is the least urgent cooperative priority.
+	# tx_processor() needs a cooperative thread for now.
+	default -1

subsys/bluetooth/host/bt_taskq.c

@@ -0,0 +1,42 @@
+/* bt_taskq.c - Workqueue for quick non-blocking Bluetooth tasks */
+
+/*
+ * Copyright (c) 2025 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/autoconf.h>
+#include <zephyr/init.h>
+#include <zephyr/kernel.h>
+#include <zephyr/kernel/thread_stack.h>
+#include <zephyr/sys/util_macro.h>
+#include <zephyr/toolchain.h>
+
+static K_THREAD_STACK_DEFINE(bt_taskq_stack, CONFIG_BT_TASKQ_STACK_SIZE);
+static struct k_work_q bt_taskq;
+
+__maybe_unused static int bt_taskq_init(void)
+{
+	struct k_work_queue_config cfg = {};
+
+	if (IS_ENABLED(CONFIG_THREAD_NAME)) {
+		cfg.name = "bt_taskq";
+	}
+
+	k_work_queue_start(&bt_taskq, bt_taskq_stack, K_THREAD_STACK_SIZEOF(bt_taskq_stack),
+			   CONFIG_BT_TASKQ_THREAD_PRIO, &cfg);
+
+	return 0;
+}
+
+#if defined(CONFIG_BT_TASKQ_DEDICATED)
+/* The init priority is set to POST_KERNEL 999, the last level
+ * before APPLICATION.
+ */
+SYS_INIT(bt_taskq_init, POST_KERNEL, 999);
+#endif /* CONFIG_BT_TASKQ_DEDICATED */
+
+/* Exports */
+struct k_work_q *const bt_taskq_chosen =
+	COND_CODE_1(CONFIG_BT_TASKQ_DEDICATED, (&bt_taskq), (&k_sys_work_q));

subsys/bluetooth/host/bt_taskq.h

@@ -0,0 +1,40 @@
+/* bt_taskq.h - Workqueue for quick non-blocking Bluetooth tasks */
+
+/*
+ * Copyright (c) 2025 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/kernel.h>
+
+/**
+ * @brief Bluetooth task workqueue
+ *
+ * bt_taskq is a workqueue intended for quick non-blocking work
+ * items ("tasks") in the Bluetooth subsystem. This workqueue
+ * must always exist and is not controlled by any Kconfig
+ * option.
+ *
+ * Blocking means "waiting for something while running". A
+ * task is NOT allowed to block. If a task need to "wait", it
+ * should instead return immediately and schedule itself to run
+ * later.
+ *
+ * Work items submitted to this queue should be:
+ * - Quick to execute (non-blocking).
+ * - Not perform long-running operations.
+ * - Not block.
+ *
+ * @warning Non-blocking violation pitfalls:
+ * - net_buf_unref() on a foreign buffer could have a blocking
+ *   destroy callback
+ * - Any user-defined callback might be blocking
+ * - Avoid any operations that could sleep or block the thread
+ *
+ * Use bt_long_wq for long-running or potentially blocking
+ * operations instead.
+ *
+ * Available in APPLICATION initialization level and later.
+ */
+extern struct k_work_q *const bt_taskq_chosen;