ipc_service: Add ipc_service_close_instance function

This function allows the application to close an ipc_service instance.
It is intended for use when the remote agent it is communicating with
has gone down and allows for cleanup.
It first checks that the endpoints have been separately deregistered
with the instance using the deregister_endpoint function before
calling into previously added functions in ipc_static_vrings.c
and ipc_rpmsg.c to close those instances.

Signed-off-by: Jackson Cooper-Driver <[email protected]>

Author: jacksonc-xlnx

include/zephyr/ipc/ipc_service.h

@@ -203,6 +203,24 @@ struct ipc_ept_cfg {
  */
 int ipc_service_open_instance(const struct device *instance);
 
+/** @brief Close an instance
+ *
+ *  Function to be used to close an instance. All endpoints must be
+ *  deregistered using ipc_service_deregister_endpoint before this
+ *  is called.
+ *
+ *  @param[in] instance Instance to close.
+ *
+ *  @retval -EINVAL when instance configuration is invalid.
+ *  @retval -EIO when no backend is registered.
+ *  @retval -EALREADY when the instance is not already opened.
+ *  @retval -EBUSY when an endpoint exists that hasn't been
+ *           deregistered
+ *
+ *  @retval 0 on success or when not implemented on the backend (not needed).
+ *  @retval other errno codes depending on the implementation of the backend.
+ */
+int ipc_service_close_instance(const struct device *instance);
 
 /** @brief Register IPC endpoint onto an instance.
  *

include/zephyr/ipc/ipc_service_backend.h

@@ -37,6 +37,18 @@ struct ipc_service_backend {
 	 */
 	int (*open_instance)(const struct device *instance);
 
+	/** @brief Pointer to the function that will be used to close an instance
+	 *
+	 *  @param[in] instance Instance pointer.
+	 *
+	 *  @retval -EALREADY when the instance is not already inited.
+	 *
+	 *  @retval 0 on success
+	 *  @retval other errno codes depending on the implementation of the
+	 *	    backend.
+	 */
+	int (*close_instance)(const struct device *instance);
+
 	/** @brief Pointer to the function that will be used to send data to the endpoint.
 	 *
 	 *  @param[in] instance Instance pointer.

subsys/ipc/ipc_service/backends/ipc_rpmsg_static_vrings.c

@@ -88,6 +88,21 @@ static struct ipc_rpmsg_ept *get_available_ept_slot(struct ipc_rpmsg_instance *r
 	return get_ept_slot_with_name(rpmsg_inst, "");
 }
 
+static bool check_endpoints_freed(struct ipc_rpmsg_instance *rpmsg_inst)
+{
+	struct ipc_rpmsg_ept *rpmsg_ept;
+
+	for (size_t i = 0; i < NUM_ENDPOINTS; i++) {
+		rpmsg_ept = &rpmsg_inst->endpoint[i];
+
+		if (strcmp("", rpmsg_ept->name) != 0) {
+			return false;
+		}
+	}
+
+	return true;
+}
+
 /*
  * Returns:
  *  - true:  when the endpoint was already cached / registered
@@ -299,6 +314,26 @@ static int mbox_init(const struct device *instance)
 	return mbox_set_enabled(&conf->mbox_rx, 1);
 }
 
+static int mbox_deinit(const struct device *instance)
+{
+	const struct backend_config_t *conf = instance->config;
+	struct backend_data_t *data = instance->data;
+	k_tid_t wq_thread;
+	int err;
+
+	err = mbox_set_enabled(&conf->mbox_rx, 0);
+	if (err != 0) {
+		return err;
+	}
+
+	k_work_queue_drain(&data->mbox_wq, 1);
+
+	wq_thread = k_work_queue_thread_get(&data->mbox_wq);
+	k_thread_abort(wq_thread);
+
+	return 0;
+}
+
 static struct ipc_rpmsg_ept *register_ept_on_host(struct ipc_rpmsg_instance *rpmsg_inst,
 						  const struct ipc_ept_cfg *cfg)
 {
@@ -539,6 +574,50 @@ static int open(const struct device *instance)
 
 }
 
+static int close(const struct device *instance)
+{
+	const struct backend_config_t *conf = instance->config;
+	struct backend_data_t *data = instance->data;
+	struct ipc_rpmsg_instance *rpmsg_inst;
+	int err;
+
+	if (!atomic_cas(&data->state, STATE_INITED, STATE_BUSY)) {
+		return -EALREADY;
+	}
+
+	rpmsg_inst = &data->rpmsg_inst;
+
+	if (!check_endpoints_freed(rpmsg_inst)) {
+		return -EBUSY;
+	}
+
+	err = ipc_rpmsg_deinit(rpmsg_inst, data->role);
+	if (err != 0) {
+		goto error;
+	}
+
+	err = mbox_deinit(instance);
+	if (err != 0) {
+		goto error;
+	}
+
+	err = ipc_static_vrings_deinit(&data->vr, conf->role);
+	if (err != 0) {
+		goto error;
+	}
+
+	memset(&data->vr, 0, sizeof(struct ipc_static_vrings));
+	memset(rpmsg_inst, 0, sizeof(struct ipc_rpmsg_instance));
+
+	atomic_set(&data->state, STATE_READY);
+	return 0;
+
+error:
+	/* Back to the inited state */
+	atomic_set(&data->state, STATE_INITED);
+	return err;
+}
+
 static int get_tx_buffer_size(const struct device *instance, void *token)
 {
 	struct backend_data_t *data = instance->data;
@@ -638,6 +717,7 @@ static int drop_tx_buffer(const struct device *instance, void *token,
 
 const static struct ipc_service_backend backend_ops = {
 	.open_instance = open,
+	.close_instance = close,
 	.register_endpoint = register_ept,
 	.deregister_endpoint = deregister_ept,
 	.send = send,

subsys/ipc/ipc_service/ipc_service.c

@@ -38,6 +38,30 @@ int ipc_service_open_instance(const struct device *instance)
 	return backend->open_instance(instance);
 }
 
+int ipc_service_close_instance(const struct device *instance)
+{
+	const struct ipc_service_backend *backend;
+
+	if (!instance) {
+		LOG_ERR("Invalid instance");
+		return -EINVAL;
+	}
+
+	backend = (const struct ipc_service_backend *) instance->api;
+
+	if (!backend) {
+		LOG_ERR("Invalid backend configuration");
+		return -EIO;
+	}
+
+	if (!backend->close_instance) {
+		/* maybe not needed on backend */
+		return 0;
+	}
+
+	return backend->close_instance(instance);
+}
+
 int ipc_service_register_endpoint(const struct device *instance,
 				  struct ipc_ept *ept,
 				  const struct ipc_ept_cfg *cfg)