sdh: simplifications and improvements

doc/nrf-bm/release_notes/release_notes_changelog.rst

@@ -30,6 +30,7 @@ SoftDevice Handler
 * Added:
 
   * The :option:`NRF_SDH_SOC_RAND_SEED` Kconfig option to control whether to automatically respond to SoftDevice random seed requests.
+  * Priority levels for SoftDevice event observers: HIGHEST, HIGH, USER, USER_LOW, LOWEST.
 
 * Removed:
 

include/ble_adv.h

@@ -27,18 +27,12 @@
 extern "C" {
 #endif
 
-/**
- * @brief Advertising module BLE event observer priority.
- */
-#define BLE_ADV_BLE_OBSERVER_PRIO 0
-
 /**
  * @brief Declare an instance of a BLE advertising library.
  */
 #define BLE_ADV_DEF(instance)                                                                      \
 	static struct ble_adv instance;                                                            \
-	NRF_SDH_BLE_OBSERVER(ble_adv_##instance, ble_adv_on_ble_evt, &instance,                    \
-			     BLE_ADV_BLE_OBSERVER_PRIO)
+	NRF_SDH_BLE_OBSERVER(ble_adv_##instance, ble_adv_on_ble_evt, &instance, HIGH)
 
 /**
  * @brief Advertising modes.

include/ble_gq.h

@@ -75,7 +75,7 @@ extern "C" {
 		.data_pool = &CONCAT(_name, _heap),                                                \
 	};                                                                                         \
 	NRF_SDH_BLE_OBSERVER(CONCAT(_name, _obs), ble_gq_on_ble_evt, (void *)&_name,               \
-			     CONFIG_BLE_GQ_OBSERVER_PRIO)
+			     HIGH)
 
 /**
  * @brief Helper macro for initializing connection handle array. Used in @ref BLE_GQ_CUSTOM_DEF.

include/ble_qwr.h

@@ -41,7 +41,7 @@ extern "C" {
 	NRF_SDH_BLE_OBSERVER(_name ## _obs,                                                        \
 			     ble_qwr_on_ble_evt,                                                   \
 			     &_name,                                                               \
-			     CONFIG_BLE_QWR_BLE_OBSERVER_PRIO)
+			     HIGH)
 
 /* Error code used by the module to reject prepare write requests on non-registered attributes. */
 #define BLE_QWR_REJ_REQUEST_ERR_CODE BLE_GATT_STATUS_ATTERR_APP_BEGIN + 0

include/bluetooth/services/ble_bas.h

@@ -29,7 +29,7 @@ extern "C" {
 #define BLE_BAS_DEF(_name)                                                                         \
 	static struct ble_bas _name;                                                               \
 	extern void ble_bas_on_ble_evt(const ble_evt_t *ble_evt, void *ctx);                       \
-	NRF_SDH_BLE_OBSERVER(_name##_obs, ble_bas_on_ble_evt, &_name, 0)
+	NRF_SDH_BLE_OBSERVER(_name##_obs, ble_bas_on_ble_evt, &_name, HIGH)
 
 /**
  * @brief Battery service event types.

include/bluetooth/services/ble_cgms.h

@@ -17,14 +17,6 @@
  *          of the sensor. Session Run Time and Session Start Time can be used to convey timing
  *          information between the sensor and the collector. The Specific Ops Control Point
  *          is used to stop and start monitoring sessions, among other things.
- *
- * @note    The application must register this module as BLE event observer using the
- *          NRF_SDH_BLE_OBSERVER macro. Example:
- *          @code
- *              struct ble_cgms instance;
- *              NRF_SDH_BLE_OBSERVER(anything, BLE_CGMS_BLE_OBSERVER_PRIO,
- *                                   ble_cgms_on_ble_evt, &instance);
- *          @endcode
  */
 
 #ifndef BLE_CGMS_H__
@@ -51,7 +43,7 @@ extern "C" {
 	static struct ble_cgms _name;                                                              \
 	NRF_SDH_BLE_OBSERVER(_name ## _obs,                                                        \
 			     ble_cgms_on_ble_evt, &_name,                                          \
-			     CONFIG_BLE_CGMS_BLE_OBSERVER_PRIO)
+			     HIGH)
 
 #define OPCODE_LENGTH 1
 #define HANDLE_LENGTH 2

include/bluetooth/services/ble_hids.h

@@ -41,7 +41,7 @@ extern "C" {
 					sizeof(uint32_t) * BYTES_TO_WORDS(BLE_HIDS_LINK_CTX_SIZE), \
 			},                                                                         \
 	};                                                                                         \
-	NRF_SDH_BLE_OBSERVER(_name##_obs, ble_hids_on_ble_evt, &_name, 0)
+	NRF_SDH_BLE_OBSERVER(_name##_obs, ble_hids_on_ble_evt, &_name, HIGH)
 
 /**
  * @brief HID boot keyboard input report maximum size, in bytes.

include/bluetooth/services/ble_hrs.h

@@ -30,7 +30,7 @@ extern "C" {
 #define BLE_HRS_DEF(_name)                                                                         \
 	static struct ble_hrs _name;                                                               \
 	extern void ble_hrs_on_ble_evt(const ble_evt_t *ble_evt, void *ctx);                       \
-	NRF_SDH_BLE_OBSERVER(_name##_obs, ble_hrs_on_ble_evt, &_name, 0)
+	NRF_SDH_BLE_OBSERVER(_name##_obs, ble_hrs_on_ble_evt, &_name, HIGH)
 
 /**
  * @defgroup BLE_HRS_BODY_SENSOR_LOCATION HRS Body sensor location

include/bluetooth/services/ble_lbs.h

@@ -20,8 +20,6 @@
 extern "C" {
 #endif
 
-#define BLE_LBS_BLE_OBSERVER_PRIO 2
-
 #define BLE_UUID_LBS_BASE	{ 0x23, 0xD1, 0xBC, 0xEA, 0x5F, 0x78, 0x23, 0x15,                  \
 				  0xDE, 0xEF, 0x12, 0x12, 0x00, 0x00, 0x00, 0x00 }
 #define BLE_UUID_LBS_SERVICE	 0x1523
@@ -39,7 +37,7 @@ struct ble_lbs;
 #define BLE_LBS_DEF(_name)                                                                         \
 	static struct ble_lbs _name;                                                               \
 	extern void ble_lbs_on_ble_evt(const ble_evt_t *ble_evt, void *lbs_instance);              \
-	NRF_SDH_BLE_OBSERVER(_name ## _obs, ble_lbs_on_ble_evt, &_name, BLE_LBS_BLE_OBSERVER_PRIO)
+	NRF_SDH_BLE_OBSERVER(_name ## _obs, ble_lbs_on_ble_evt, &_name, HIGH)
 
 enum ble_lbs_evt_type {
 	BLE_LBS_EVT_LED_WRITE,

include/bluetooth/services/ble_nus.h

@@ -48,7 +48,7 @@ void ble_nus_on_ble_evt(ble_evt_t const *ble_evt, void *context);
 	NRF_SDH_BLE_OBSERVER(_name ## _obs,                                                        \
 			     ble_nus_on_ble_evt,                                                   \
 			     &_name,                                                               \
-			     0)
+			     HIGH)
 
 #define OPCODE_LENGTH 1
 #define HANDLE_LENGTH 2

include/nrf_sdh.h

@@ -15,12 +15,66 @@
 #define NRF_SDH_H__
 
 #include <stdbool.h>
+#include <zephyr/toolchain.h>
+#include <zephyr/sys/util.h>
 #include <zephyr/sys/iterable_sections.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/**
+ * @defgroup softdevice_observer_prio SoftDevice event observer priority levels
+ *
+ * A SoftDevice observer has a defined priority, which determines the order with
+ * which the observer receives relevant events compared to other observers.
+ *
+ * Five priority levels are defined, highest, high, user, user low, lowest.
+ * These can be selected using the tokens HIGHEST, HIGH, USER, USER_LOW, and LOWEST respectively.
+ *
+ * In general, an observer priority must be defined in such a way that an observer
+ * has a lower priority than that of other observers (libraries, etc.) it depends on.
+ *
+ * @{
+ */
+
+
+/* Helper macros to check for equality */
+
+#define H_NRF_SDH_OBSERVER_PRIO_HIGHEST_HIGHEST 1
+#define H_NRF_SDH_OBSERVER_PRIO_HIGH_HIGH 1
+#define H_NRF_SDH_OBSERVER_PRIO_USER_USER 1
+#define H_NRF_SDH_OBSERVER_PRIO_USER_LOW_USER_LOW 1
+#define H_NRF_SDH_OBSERVER_PRIO_LOWEST_LOWEST 1
+
+/**
+ * @brief Utility macro to check for observer priority validity.
+ * @internal
+ */
+#define PRIO_LEVEL_IS_VALID(level)                                                                 \
+	COND_CODE_1(H_NRF_SDH_OBSERVER_PRIO_HIGHEST_##level, (),                                   \
+	(COND_CODE_1(H_NRF_SDH_OBSERVER_PRIO_HIGH_##level, (),                                     \
+	(COND_CODE_1(H_NRF_SDH_OBSERVER_PRIO_USER_##level, (),                                     \
+	(COND_CODE_1(H_NRF_SDH_OBSERVER_PRIO_USER_LOW_##level, (),                                 \
+	(COND_CODE_1(H_NRF_SDH_OBSERVER_PRIO_LOWEST_##level, (),                                   \
+	(BUILD_ASSERT(0, "Invalid priority level")))))))))))
+
+/**
+ * @brief Utility macro to convert a priority token to its numerical value
+ * @internal
+ */
+#define PRIO_LEVEL_ORD(level)                                                                      \
+	COND_CODE_1(H_NRF_SDH_OBSERVER_PRIO_HIGHEST_##level, (0),                                  \
+	(COND_CODE_1(H_NRF_SDH_OBSERVER_PRIO_HIGH_##level, (1),                                    \
+	(COND_CODE_1(H_NRF_SDH_OBSERVER_PRIO_USER_##level, (2),                                    \
+	(COND_CODE_1(H_NRF_SDH_OBSERVER_PRIO_USER_LOW_##level, (3),                                \
+	(COND_CODE_1(H_NRF_SDH_OBSERVER_PRIO_LOWEST_##level, (4),                                  \
+	(BUILD_ASSERT(0, "Invalid priority level")))))))))))
+
+/**
+ * @}
+ */
+
 /**
  * @brief SoftDevice Handler state requests.
  */
@@ -73,12 +127,13 @@ struct nrf_sdh_state_req_observer {
  * @param _handler State request handler.
  * @param _ctx A context passed to the state request handler.
  * @param _prio Priority of the observer's event handler.
- *		The lower the number, the higher the priority.
+ *		Allowed input: `HIGHEST`, `HIGH`, `USER`, `USER_LOW`, `LOWEST`.
  */
 #define NRF_SDH_STATE_REQ_OBSERVER(_observer, _handler, _ctx, _prio)                               \
+	PRIO_LEVEL_IS_VALID(_prio);                                                                \
 	static bool _handler(enum nrf_sdh_state_req, void *);                                      \
 	const TYPE_SECTION_ITERABLE(struct nrf_sdh_state_req_observer, _observer,                  \
-				    nrf_sdh_state_req_observers, _prio) = {                        \
+				    nrf_sdh_state_req_observers, PRIO_LEVEL_ORD(_prio)) = {        \
 		.handler = _handler,                                                               \
 		.context = _ctx,                                                                   \
 	};
@@ -140,12 +195,13 @@ struct nrf_sdh_state_evt_observer {
  * @param _handler State request handler.
  * @param _ctx A context passed to the state request handler.
  * @param _prio Priority of the observer's event handler.
- *		The lower the number, the higher the priority.
+ *		Allowed input: `HIGHEST`, `HIGH`, `USER`, `USER_LOW`, `LOWEST`.
  */
 #define NRF_SDH_STATE_EVT_OBSERVER(_observer, _handler, _ctx, _prio)                               \
+	PRIO_LEVEL_IS_VALID(_prio);                                                                \
 	static void _handler(enum nrf_sdh_state_evt, void *);                                      \
 	const TYPE_SECTION_ITERABLE(struct nrf_sdh_state_evt_observer, _observer,                  \
-				    nrf_sdh_state_evt_observers, _prio) = {                        \
+				    nrf_sdh_state_evt_observers, PRIO_LEVEL_ORD(_prio)) = {        \
 		.handler = _handler,                                                               \
 		.context = _ctx,                                                                   \
 	};
@@ -180,12 +236,13 @@ struct nrf_sdh_stack_evt_observer {
  * @param _handler Stack event handler.
  * @param _ctx A context passed to the state request handler.
  * @param _prio Priority of the observer's event handler.
- *		The lower the number, the higher the priority.
+ *		Allowed input: `HIGHEST`, `HIGH`, `USER`, `USER_LOW`, `LOWEST`.
  */
 #define NRF_SDH_STACK_EVT_OBSERVER(_observer, _handler, _ctx, _prio)                               \
+	PRIO_LEVEL_IS_VALID(_prio);                                                                \
 	static void _handler(void *);                                                              \
 	const TYPE_SECTION_ITERABLE(struct nrf_sdh_stack_evt_observer, _observer,                  \
-				    nrf_sdh_stack_evt_observers, _prio) = {                        \
+				    nrf_sdh_stack_evt_observers, PRIO_LEVEL_ORD(_prio)) = {        \
 		.handler = _handler,                                                               \
 		.context = _ctx,                                                                   \
 	};

include/nrf_sdh_ble.h

@@ -16,6 +16,7 @@
 #define NRF_SDH_BLE_H__
 
 #include <stdint.h>
+#include <nrf_sdh.h>
 #include <ble.h>
 #include <zephyr/sys/iterable_sections.h>
 
@@ -54,11 +55,12 @@ struct nrf_sdh_ble_evt_observer {
  * @param _handler State request handler.
  * @param _ctx A context passed to the state request handler.
  * @param _prio Priority of the observer's event handler.
- *		The lower the number, the higher the priority.
+ *		Allowed input: `HIGHEST`, `HIGH`, `USER`, `USER_LOW`, `LOWEST`.
  */
 #define NRF_SDH_BLE_OBSERVER(_observer, _handler, _ctx, _prio)                                     \
+	PRIO_LEVEL_IS_VALID(_prio);                                                                \
 	static const TYPE_SECTION_ITERABLE(struct nrf_sdh_ble_evt_observer, _observer,             \
-					   nrf_sdh_ble_evt_observers, _prio) = {                   \
+					   nrf_sdh_ble_evt_observers, PRIO_LEVEL_ORD(_prio)) = {   \
 		.handler = _handler,                                                               \
 		.context = _ctx,                                                                   \
 	};

include/nrf_sdh_soc.h

@@ -16,6 +16,7 @@
 #define NRF_SDH_SOC_H__
 
 #include <stdint.h>
+#include <nrf_sdh.h>
 #include <zephyr/sys/iterable_sections.h>
 
 #ifdef __cplusplus
@@ -48,11 +49,12 @@ struct nrf_sdh_soc_evt_observer {
  * @param _handler State request handler.
  * @param _ctx A context passed to the state request handler.
  * @param _prio Priority of the observer's event handler.
- *		The lower the number, the higher the priority.
+ *		Allowed input: `HIGHEST`, `HIGH`, `USER`, `USER_LOW`, `LOWEST`.
  */
 #define NRF_SDH_SOC_OBSERVER(_observer, _handler, _ctx, _prio)                                     \
+	PRIO_LEVEL_IS_VALID(_prio);                                                                \
 	const TYPE_SECTION_ITERABLE(struct nrf_sdh_soc_evt_observer, _observer,                    \
-				    nrf_sdh_soc_evt_observers, _prio) = {                          \
+				    nrf_sdh_soc_evt_observers, PRIO_LEVEL_ORD(_prio)) = {          \
 		.handler = _handler,                                                               \
 		.context = _ctx,                                                                   \
 	};

lib/ble_conn_params/att_mtu.c

@@ -159,7 +159,7 @@ static void on_ble_evt(const ble_evt_t *evt, void *ctx)
 		mtu_exchange_request(conn_handle, idx);
 	}
 }
-NRF_SDH_BLE_OBSERVER(ble_observer, on_ble_evt, NULL, 0);
+NRF_SDH_BLE_OBSERVER(ble_observer, on_ble_evt, NULL, HIGH);
 
 int ble_conn_params_att_mtu_set(uint16_t conn_handle, uint16_t att_mtu)
 {

lib/ble_conn_params/conn_param.c

@@ -167,7 +167,7 @@ static void on_ble_evt(const ble_evt_t *evt, void *ctx)
 		break;
 	}
 }
-NRF_SDH_BLE_OBSERVER(ble_observer, on_ble_evt, NULL, 0);
+NRF_SDH_BLE_OBSERVER(ble_observer, on_ble_evt, NULL, HIGH);
 
 static void on_state_evt(enum nrf_sdh_state_evt evt, void *ctx)
 {
@@ -188,7 +188,7 @@ static void on_state_evt(enum nrf_sdh_state_evt evt, void *ctx)
 		ppcp.slave_latency,
 		ppcp.conn_sup_timeout);
 }
-NRF_SDH_STATE_EVT_OBSERVER(ble_conn_params_sdh_state_observer, on_state_evt, NULL, 0);
+NRF_SDH_STATE_EVT_OBSERVER(ble_conn_params_sdh_state_observer, on_state_evt, NULL, HIGH);
 
 int ble_conn_params_override(uint16_t conn_handle, const ble_gap_conn_params_t *conn_params)
 {

lib/ble_conn_params/data_length.c

@@ -185,7 +185,7 @@ static void on_ble_evt(const ble_evt_t *evt, void *ctx)
 		data_length_update(conn_handle, idx);
 	}
 }
-NRF_SDH_BLE_OBSERVER(ble_observer, on_ble_evt, NULL, 0);
+NRF_SDH_BLE_OBSERVER(ble_observer, on_ble_evt, NULL, HIGH);
 
 int ble_conn_params_data_length_set(uint16_t conn_handle, struct ble_conn_params_data_length dl)
 {

lib/ble_conn_params/phy_mode.c

@@ -156,7 +156,7 @@ static void on_ble_evt(const ble_evt_t *evt, void *ctx)
 		radio_phy_mode_update(conn_handle, idx);
 	}
 }
-NRF_SDH_BLE_OBSERVER(ble_observer, on_ble_evt, NULL, 0);
+NRF_SDH_BLE_OBSERVER(ble_observer, on_ble_evt, NULL, HIGH);
 
 int ble_conn_params_phy_radio_mode_set(uint16_t conn_handle, ble_gap_phys_t phy_pref)
 {

lib/ble_conn_state/Kconfig

@@ -18,10 +18,6 @@ config BLE_CONN_STATE_USER_FLAG_COUNT
 	help
 	   The number of available user flags.
 
-config BLE_CONN_STATE_BLE_OBSERVER_PRIO
-	int "BLE observer priority"
-	default 0
-
 module=BLE_CONN_STATE
 module-str=BLE Connection state
 source "${ZEPHYR_BASE}/subsys/logging/Kconfig.template.log_config"

lib/ble_conn_state/ble_conn_state.c

@@ -423,4 +423,4 @@ static void ble_evt_handler(ble_evt_t const *ble_evt, void *ctx)
 }
 
 NRF_SDH_BLE_OBSERVER(ble_evt_observer, ble_evt_handler, NULL,
-		     CONFIG_BLE_CONN_STATE_BLE_OBSERVER_PRIO);
+		     HIGHEST);

lib/ble_gq/Kconfig

@@ -30,10 +30,6 @@ config BLE_GQ_HEAP_SIZE
 	  Default value used for GATT queue instances defined using BLE_GQ_DEF. Sets the heap size
 	  for storing additional data that can be of variable size.
 
-config BLE_GQ_OBSERVER_PRIO
-	int "SoftDevice event observer priority"
-	default 0
-
 module=BLE_GQ
 module-str=BLE GATT Queue
 source "$(ZEPHYR_BASE)/subsys/logging/Kconfig.template.log_config"

lib/ble_qwr/Kconfig

@@ -14,10 +14,6 @@ config BLE_QWR_MAX_ATTR
 	help
 	   Maximum queued writes attributes
 
-config BLE_QWR_BLE_OBSERVER_PRIO
-	int "BLE observer priority"
-	default 2
-
 module=BLE_QWR
 module-str=BLE QWR
 source "$(ZEPHYR_BASE)/subsys/logging/Kconfig.template.log_config"

lib/bm_storage/sd/bm_storage_sd.c

@@ -70,9 +70,9 @@ static void on_state_evt_change(enum nrf_sdh_state_evt evt, void *ctx);
 RING_BUF_DECLARE(sd_fifo, CONFIG_BM_STORAGE_BACKEND_SD_QUEUE_SIZE *
 		 sizeof(struct bm_storage_sd_op));
 
-NRF_SDH_SOC_OBSERVER(sdh_soc, on_soc_evt, NULL, 0);
-NRF_SDH_STATE_REQ_OBSERVER(sdh_state_req, on_state_req_change, NULL, 0);
-NRF_SDH_STATE_EVT_OBSERVER(sdh_state_evt, on_state_evt_change, NULL, 0);
+NRF_SDH_SOC_OBSERVER(sdh_soc, on_soc_evt, NULL, HIGH);
+NRF_SDH_STATE_REQ_OBSERVER(sdh_state_req, on_state_req_change, NULL, HIGH);
+NRF_SDH_STATE_EVT_OBSERVER(sdh_state_evt, on_state_evt_change, NULL, HIGH);
 
 static inline bool is_aligned32(uint32_t addr)
 {

lib/peer_manager/Kconfig

@@ -21,12 +21,6 @@ config PM_BM_ZMS_SECTOR_SIZE
 	int "Sector size"
 	default 1024
 
-config PM_BLE_OBSERVER_PRIO
-	int "Priority with which BLE events are dispatched to the Peer Manager module."
-	default 1
-	help
-	  Priority with which BLE events are dispatched to the Peer Manager module.
-
 config PM_MAX_REGISTRANTS
 	int "Number of event handlers that can be registered."
 	default 3