API Change: IPM - callback improvement

doc/releases/release-notes-2.4.rst

@@ -59,6 +59,12 @@ API Changes
   'callback_arg' argument has been renamed to 'user_data. All user code have
   been modified accordingly.
 
+* ``<drivers/ipm.h>`` has seen its callback normalized.
+  :c:type:`ipm_callback_t` had its signature changed to add a struct device
+  pointer as first parameter. :c:func:`ipm_register_callback` user code have
+  been modified accordingly. The context argument has been renamed to user_data
+  and all drivers have been modified against it as well.
+
 Deprecated in this release
 ==========================
 

drivers/bluetooth/hci/rpmsg_nrf53.c

@@ -115,7 +115,8 @@ const struct virtio_dispatch dispatch = {
 	.notify = virtio_notify,
 };
 
-static void ipm_callback(void *context, uint32_t id, volatile void *data)
+static void ipm_callback(struct device *dev, void *context,
+			 uint32_t id, volatile void *data)
 {
 	BT_DBG("Got callback of id %u", id);
 	k_sem_give(&rx_sem);

drivers/console/ipm_console_receiver.c

@@ -84,8 +84,8 @@ static void ipm_console_thread(void *arg1, void *arg2, void *arg3)
 	}
 }
 
-static void ipm_console_receive_callback(void *context, uint32_t id,
-					 volatile void *data)
+static void ipm_console_receive_callback(struct device *ipm_dev, void *context,
+					 uint32_t id, volatile void *data)
 {
 	struct device *d;
 	struct ipm_console_receiver_runtime_data *driver_data;
@@ -109,7 +109,7 @@ static void ipm_console_receive_callback(void *context, uint32_t id,
 	 * re-enables the channel and consumes the data.
 	 */
 	if (ring_buf_space_get(&driver_data->rb) == 0) {
-		ipm_set_enabled(driver_data->ipm_device, 0);
+		ipm_set_enabled(ipm_dev, 0);
 		driver_data->channel_disabled = 1;
 	}
 }

drivers/ipm/ipm_cavs_idc.c

@@ -23,7 +23,7 @@ extern void z_sched_ipi(void);
 
 struct cavs_idc_data {
 	ipm_callback_t	cb;
-	void		*ctx;
+	void		*user_data;
 };
 
 DEVICE_DECLARE(cavs_idc);
@@ -68,7 +68,7 @@ static void cavs_idc_isr(struct device *dev)
 				ext = UINT_TO_POINTER(
 					idc_read(REG_IDCTEFC(i), curr_cpu_id) &
 					REG_IDCTEFC_MSG_MASK);
-				drv_data->cb(drv_data->ctx, id, ext);
+				drv_data->cb(dev, drv_data->user_data, id, ext);
 			}
 			break;
 		}
@@ -157,12 +157,12 @@ static uint32_t cavs_idc_max_id_val_get(struct device *dev)
 }
 
 static void cavs_idc_register_callback(struct device *dev, ipm_callback_t cb,
-				       void *context)
+				       void *user_data)
 {
 	struct cavs_idc_data *drv_data = dev->driver_data;
 
 	drv_data->cb = cb;
-	drv_data->ctx = context;
+	drv_data->user_data = user_data;
 }
 
 static int cavs_idc_set_enabled(struct device *dev, int enable)

drivers/ipm/ipm_imx.c

@@ -28,7 +28,7 @@ struct imx_mu_config {
 
 struct imx_mu_data {
 	ipm_callback_t callback;
-	void *callback_ctx;
+	void *user_data;
 };
 
 static void imx_mu_isr(void *arg)
@@ -69,7 +69,7 @@ static void imx_mu_isr(void *arg)
 				}
 
 				if (data->callback) {
-					data->callback(data->callback_ctx,
+					data->callback(dev, data->user_data,
 						       (uint32_t)id,
 						       &data32[0]);
 				}
@@ -140,12 +140,12 @@ static uint32_t imx_mu_ipm_max_id_val_get(struct device *dev)
 
 static void imx_mu_ipm_register_callback(struct device *dev,
 					 ipm_callback_t cb,
-					 void *context)
+					 void *user_data)
 {
 	struct imx_mu_data *driver_data = dev->driver_data;
 
 	driver_data->callback = cb;
-	driver_data->callback_ctx = context;
+	driver_data->user_data = user_data;
 }
 
 static int imx_mu_ipm_set_enabled(struct device *dev, int enable)

