Bluetooth: Add "Connection event callback" feature

The connection event callback feature replaces
the radio notification feature. It can be used to
synchronize data sampling with Bluetooth connection events.

The old feature had several weaknesses:
 - It was not possible to know which connection
   the notification belonged to.
 - The trigger also happened upon flash access.
 - The time from trigger until event start was fixed.
   That is, not configurable per use case.

The new feature is built on top of the connection event
trigger feature and is therefore able to known
which connection a given notification belongs to.

The feature is marked as experimental.
Currently this feature will cancels out peripheral latency
which we indent to change.

Signed-off-by: Rubin Gerritsen <[email protected]>

doc/nrf/protocols/bt/ble/conn_evt_cb.rst

@@ -0,0 +1,37 @@
+.. _ug_bt_conn_evt_cb:
+
+Synchronize data sampling with Bluetooth connection events
+##########################################################
+
+The Bluetooth connection event callback feature is used to inform the application about connection events.
+The connection event prepare callback triggered right before of a Bluetooth connection event.
+This allows the application to trigger sensor data collection for transmission during the upcoming connection event.
+
+.. figure:: images/ConnEvtCb.svg
+   :alt: Connection event prepare callback
+
+   Connection event prepare callback is called before a connection event
+
+The timing of the prepare callback is configured with the parameter `prepare_time_us`.
+The parameter must be set sufficiently large to allow the Bluetooth Stack to enqueue a data packet for the upcoming connection event.
+
+The :ref:`ble_conn_evt_cb` sample application demonstrates how this feature is used to reduce the latency between data sampling and data transmission.
+
+Connection event callback with peripheral latency
+*************************************************
+
+When a connection is configured with peripheral latency, the peripheral device may sleep for `peripheral_latency` consecutive connection events to save power.
+It may wake up more often if, for example if it has data to send.
+Therefore, the central device assumes the peripheral will wake up every connection event.
+
+The connection event prepare callback will be called for every connection event for both the peripheral and central device.
+If the peripheral application provides data to be sent in this callback, the peripheral device will wake up for that given connection event.
+
+.. figure:: images/ConnEvtCbPeripheralLatency.svg
+   :alt: Connection event prepare callback with peripheral latency
+
+   The peripheral wakes up if data is provided in a connection event prepare callback
+
+For this configuration, the application is required to configure the prepare callback to trigger at least 3 ms before the connection event starts.
+This allows the Bluetooth stack to start the high frequency clock and radio peripheral in case they are not already running.
+If the data is provided too close to the start of the connection event, the data will be sent in future connection events.

doc/nrf/protocols/bt/index.rst

@@ -12,5 +12,6 @@ To enable Bluetooth LE in your application, you can use the standard HCI-based a
    :caption: Subpages:
 
    ble/index.rst
+   ble/conn_evt_cb.rst
    bt_mesh/index.rst
    bt_qualification/index.rst

include/bluetooth/evt_cb.h

@@ -0,0 +1,69 @@
+/*
+ * Copyright (c) 2024 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+ */
+
+#ifndef BT_EVT_CB_H__
+#define BT_EVT_CB_H__
+
+/**
+ * @file
+ * @defgroup bt_evt_cb Event callback
+ * @{
+ * @brief APIs to setup event callbacks
+ *
+ * The event callbacks are triggered relative to the
+ * start of a Link Layer event.
+ *
+ * This information can be used to reduce the time from data sampling
+ * until data is sent on air.
+ */
+
+#include <stdint.h>
+#include <zephyr/bluetooth/conn.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** Connection event callbacks
+ *
+ * The callbacks will be called from the system workqueue.
+ */
+struct bt_conn_evt_cb {
+	/** Connection event prepare callback
+	 *
+	 * @param[in] conn      The connection context.
+	 * @param[in] user_data User provided data.
+	 */
+	void (*prepare)(struct bt_conn *conn,
+			void *user_data);
+};
+
+/** Register a connect event callback for a connection.
+ *
+ * @param[in] conn                The connection context.
+ * @param[in] cb                  The callback to be used.
+ * @param[in] user_data           User data which will be provided in the callback.
+ * @param[in] prepare_distance_us The distance in time from the start of the
+ *                                callback to the start of the connection event.
+ *
+ *  @retval 0          The device callbak has been successfully registered.
+ *  @retval -EALREADY  A callback has already been registered for this connection.
+ *  @retval -ENOMEM    There is not enough PPI channels available to use this feature.
+ */
+int bt_conn_evt_cb_register(struct bt_conn *conn,
+			    struct bt_conn_evt_cb cb,
+			    void *user_data,
+			    uint32_t prepare_distance_us);
+
+#ifdef __cplusplus
+}
+#endif
+
+/**
+ * @}
+ */
+
+#endif /* BT_EVT_CB_H__ */

subsys/bluetooth/Kconfig

@@ -38,6 +38,7 @@ config BT_LL_SOFTDEVICE_HEADERS_INCLUDE
 if BT_CTLR
 rsource "controller/Kconfig"
 endif
+rsource "host_extensions/Kconfig"
 
 comment "BLE Libraries"
 rsource "Kconfig.pool"

subsys/bluetooth/host_extensions/CMakeLists.txt

@@ -5,3 +5,4 @@
 #
 
 zephyr_sources(host_extensions.c)
+zephyr_sources_ifdef(CONFIG_BT_CONN_EVT_CB conn_evt_cb.c)