1 /* SPDX-License-Identifier: BSD-3-Clause */
2 /*
3 * Remote processor messaging
4 *
5 * Copyright (c) 2020 The Linux Foundation.
6 * Copyright (C) 2011 Texas Instruments, Inc.
7 * Copyright (C) 2011 Google, Inc.
8 * All rights reserved.
9 */
10
11 #ifndef _LINUX_RPMSG_H
12 #define _LINUX_RPMSG_H
13
14 #include <linux/types.h>
15 #include <linux/device.h>
16 #include <linux/err.h>
17 #include <linux/mod_devicetable.h>
18 #include <linux/kref.h>
19 #include <linux/mutex.h>
20 #include <linux/poll.h>
21
22 #define RPMSG_ADDR_ANY 0xFFFFFFFF
23
24 struct rpmsg_device;
25 struct rpmsg_endpoint;
26 struct rpmsg_device_ops;
27 struct rpmsg_endpoint_ops;
28
29 /**
30 * struct rpmsg_channel_info - channel info representation
31 * @name: name of service
32 * @src: local address
33 * @dst: destination address
34 */
35 struct rpmsg_channel_info {
36 char name[RPMSG_NAME_SIZE];
37 u32 src;
38 u32 dst;
39 };
40
41 /**
42 * rpmsg_device - device that belong to the rpmsg bus
43 * @dev: the device struct
44 * @id: device id (used to match between rpmsg drivers and devices)
45 * @driver_override: driver name to force a match; do not set directly,
46 * because core frees it; use driver_set_override() to
47 * set or clear it.
48 * @src: local address
49 * @dst: destination address
50 * @ept: the rpmsg endpoint of this channel
51 * @announce: if set, rpmsg will announce the creation/removal of this channel
52 */
53 struct rpmsg_device {
54 struct device dev;
55 struct rpmsg_device_id id;
56 char *driver_override;
57 u32 src;
58 u32 dst;
59 struct rpmsg_endpoint *ept;
60 bool announce;
61
62 const struct rpmsg_device_ops *ops;
63 };
64
65 typedef int (*rpmsg_rx_cb_t)(struct rpmsg_device *, void *, int, void *, u32);
66 typedef int (*rpmsg_rx_sig_t)(struct rpmsg_device *, void *, u32, u32);
67
68 /**
69 * struct rpmsg_endpoint - binds a local rpmsg address to its user
70 * @rpdev: rpmsg channel device
71 * @refcount: when this drops to zero, the ept is deallocated
72 * @cb: rx callback handler
73 * @cb_lock: must be taken before accessing/changing @cb
74 * @sig_cb: rx serial signal handler
75 * @addr: local rpmsg address
76 * @priv: private data for the driver's use
77 *
78 * In essence, an rpmsg endpoint represents a listener on the rpmsg bus, as
79 * it binds an rpmsg address with an rx callback handler.
80 *
81 * Simple rpmsg drivers shouldn't use this struct directly, because
82 * things just work: every rpmsg driver provides an rx callback upon
83 * registering to the bus, and that callback is then bound to its rpmsg
84 * address when the driver is probed. When relevant inbound messages arrive
85 * (i.e. messages which their dst address equals to the src address of
86 * the rpmsg channel), the driver's handler is invoked to process it.
87 *
88 * More complicated drivers though, that do need to allocate additional rpmsg
89 * addresses, and bind them to different rx callbacks, must explicitly
90 * create additional endpoints by themselves (see rpmsg_create_ept()).
91 */
92 struct rpmsg_endpoint {
93 struct rpmsg_device *rpdev;
94 struct kref refcount;
95 rpmsg_rx_cb_t cb;
96 struct mutex cb_lock;
97 rpmsg_rx_sig_t sig_cb;
98 u32 addr;
99 void *priv;
100
101 const struct rpmsg_endpoint_ops *ops;
102 };
103
104 /**
105 * struct rpmsg_driver - rpmsg driver struct
106 * @drv: underlying device driver
107 * @id_table: rpmsg ids serviced by this driver
108 * @probe: invoked when a matching rpmsg channel (i.e. device) is found
109 * @remove: invoked when the rpmsg channel is removed
110 * @callback: invoked when an inbound message is received on the channel
111 * @signals: invoked when a serial signal change is received on the channel
112 */
113 struct rpmsg_driver {
114 struct device_driver drv;
115 const struct rpmsg_device_id *id_table;
116 int (*probe)(struct rpmsg_device *dev);
117 void (*remove)(struct rpmsg_device *dev);
118 int (*callback)(struct rpmsg_device *, void *, int, void *, u32);
119 int (*signals)(struct rpmsg_device *rpdev,
120 void *priv, u32 old, u32 new);
121 };
122
123 #if IS_ENABLED(CONFIG_RPMSG)
124
125 int rpmsg_register_device_override(struct rpmsg_device *rpdev,
126 const char *driver_override);
127 int register_rpmsg_device(struct rpmsg_device *dev);
128 void unregister_rpmsg_device(struct rpmsg_device *dev);
129 int __register_rpmsg_driver(struct rpmsg_driver *drv, struct module *owner);
130 void unregister_rpmsg_driver(struct rpmsg_driver *drv);
131 void rpmsg_destroy_ept(struct rpmsg_endpoint *);
132 struct rpmsg_endpoint *rpmsg_create_ept(struct rpmsg_device *,
133 rpmsg_rx_cb_t cb, void *priv,
134 struct rpmsg_channel_info chinfo);
135
136 int rpmsg_send(struct rpmsg_endpoint *ept, void *data, int len);
137 int rpmsg_sendto(struct rpmsg_endpoint *ept, void *data, int len, u32 dst);
138 int rpmsg_send_offchannel(struct rpmsg_endpoint *ept, u32 src, u32 dst,
139 void *data, int len);
140
141 int rpmsg_trysend(struct rpmsg_endpoint *ept, void *data, int len);
142 int rpmsg_trysendto(struct rpmsg_endpoint *ept, void *data, int len, u32 dst);
143 int rpmsg_trysend_offchannel(struct rpmsg_endpoint *ept, u32 src, u32 dst,
144 void *data, int len);
145
146 __poll_t rpmsg_poll(struct rpmsg_endpoint *ept, struct file *filp,
147 poll_table *wait);
148
149 int rpmsg_get_signals(struct rpmsg_endpoint *ept);
150 int rpmsg_set_signals(struct rpmsg_endpoint *ept, u32 set, u32 clear);
151
152 #else
153
rpmsg_register_device_override(struct rpmsg_device * rpdev,const char * driver_override)154 static inline int rpmsg_register_device_override(struct rpmsg_device *rpdev,
155 const char *driver_override)
156 {
157 return -ENXIO;
158 }
159
register_rpmsg_device(struct rpmsg_device * dev)160 static inline int register_rpmsg_device(struct rpmsg_device *dev)
161 {
162 return -ENXIO;
163 }
164
unregister_rpmsg_device(struct rpmsg_device * dev)165 static inline void unregister_rpmsg_device(struct rpmsg_device *dev)
166 {
167 /* This shouldn't be possible */
168 WARN_ON(1);
169 }
170
__register_rpmsg_driver(struct rpmsg_driver * drv,struct module * owner)171 static inline int __register_rpmsg_driver(struct rpmsg_driver *drv,
172 struct module *owner)
173 {
174 /* This shouldn't be possible */
175 WARN_ON(1);
176
177 return -ENXIO;
178 }
179
unregister_rpmsg_driver(struct rpmsg_driver * drv)180 static inline void unregister_rpmsg_driver(struct rpmsg_driver *drv)
181 {
182 /* This shouldn't be possible */
183 WARN_ON(1);
184 }
185
rpmsg_destroy_ept(struct rpmsg_endpoint * ept)186 static inline void rpmsg_destroy_ept(struct rpmsg_endpoint *ept)
187 {
188 /* This shouldn't be possible */
189 WARN_ON(1);
190 }
191
rpmsg_create_ept(struct rpmsg_device * rpdev,rpmsg_rx_cb_t cb,void * priv,struct rpmsg_channel_info chinfo)192 static inline struct rpmsg_endpoint *rpmsg_create_ept(struct rpmsg_device *rpdev,
193 rpmsg_rx_cb_t cb,
194 void *priv,
195 struct rpmsg_channel_info chinfo)
196 {
197 /* This shouldn't be possible */
198 WARN_ON(1);
199
200 return NULL;
201 }
202
rpmsg_send(struct rpmsg_endpoint * ept,void * data,int len)203 static inline int rpmsg_send(struct rpmsg_endpoint *ept, void *data, int len)
204 {
205 /* This shouldn't be possible */
206 WARN_ON(1);
207
208 return -ENXIO;
209 }
210
rpmsg_sendto(struct rpmsg_endpoint * ept,void * data,int len,u32 dst)211 static inline int rpmsg_sendto(struct rpmsg_endpoint *ept, void *data, int len,
212 u32 dst)
213 {
214 /* This shouldn't be possible */
215 WARN_ON(1);
216
217 return -ENXIO;
218
219 }
220
rpmsg_send_offchannel(struct rpmsg_endpoint * ept,u32 src,u32 dst,void * data,int len)221 static inline int rpmsg_send_offchannel(struct rpmsg_endpoint *ept, u32 src,
222 u32 dst, void *data, int len)
223 {
224 /* This shouldn't be possible */
225 WARN_ON(1);
226
227 return -ENXIO;
228 }
229
rpmsg_trysend(struct rpmsg_endpoint * ept,void * data,int len)230 static inline int rpmsg_trysend(struct rpmsg_endpoint *ept, void *data, int len)
231 {
232 /* This shouldn't be possible */
233 WARN_ON(1);
234
235 return -ENXIO;
236 }
237
rpmsg_trysendto(struct rpmsg_endpoint * ept,void * data,int len,u32 dst)238 static inline int rpmsg_trysendto(struct rpmsg_endpoint *ept, void *data,
239 int len, u32 dst)
240 {
241 /* This shouldn't be possible */
242 WARN_ON(1);
243
244 return -ENXIO;
245 }
246
rpmsg_trysend_offchannel(struct rpmsg_endpoint * ept,u32 src,u32 dst,void * data,int len)247 static inline int rpmsg_trysend_offchannel(struct rpmsg_endpoint *ept, u32 src,
248 u32 dst, void *data, int len)
249 {
250 /* This shouldn't be possible */
251 WARN_ON(1);
252
253 return -ENXIO;
254 }
255
rpmsg_poll(struct rpmsg_endpoint * ept,struct file * filp,poll_table * wait)256 static inline __poll_t rpmsg_poll(struct rpmsg_endpoint *ept,
257 struct file *filp, poll_table *wait)
258 {
259 /* This shouldn't be possible */
260 WARN_ON(1);
261
262 return 0;
263 }
264
rpmsg_get_signals(struct rpmsg_endpoint * ept)265 static inline int rpmsg_get_signals(struct rpmsg_endpoint *ept)
266 {
267 /* This shouldn't be possible */
268 WARN_ON(1);
269
270 return -ENXIO;
271 }
272
rpmsg_set_signals(struct rpmsg_endpoint * ept,u32 set,u32 clear)273 static inline int rpmsg_set_signals(struct rpmsg_endpoint *ept,
274 u32 set, u32 clear)
275 {
276 /* This shouldn't be possible */
277 WARN_ON(1);
278
279 return -ENXIO;
280 }
281
282 #endif /* IS_ENABLED(CONFIG_RPMSG) */
283
284 /* use a macro to avoid include chaining to get THIS_MODULE */
285 #define register_rpmsg_driver(drv) \
286 __register_rpmsg_driver(drv, THIS_MODULE)
287
288 /**
289 * module_rpmsg_driver() - Helper macro for registering an rpmsg driver
290 * @__rpmsg_driver: rpmsg_driver struct
291 *
292 * Helper macro for rpmsg drivers which do not do anything special in module
293 * init/exit. This eliminates a lot of boilerplate. Each module may only
294 * use this macro once, and calling it replaces module_init() and module_exit()
295 */
296 #define module_rpmsg_driver(__rpmsg_driver) \
297 module_driver(__rpmsg_driver, register_rpmsg_driver, \
298 unregister_rpmsg_driver)
299
300 #endif /* _LINUX_RPMSG_H */
301