drivers/ipm/ipm_mcux.c

@@ -52,7 +52,7 @@ static void mcux_mailbox_isr(void *arg)
 
 	if (data->callback) {
 		/* Only one MAILBOX, id is unused and set to 0 */
-		data->callback(data->callback_ctx, 0, &value);
+		data->callback(dev, data->callback_ctx, 0, &value);
 	}
 	/* Add for ARM errata 838869, affects Cortex-M4, Cortex-M4F
 	 * Store immediate overlapping exception return operation

drivers/ipm/ipm_mhu.c

@@ -137,8 +137,8 @@ static void ipm_mhu_isr(void *arg)
 	ipm_mhu_clear_val(d, cpu_id, ipm_mhu_status);
 
 	if (driver_data->callback) {
-		driver_data->callback(driver_data->callback_ctx, cpu_id,
-					&ipm_mhu_status);
+		driver_data->callback(d, driver_data->user_data, cpu_id,
+				      &ipm_mhu_status);
 	}
 }
 
@@ -157,13 +157,13 @@ static int ipm_mhu_max_data_size_get(struct device *d)
 }
 
 static void ipm_mhu_register_cb(struct device *d,
-						ipm_callback_t cb,
-						void *context)
+				ipm_callback_t cb,
+				void *user_data)
 {
 	struct ipm_mhu_data *driver_data = DEV_DATA(d);
 
 	driver_data->callback = cb;
-	driver_data->callback_ctx = context;
+	driver_data->user_data = user_data;
 }
 
 static const struct ipm_driver_api ipm_mhu_driver_api = {
@@ -183,7 +183,7 @@ static const struct ipm_mhu_device_config ipm_mhu_cfg_0 = {
 
 static struct ipm_mhu_data ipm_mhu_data_0 = {
 	.callback = NULL,
-	.callback_ctx = NULL,
+	.user_data = NULL,
 };
 
 DEVICE_AND_API_INIT(mhu_0,
@@ -214,7 +214,7 @@ static const struct ipm_mhu_device_config ipm_mhu_cfg_1 = {
 
 static struct ipm_mhu_data ipm_mhu_data_1 = {
 	.callback = NULL,
-	.callback_ctx = NULL,
+	.user_data = NULL,
 };
 
 DEVICE_AND_API_INIT(mhu_1,

drivers/ipm/ipm_mhu.h

@@ -65,7 +65,7 @@ struct ipm_mhu_device_config {
 /* Device data structure */
 struct ipm_mhu_data {
 	ipm_callback_t callback;
-	void *callback_ctx;
+	void *user_data;
 };
 
 #ifdef __cplusplus

drivers/ipm/ipm_nrfx_ipc.c

@@ -17,7 +17,7 @@ LOG_MODULE_REGISTER(ipm_nrfx_ipc);
 
 struct ipm_nrf_data {
 	ipm_callback_t callback;
-	void *callback_ctx;
+	void *user_data;
 };
 
 static struct ipm_nrf_data nrfx_ipm_data;
@@ -27,6 +27,8 @@ static void gipm_send(uint32_t id);
 
 #if IS_ENABLED(CONFIG_IPM_NRF_SINGLE_INSTANCE)
 
