1 /*
2  * Copyright (c) 2021 Carlo Caione <ccaione@baylibre.com>
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 #ifndef ZEPHYR_INCLUDE_IPC_SERVICE_IPC_RPMSG_H_
8 #define ZEPHYR_INCLUDE_IPC_SERVICE_IPC_RPMSG_H_
9 
10 #include <zephyr/ipc/ipc_service.h>
11 #include <openamp/open_amp.h>
12 #include <metal/device.h>
13 
14 #ifdef __cplusplus
15 extern "C" {
16 #endif
17 
18 /**
19  * @brief IPC service RPMsg API
20  * @defgroup ipc_service_rpmsg_api IPC service RPMsg API
21  * @ingroup ipc
22  * @{
23  */
24 
25 /** Number of endpoints. */
26 #define NUM_ENDPOINTS	CONFIG_IPC_SERVICE_BACKEND_RPMSG_NUM_ENDPOINTS_PER_INSTANCE
27 
28 struct ipc_rpmsg_ept;
29 
30 /**
31  * @typedef rpmsg_ept_bound_cb
32  * @brief Define the bound callback.
33  *
34  * This callback is defined at instance level and it is called when an endpoint
35  * of the instance is bound.
36  *
37  * @param ept Endpoint of the instance just bound.
38  */
39 typedef void (*rpmsg_ept_bound_cb)(struct ipc_rpmsg_ept *ept);
40 
41 /** @brief Endpoint structure.
42  *
43  *  Used to define an endpoint to be encapsulated in an RPMsg instance.
44  */
45 struct ipc_rpmsg_ept {
46 	/** RPMsg endpoint. */
47 	struct rpmsg_endpoint ep;
48 
49 	/** Name of the endpoint. */
50 	char name[RPMSG_NAME_SIZE];
51 
52 	/** Destination endpoint. */
53 	uint32_t dest;
54 
55 	/** Bound flag. */
56 	volatile bool bound;
57 
58 	/** Callbacks. */
59 	const struct ipc_service_cb *cb;
60 
61 	/** Private data to be passed to the endpoint callbacks. */
62 	void *priv;
63 };
64 
65 /** @brief RPMsg instance structure.
66  *
67  *  Struct representation of an RPMsg instance.
68  */
69 struct ipc_rpmsg_instance {
70 	/** Endpoints in the instance. */
71 	struct ipc_rpmsg_ept endpoint[NUM_ENDPOINTS];
72 
73 	/** RPMsg virtIO device. */
74 	struct rpmsg_virtio_device rvdev;
75 
76 	/** SHM pool. */
77 	struct rpmsg_virtio_shm_pool shm_pool;
78 
79 	/** EPT (instance) bound callback. */
80 	rpmsg_ept_bound_cb bound_cb;
81 
82 	/** EPT (instance) callback. */
83 	rpmsg_ept_cb cb;
84 
85 	/** Mutex for the instance. */
86 	struct k_mutex mtx;
87 };
88 
89 /** @brief Init an RPMsg instance.
90  *
91  *  Init an RPMsg instance.
92  *
93  *  @param instance Pointer to the RPMsg instance struct.
94  *  @param role Host / Remote role.
95  *  @param buffer_size Size of the buffer used to send data between host and remote.
96  *  @param shm_io SHM IO region pointer.
97  *  @param vdev VirtIO device pointer.
98  *  @param shb Shared memory region pointer.
99  *  @param size Size of the shared memory region.
100  *  @param ns_bind_cb callback handler for name service announcement without
101  *		      local endpoints waiting to bind. If NULL the
102  *		      implementation falls back to the internal implementation.
103  *
104  *  @retval -EINVAL When some parameter is missing.
105  *  @retval 0 If successful.
106  *  @retval Other errno codes depending on the OpenAMP implementation.
107  */
108 int ipc_rpmsg_init(struct ipc_rpmsg_instance *instance,
109 		   unsigned int role,
110 		   unsigned int buffer_size,
111 		   struct metal_io_region *shm_io,
112 		   struct virtio_device *vdev,
113 		   void *shb, size_t size,
114 		   rpmsg_ns_bind_cb ns_bind_cb);
115 
116 
117 /** @brief
118  *
119  * Deinit an RPMsg instance
120  *
121  * @param instance Pointer to the RPMsg instance struct.
122  * @param role Host / Remote role.
123  *
124  * @retval -EINVAL When some parameter is missing
125  * @retval 0 If successful
126  */
127 int ipc_rpmsg_deinit(struct ipc_rpmsg_instance *instance,
128 		   unsigned int role);
129 
130 /** @brief Register an endpoint.
131  *
132  *  Register an endpoint to a provided RPMsg instance.
133  *
134  *  @param instance Pointer to the RPMsg instance struct.
135  *  @param role Host / Remote role.
136  *  @param ept Endpoint to register.
137  *
138  *  @retval -EINVAL When some parameter is missing.
139  *  @retval 0 If successful.
140  *  @retval Other errno codes depending on the OpenAMP implementation.
141  */
142 int ipc_rpmsg_register_ept(struct ipc_rpmsg_instance *instance, unsigned int role,
143 			   struct ipc_rpmsg_ept *ept);
144 
145 /**
146  * @}
147  */
148 
149 #ifdef __cplusplus
150 }
151 #endif
152 
153 #endif /* ZEPHYR_INCLUDE_IPC_SERVICE_IPC_RPMSG_H_ */
154