1 ============================================
2 Remote Processor Messaging (rpmsg) Framework
3 ============================================
4
5 .. note::
6
7 This document describes the rpmsg bus and how to write rpmsg drivers.
8 To learn how to add rpmsg support for new platforms, check out remoteproc.txt
9 (also a resident of Documentation/).
10
11 Introduction
12 ============
13
14 Modern SoCs typically employ heterogeneous remote processor devices in
15 asymmetric multiprocessing (AMP) configurations, which may be running
16 different instances of operating system, whether it's Linux or any other
17 flavor of real-time OS.
18
19 OMAP4, for example, has dual Cortex-A9, dual Cortex-M3 and a C64x+ DSP.
20 Typically, the dual cortex-A9 is running Linux in a SMP configuration,
21 and each of the other three cores (two M3 cores and a DSP) is running
22 its own instance of RTOS in an AMP configuration.
23
24 Typically AMP remote processors employ dedicated DSP codecs and multimedia
25 hardware accelerators, and therefore are often used to offload CPU-intensive
26 multimedia tasks from the main application processor.
27
28 These remote processors could also be used to control latency-sensitive
29 sensors, drive random hardware blocks, or just perform background tasks
30 while the main CPU is idling.
31
32 Users of those remote processors can either be userland apps (e.g. multimedia
33 frameworks talking with remote OMX components) or kernel drivers (controlling
34 hardware accessible only by the remote processor, reserving kernel-controlled
35 resources on behalf of the remote processor, etc..).
36
37 Rpmsg is a virtio-based messaging bus that allows kernel drivers to communicate
38 with remote processors available on the system. In turn, drivers could then
39 expose appropriate user space interfaces, if needed.
40
41 When writing a driver that exposes rpmsg communication to userland, please
42 keep in mind that remote processors might have direct access to the
43 system's physical memory and other sensitive hardware resources (e.g. on
44 OMAP4, remote cores and hardware accelerators may have direct access to the
45 physical memory, gpio banks, dma controllers, i2c bus, gptimers, mailbox
46 devices, hwspinlocks, etc..). Moreover, those remote processors might be
47 running RTOS where every task can access the entire memory/devices exposed
48 to the processor. To minimize the risks of rogue (or buggy) userland code
49 exploiting remote bugs, and by that taking over the system, it is often
50 desired to limit userland to specific rpmsg channels (see definition below)
51 it can send messages on, and if possible, minimize how much control
52 it has over the content of the messages.
53
54 Every rpmsg device is a communication channel with a remote processor (thus
55 rpmsg devices are called channels). Channels are identified by a textual name
56 and have a local ("source") rpmsg address, and remote ("destination") rpmsg
57 address.
58
59 When a driver starts listening on a channel, its rx callback is bound with
60 a unique rpmsg local address (a 32-bit integer). This way when inbound messages
61 arrive, the rpmsg core dispatches them to the appropriate driver according
62 to their destination address (this is done by invoking the driver's rx handler
63 with the payload of the inbound message).
64
65
66 User API
67 ========
68
69 ::
70
71 int rpmsg_send(struct rpmsg_endpoint *ept, void *data, int len);
72
73 sends a message across to the remote processor from the given endpoint.
74 The caller should specify the endpoint, the data it wants to send,
75 and its length (in bytes). The message will be sent on the specified
76 endpoint's channel, i.e. its source and destination address fields will be
77 respectively set to the endpoint's src address and its parent channel
78 dst addresses.
79
80 In case there are no TX buffers available, the function will block until
81 one becomes available (i.e. until the remote processor consumes
82 a tx buffer and puts it back on virtio's used descriptor ring),
83 or a timeout of 15 seconds elapses. When the latter happens,
84 -ERESTARTSYS is returned.
85
86 The function can only be called from a process context (for now).
87 Returns 0 on success and an appropriate error value on failure.
88
89 ::
90
91 int rpmsg_sendto(struct rpmsg_endpoint *ept, void *data, int len, u32 dst);
92
93 sends a message across to the remote processor from a given endpoint,
94 to a destination address provided by the caller.
95
96 The caller should specify the endpoint, the data it wants to send,
97 its length (in bytes), and an explicit destination address.
98
99 The message will then be sent to the remote processor to which the
100 endpoints's channel belongs, using the endpoints's src address,
101 and the user-provided dst address (thus the channel's dst address
102 will be ignored).
103
104 In case there are no TX buffers available, the function will block until
105 one becomes available (i.e. until the remote processor consumes
106 a tx buffer and puts it back on virtio's used descriptor ring),
107 or a timeout of 15 seconds elapses. When the latter happens,
108 -ERESTARTSYS is returned.
109
110 The function can only be called from a process context (for now).
111 Returns 0 on success and an appropriate error value on failure.
112
113 ::
114
115 int rpmsg_send_offchannel(struct rpmsg_endpoint *ept, u32 src, u32 dst,
116 void *data, int len);
117
118
119 sends a message across to the remote processor, using the src and dst
120 addresses provided by the user.
121
122 The caller should specify the endpoint, the data it wants to send,
123 its length (in bytes), and explicit source and destination addresses.
124 The message will then be sent to the remote processor to which the
125 endpoint's channel belongs, but the endpoint's src and channel dst
126 addresses will be ignored (and the user-provided addresses will
127 be used instead).
128
129 In case there are no TX buffers available, the function will block until
130 one becomes available (i.e. until the remote processor consumes
131 a tx buffer and puts it back on virtio's used descriptor ring),
132 or a timeout of 15 seconds elapses. When the latter happens,
133 -ERESTARTSYS is returned.
134
135 The function can only be called from a process context (for now).
136 Returns 0 on success and an appropriate error value on failure.
137
138 ::
139
140 int rpmsg_trysend(struct rpmsg_endpoint *ept, void *data, int len);
141
142 sends a message across to the remote processor from a given endpoint.
143 The caller should specify the endpoint, the data it wants to send,
144 and its length (in bytes). The message will be sent on the specified
145 endpoint's channel, i.e. its source and destination address fields will be
146 respectively set to the endpoint's src address and its parent channel
147 dst addresses.
148
149 In case there are no TX buffers available, the function will immediately
150 return -ENOMEM without waiting until one becomes available.
151
152 The function can only be called from a process context (for now).
153 Returns 0 on success and an appropriate error value on failure.
154
155 ::
156
157 int rpmsg_trysendto(struct rpmsg_endpoint *ept, void *data, int len, u32 dst)
158
159
160 sends a message across to the remote processor from a given endpoint,
161 to a destination address provided by the user.
162
163 The user should specify the channel, the data it wants to send,
164 its length (in bytes), and an explicit destination address.
165
166 The message will then be sent to the remote processor to which the
167 channel belongs, using the channel's src address, and the user-provided
168 dst address (thus the channel's dst address will be ignored).
169
170 In case there are no TX buffers available, the function will immediately
171 return -ENOMEM without waiting until one becomes available.
172
173 The function can only be called from a process context (for now).
174 Returns 0 on success and an appropriate error value on failure.
175
176 ::
177
178 int rpmsg_trysend_offchannel(struct rpmsg_endpoint *ept, u32 src, u32 dst,
179 void *data, int len);
180
181
182 sends a message across to the remote processor, using source and
183 destination addresses provided by the user.
184
185 The user should specify the channel, the data it wants to send,
186 its length (in bytes), and explicit source and destination addresses.
187 The message will then be sent to the remote processor to which the
188 channel belongs, but the channel's src and dst addresses will be
189 ignored (and the user-provided addresses will be used instead).
190
191 In case there are no TX buffers available, the function will immediately
192 return -ENOMEM without waiting until one becomes available.
193
194 The function can only be called from a process context (for now).
195 Returns 0 on success and an appropriate error value on failure.
196
197 ::
198
199 struct rpmsg_endpoint *rpmsg_create_ept(struct rpmsg_device *rpdev,
200 rpmsg_rx_cb_t cb, void *priv,
201 struct rpmsg_channel_info chinfo);
202
203 every rpmsg address in the system is bound to an rx callback (so when
204 inbound messages arrive, they are dispatched by the rpmsg bus using the
205 appropriate callback handler) by means of an rpmsg_endpoint struct.
206
207 This function allows drivers to create such an endpoint, and by that,
208 bind a callback, and possibly some private data too, to an rpmsg address
209 (either one that is known in advance, or one that will be dynamically
210 assigned for them).
211
212 Simple rpmsg drivers need not call rpmsg_create_ept, because an endpoint
213 is already created for them when they are probed by the rpmsg bus
214 (using the rx callback they provide when they registered to the rpmsg bus).
215
216 So things should just work for simple drivers: they already have an
217 endpoint, their rx callback is bound to their rpmsg address, and when
218 relevant inbound messages arrive (i.e. messages which their dst address
219 equals to the src address of their rpmsg channel), the driver's handler
220 is invoked to process it.
221
222 That said, more complicated drivers might do need to allocate
223 additional rpmsg addresses, and bind them to different rx callbacks.
224 To accomplish that, those drivers need to call this function.
225 Drivers should provide their channel (so the new endpoint would bind
226 to the same remote processor their channel belongs to), an rx callback
227 function, an optional private data (which is provided back when the
228 rx callback is invoked), and an address they want to bind with the
229 callback. If addr is RPMSG_ADDR_ANY, then rpmsg_create_ept will
230 dynamically assign them an available rpmsg address (drivers should have
231 a very good reason why not to always use RPMSG_ADDR_ANY here).
232
233 Returns a pointer to the endpoint on success, or NULL on error.
234
235 ::
236
237 void rpmsg_destroy_ept(struct rpmsg_endpoint *ept);
238
239
240 destroys an existing rpmsg endpoint. user should provide a pointer
241 to an rpmsg endpoint that was previously created with rpmsg_create_ept().
242
243 ::
244
245 int register_rpmsg_driver(struct rpmsg_driver *rpdrv);
246
247
248 registers an rpmsg driver with the rpmsg bus. user should provide
249 a pointer to an rpmsg_driver struct, which contains the driver's
250 ->probe() and ->remove() functions, an rx callback, and an id_table
251 specifying the names of the channels this driver is interested to
252 be probed with.
253
254 ::
255
256 void unregister_rpmsg_driver(struct rpmsg_driver *rpdrv);
257
258
259 unregisters an rpmsg driver from the rpmsg bus. user should provide
260 a pointer to a previously-registered rpmsg_driver struct.
261 Returns 0 on success, and an appropriate error value on failure.
262
263
264 Typical usage
265 =============
266
267 The following is a simple rpmsg driver, that sends an "hello!" message
268 on probe(), and whenever it receives an incoming message, it dumps its
269 content to the console.
270
271 ::
272
273 #include <linux/kernel.h>
274 #include <linux/module.h>
275 #include <linux/rpmsg.h>
276
277 static void rpmsg_sample_cb(struct rpmsg_channel *rpdev, void *data, int len,
278 void *priv, u32 src)
279 {
280 print_hex_dump(KERN_INFO, "incoming message:", DUMP_PREFIX_NONE,
281 16, 1, data, len, true);
282 }
283
284 static int rpmsg_sample_probe(struct rpmsg_channel *rpdev)
285 {
286 int err;
287
288 dev_info(&rpdev->dev, "chnl: 0x%x -> 0x%x\n", rpdev->src, rpdev->dst);
289
290 /* send a message on our channel */
291 err = rpmsg_send(rpdev->ept, "hello!", 6);
292 if (err) {
293 pr_err("rpmsg_send failed: %d\n", err);
294 return err;
295 }
296
297 return 0;
298 }
299
300 static void rpmsg_sample_remove(struct rpmsg_channel *rpdev)
301 {
302 dev_info(&rpdev->dev, "rpmsg sample client driver is removed\n");
303 }
304
305 static struct rpmsg_device_id rpmsg_driver_sample_id_table[] = {
306 { .name = "rpmsg-client-sample" },
307 { },
308 };
309 MODULE_DEVICE_TABLE(rpmsg, rpmsg_driver_sample_id_table);
310
311 static struct rpmsg_driver rpmsg_sample_client = {
312 .drv.name = KBUILD_MODNAME,
313 .id_table = rpmsg_driver_sample_id_table,
314 .probe = rpmsg_sample_probe,
315 .callback = rpmsg_sample_cb,
316 .remove = rpmsg_sample_remove,
317 };
318 module_rpmsg_driver(rpmsg_sample_client);
319
320 .. note::
321
322 a similar sample which can be built and loaded can be found
323 in samples/rpmsg/.
324
325 Allocations of rpmsg channels
326 =============================
327
328 At this point we only support dynamic allocations of rpmsg channels.
329
330 This is possible only with remote processors that have the VIRTIO_RPMSG_F_NS
331 virtio device feature set. This feature bit means that the remote
332 processor supports dynamic name service announcement messages.
333
334 When this feature is enabled, creation of rpmsg devices (i.e. channels)
335 is completely dynamic: the remote processor announces the existence of a
336 remote rpmsg service by sending a name service message (which contains
337 the name and rpmsg addr of the remote service, see struct rpmsg_ns_msg).
338
339 This message is then handled by the rpmsg bus, which in turn dynamically
340 creates and registers an rpmsg channel (which represents the remote service).
341 If/when a relevant rpmsg driver is registered, it will be immediately probed
342 by the bus, and can then start sending messages to the remote service.
343
344 The plan is also to add static creation of rpmsg channels via the virtio
345 config space, but it's not implemented yet.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.