+DEVICE_DECLARE(ipm_nrf);
+
 static void nrfx_ipc_handler(uint32_t event_mask, void *p_context)
 {
 	if (nrfx_ipm_data.callback) {
@@ -36,7 +38,8 @@ static void nrfx_ipc_handler(uint32_t event_mask, void *p_context)
 			__ASSERT(event_idx < NRFX_IPC_ID_MAX_VALUE,
 				 "Illegal event_idx: %d", event_idx);
 			event_mask &= ~BIT(event_idx);
-			nrfx_ipm_data.callback(nrfx_ipm_data.callback_ctx,
+			nrfx_ipm_data.callback(DEVICE_GET(ipm_nrf),
+					       nrfx_ipm_data.user_data,
 					       event_idx,
 					       NULL);
 		}
@@ -74,10 +77,10 @@ static uint32_t ipm_nrf_max_id_val_get(struct device *dev)
 
 static void ipm_nrf_register_callback(struct device *dev,
 				      ipm_callback_t cb,
-				      void *context)
+				      void *user_data)
 {
 	nrfx_ipm_data.callback = cb;
-	nrfx_ipm_data.callback_ctx = context;
+	nrfx_ipm_data.user_data = user_data;
 }
 
 static int ipm_nrf_set_enabled(struct device *dev, int enable)
@@ -116,9 +119,9 @@ DEVICE_AND_API_INIT(ipm_nrf, DT_INST_LABEL(0),
 
 struct vipm_nrf_data {
 	ipm_callback_t callback[NRFX_IPC_ID_MAX_VALUE];
-	void *callback_ctx[NRFX_IPC_ID_MAX_VALUE];
+	void *user_data[NRFX_IPC_ID_MAX_VALUE];
+	struct device *ipm_device[NRFX_IPC_ID_MAX_VALUE];
 	bool ipm_init;
-	struct device *ipm_device;
 };
 
 static struct vipm_nrf_data nrfx_vipm_data;
@@ -133,7 +136,8 @@ static void vipm_dispatcher(uint32_t event_mask, void *p_context)
 		event_mask &= ~BIT(event_idx);
 		if (nrfx_vipm_data.callback[event_idx] != NULL) {
 			nrfx_vipm_data.callback[event_idx]
-				(nrfx_vipm_data.callback_ctx[event_idx],
+				(nrfx_vipm_data.ipm_device[event_idx],
+				 nrfx_vipm_data.user_data[event_idx],
 				 0,
 				 NULL);
 		}
@@ -190,11 +194,12 @@ static int vipm_nrf_##_idx##_send(struct device *dev, int wait,		\
 									\
 static void vipm_nrf_##_idx##_register_callback(struct device *dev,	\
 						ipm_callback_t cb,	\
-						void *context)		\
+						void *user_data)	\
 {									\
 	if (IS_ENABLED(CONFIG_IPM_MSG_CH_##_idx##_RX)) {		\
 		nrfx_vipm_data.callback[_idx] = cb;			\
-		nrfx_vipm_data.callback_ctx[_idx] = context;		\
+		nrfx_vipm_data.user_data[_idx] = user_data;		\
+		nrfx_vipm_data.ipm_device[_idx] = dev;			\
 	} else {							\
 		LOG_WRN("Trying to register a callback"			\
 			"for TX channel IPM_" #_idx);			\

drivers/ipm/ipm_stm32_ipcc.c

@@ -96,7 +96,7 @@ struct stm32_ipcc_mailbox_config {
 struct stm32_ipcc_mbx_data {
 	uint32_t num_ch;
 	ipm_callback_t callback;
-	void *callback_ctx;
+	void *user_data;
 };
 
 static struct stm32_ipcc_mbx_data stm32_IPCC_data;
@@ -122,7 +122,7 @@ static void stm32_ipcc_mailbox_rx_isr(void *arg)
 
 		if (data->callback) {
 			/* Only one MAILBOX, id is unused and set to 0 */
-			data->callback(data->callback_ctx, i, &value);
+			data->callback(dev, data->user_data, i, &value);
 		}
 		/* clear status to acknoledge message reception */
 		IPCC_ClearFlag_CHx(cfg->ipcc, i);
@@ -203,12 +203,12 @@ static uint32_t stm32_ipcc_mailbox_ipm_max_id_val_get(struct device *d)
 
 static void stm32_ipcc_mailbox_ipm_register_callback(struct device *d,
 						     ipm_callback_t cb,
-						     void *context)
+						     void *user_data)
 {
 	struct stm32_ipcc_mbx_data *data = DEV_DATA(d);
 
 	data->callback = cb;
-	data->callback_ctx = context;
+	data->user_data = user_data;
 }
 
 static int stm32_ipcc_mailbox_ipm_set_enabled(struct device *dev, int enable)

include/drivers/ipm.h

@@ -35,14 +35,15 @@ extern "C" {
  * interrupt-safe APIS. Registration of callbacks is done via
  * @a ipm_register_callback
  *
- * @param "void *context" Arbitrary context pointer provided at
- *        registration time.
- * @param "uint32_t id" Message type identifier.
- * @param "volatile void *data" Message data pointer. The correct
- *        amount of data to read out
- * must be inferred using the message id/upper level protocol.
+ * @param ipmdev Driver instance
+ * @param user_data Pointer to some private data provided at registration
+ *        time.
+ * @param id Message type identifier.
+ * @param data Message data pointer. The correct amount of data to read out
+ *        must be inferred using the message id/upper level protocol.
  */
-typedef void (*ipm_callback_t)(void *context, uint32_t id, volatile void *data);
+typedef void (*ipm_callback_t)(struct device *ipmdev, void *user_data,
+			       uint32_t id, volatile void *data);
 
 /**
  * @typedef ipm_send_t
@@ -75,7 +76,7 @@ typedef uint32_t (*ipm_max_id_val_get_t)(struct device *ipmdev);
  * See @a ipm_register_callback() for argument definitions.
  */
 typedef void (*ipm_register_callback_t)(struct device *port, ipm_callback_t cb,
-					void *cb_context);
+					void *user_data);
 
 /**
  * @typedef ipm_set_enabled_t
@@ -145,16 +146,16 @@ static inline int z_impl_ipm_send(struct device *ipmdev, int wait, uint32_t id,
  *
  * @param ipmdev Driver instance pointer.
  * @param cb Callback function to execute on incoming message interrupts.
- * @param context Application-specific context pointer which will be passed
+ * @param user_data Application-specific data pointer which will be passed
  *        to the callback function when executed.
  */
 static inline void ipm_register_callback(struct device *ipmdev,
-					 ipm_callback_t cb, void *context)
+					 ipm_callback_t cb, void *user_data)
 {
 	const struct ipm_driver_api *api =
 		(const struct ipm_driver_api *)ipmdev->driver_api;
 
-	api->register_callback(ipmdev, cb, context);
+	api->register_callback(ipmdev, cb, user_data);
 }
 
 /**

samples/bluetooth/hci_rpmsg/src/main.c

@@ -123,7 +123,8 @@ static void ipm_callback_process(struct k_work *work)
 	virtqueue_notification(vq[1]);
 }
 
-static void ipm_callback(void *context, uint32_t id, volatile void *data)
+static void ipm_callback(struct device *dev, void *context,
+			 uint32_t id, volatile void *data)
 {
 	LOG_INF("Got callback of id %u", id);
 	k_work_submit(&ipm_work);

samples/subsys/ipc/ipm_imx/src/main.c

@@ -9,9 +9,8 @@
 #include <device.h>
 #include <drivers/ipm.h>
 
-static struct device *ipm;
-
-static void ipm_callback(void *context, uint32_t id, volatile void *data)
+static void ipm_callback(struct device *dev, void *context,
+			 uint32_t id, volatile void *data)
 {
 	int i;
 	int status;
@@ -23,7 +22,7 @@ static void ipm_callback(void *context, uint32_t id, volatile void *data)
 	}
 	printk("\n");
 
-	status = ipm_send(ipm, 1, id, (const void *)data,
+	status = ipm_send(dev, 1, id, (const void *)data,
 			  CONFIG_IPM_IMX_MAX_DATA_SIZE);
 	if (status) {
 		printk("ipm_send() failed: %d\n", status);
@@ -32,6 +31,8 @@ static void ipm_callback(void *context, uint32_t id, volatile void *data)
 
 void main(void)
 {
+	struct device *ipm;
+
 	ipm = device_get_binding("MU_B");
 	if (!ipm) {
 		while (1) {

samples/subsys/ipc/ipm_mcux/remote/src/main_remote.c

@@ -9,17 +9,18 @@
 #include <device.h>
 #include <drivers/ipm.h>
 
-struct device *ipm;
-
-void ping_ipm_callback(void *context, uint32_t id, volatile void *data)
+void ping_ipm_callback(struct device *dev, void *context,
+		       uint32_t id, volatile void *data)
 {
-	ipm_send(ipm, 1, 0, (const void *)data, 4);
+	ipm_send(dev, 1, 0, (const void *)data, 4);
 }
 
 
 
 void main(void)
 {
+	struct device *ipm;
+
 	ipm = device_get_binding(DT_LABEL(DT_INST(0, nxp_lpc_mailbox)));
 	if (!ipm) {
 		while (1) {