About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / rpmsg.txt




Custom Search

Based on kernel version 4.13.3. Page generated on 2017-09-23 13:56 EST.

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_channel *rpdev, void *data, int len);
72	
73	sends a message across to the remote processor on a given channel.
74	The caller should specify the channel, the data it wants to send,
75	and its length (in bytes). The message will be sent on the specified
76	channel, i.e. its source and destination address fields will be
77	set to the channel's src and dst addresses.
78	
79	In case there are no TX buffers available, the function will block until
80	one becomes available (i.e. until the remote processor consumes
81	a tx buffer and puts it back on virtio's used descriptor ring),
82	or a timeout of 15 seconds elapses. When the latter happens,
83	-ERESTARTSYS is returned.
84	
85	The function can only be called from a process context (for now).
86	Returns 0 on success and an appropriate error value on failure.
87	
88	::
89	
90	  int rpmsg_sendto(struct rpmsg_channel *rpdev, void *data, int len, u32 dst);
91	
92	sends a message across to the remote processor on a given channel,
93	to a destination address provided by the caller.
94	
95	The caller should specify the channel, the data it wants to send,
96	its length (in bytes), and an explicit destination address.
97	
98	The message will then be sent to the remote processor to which the
99	channel belongs, using the channel's src address, and the user-provided
100	dst address (thus the channel's dst address will be ignored).
101	
102	In case there are no TX buffers available, the function will block until
103	one becomes available (i.e. until the remote processor consumes
104	a tx buffer and puts it back on virtio's used descriptor ring),
105	or a timeout of 15 seconds elapses. When the latter happens,
106	-ERESTARTSYS is returned.
107	
108	The function can only be called from a process context (for now).
109	Returns 0 on success and an appropriate error value on failure.
110	
111	::
112	
113	  int rpmsg_send_offchannel(struct rpmsg_channel *rpdev, u32 src, u32 dst,
114								void *data, int len);
115	
116	
117	sends a message across to the remote processor, using the src and dst
118	addresses provided by the user.
119	
120	The caller should specify the channel, the data it wants to send,
121	its length (in bytes), and explicit source and destination addresses.
122	The message will then be sent to the remote processor to which the
123	channel belongs, but the channel's src and dst addresses will be
124	ignored (and the user-provided addresses will be used instead).
125	
126	In case there are no TX buffers available, the function will block until
127	one becomes available (i.e. until the remote processor consumes
128	a tx buffer and puts it back on virtio's used descriptor ring),
129	or a timeout of 15 seconds elapses. When the latter happens,
130	-ERESTARTSYS is returned.
131	
132	The function can only be called from a process context (for now).
133	Returns 0 on success and an appropriate error value on failure.
134	
135	::
136	
137	  int rpmsg_trysend(struct rpmsg_channel *rpdev, void *data, int len);
138	
139	sends a message across to the remote processor on a given channel.
140	The caller should specify the channel, the data it wants to send,
141	and its length (in bytes). The message will be sent on the specified
142	channel, i.e. its source and destination address fields will be
143	set to the channel's src and dst addresses.
144	
145	In case there are no TX buffers available, the function will immediately
146	return -ENOMEM without waiting until one becomes available.
147	
148	The function can only be called from a process context (for now).
149	Returns 0 on success and an appropriate error value on failure.
150	
151	::
152	
153	  int rpmsg_trysendto(struct rpmsg_channel *rpdev, void *data, int len, u32 dst)
154	
155	
156	sends a message across to the remote processor on a given channel,
157	to a destination address provided by the user.
158	
159	The user should specify the channel, the data it wants to send,
160	its length (in bytes), and an explicit destination address.
161	
162	The message will then be sent to the remote processor to which the
163	channel belongs, using the channel's src address, and the user-provided
164	dst address (thus the channel's dst address will be ignored).
165	
166	In case there are no TX buffers available, the function will immediately
167	return -ENOMEM without waiting until one becomes available.
168	
169	The function can only be called from a process context (for now).
170	Returns 0 on success and an appropriate error value on failure.
171	
172	::
173	
174	  int rpmsg_trysend_offchannel(struct rpmsg_channel *rpdev, u32 src, u32 dst,
175								void *data, int len);
176	
177	
178	sends a message across to the remote processor, using source and
179	destination addresses provided by the user.
180	
181	The user should specify the channel, the data it wants to send,
182	its length (in bytes), and explicit source and destination addresses.
183	The message will then be sent to the remote processor to which the
184	channel belongs, but the channel's src and dst addresses will be
185	ignored (and the user-provided addresses will be used instead).
186	
187	In case there are no TX buffers available, the function will immediately
188	return -ENOMEM without waiting until one becomes available.
189	
190	The function can only be called from a process context (for now).
191	Returns 0 on success and an appropriate error value on failure.
192	
193	::
194	
195	  struct rpmsg_endpoint *rpmsg_create_ept(struct rpmsg_channel *rpdev,
196			void (*cb)(struct rpmsg_channel *, void *, int, void *, u32),
197			void *priv, u32 addr);
198	
199	every rpmsg address in the system is bound to an rx callback (so when
200	inbound messages arrive, they are dispatched by the rpmsg bus using the
201	appropriate callback handler) by means of an rpmsg_endpoint struct.
202	
203	This function allows drivers to create such an endpoint, and by that,
204	bind a callback, and possibly some private data too, to an rpmsg address
205	(either one that is known in advance, or one that will be dynamically
206	assigned for them).
207	
208	Simple rpmsg drivers need not call rpmsg_create_ept, because an endpoint
209	is already created for them when they are probed by the rpmsg bus
210	(using the rx callback they provide when they registered to the rpmsg bus).
211	
212	So things should just work for simple drivers: they already have an
213	endpoint, their rx callback is bound to their rpmsg address, and when
214	relevant inbound messages arrive (i.e. messages which their dst address
215	equals to the src address of their rpmsg channel), the driver's handler
216	is invoked to process it.
217	
218	That said, more complicated drivers might do need to allocate
219	additional rpmsg addresses, and bind them to different rx callbacks.
220	To accomplish that, those drivers need to call this function.
221	Drivers should provide their channel (so the new endpoint would bind
222	to the same remote processor their channel belongs to), an rx callback
223	function, an optional private data (which is provided back when the
224	rx callback is invoked), and an address they want to bind with the
225	callback. If addr is RPMSG_ADDR_ANY, then rpmsg_create_ept will
226	dynamically assign them an available rpmsg address (drivers should have
227	a very good reason why not to always use RPMSG_ADDR_ANY here).
228	
229	Returns a pointer to the endpoint on success, or NULL on error.
230	
231	::
232	
233	  void rpmsg_destroy_ept(struct rpmsg_endpoint *ept);
234	
235	
236	destroys an existing rpmsg endpoint. user should provide a pointer
237	to an rpmsg endpoint that was previously created with rpmsg_create_ept().
238	
239	::
240	
241	  int register_rpmsg_driver(struct rpmsg_driver *rpdrv);
242	
243	
244	registers an rpmsg driver with the rpmsg bus. user should provide
245	a pointer to an rpmsg_driver struct, which contains the driver's
246	->probe() and ->remove() functions, an rx callback, and an id_table
247	specifying the names of the channels this driver is interested to
248	be probed with.
249	
250	::
251	
252	  void unregister_rpmsg_driver(struct rpmsg_driver *rpdrv);
253	
254	
255	unregisters an rpmsg driver from the rpmsg bus. user should provide
256	a pointer to a previously-registered rpmsg_driver struct.
257	Returns 0 on success, and an appropriate error value on failure.
258	
259	
260	Typical usage
261	=============
262	
263	The following is a simple rpmsg driver, that sends an "hello!" message
264	on probe(), and whenever it receives an incoming message, it dumps its
265	content to the console.
266	
267	::
268	
269	  #include <linux/kernel.h>
270	  #include <linux/module.h>
271	  #include <linux/rpmsg.h>
272	
273	  static void rpmsg_sample_cb(struct rpmsg_channel *rpdev, void *data, int len,
274							void *priv, u32 src)
275	  {
276		print_hex_dump(KERN_INFO, "incoming message:", DUMP_PREFIX_NONE,
277							16, 1, data, len, true);
278	  }
279	
280	  static int rpmsg_sample_probe(struct rpmsg_channel *rpdev)
281	  {
282		int err;
283	
284		dev_info(&rpdev->dev, "chnl: 0x%x -> 0x%x\n", rpdev->src, rpdev->dst);
285	
286		/* send a message on our channel */
287		err = rpmsg_send(rpdev, "hello!", 6);
288		if (err) {
289			pr_err("rpmsg_send failed: %d\n", err);
290			return err;
291		}
292	
293		return 0;
294	  }
295	
296	  static void rpmsg_sample_remove(struct rpmsg_channel *rpdev)
297	  {
298		dev_info(&rpdev->dev, "rpmsg sample client driver is removed\n");
299	  }
300	
301	  static struct rpmsg_device_id rpmsg_driver_sample_id_table[] = {
302		{ .name	= "rpmsg-client-sample" },
303		{ },
304	  };
305	  MODULE_DEVICE_TABLE(rpmsg, rpmsg_driver_sample_id_table);
306	
307	  static struct rpmsg_driver rpmsg_sample_client = {
308		.drv.name	= KBUILD_MODNAME,
309		.id_table	= rpmsg_driver_sample_id_table,
310		.probe		= rpmsg_sample_probe,
311		.callback	= rpmsg_sample_cb,
312		.remove		= rpmsg_sample_remove,
313	  };
314	  module_rpmsg_driver(rpmsg_sample_client);
315	
316	.. note::
317	
318	   a similar sample which can be built and loaded can be found
319	   in samples/rpmsg/.
320	
321	Allocations of rpmsg channels
322	=============================
323	
324	At this point we only support dynamic allocations of rpmsg channels.
325	
326	This is possible only with remote processors that have the VIRTIO_RPMSG_F_NS
327	virtio device feature set. This feature bit means that the remote
328	processor supports dynamic name service announcement messages.
329	
330	When this feature is enabled, creation of rpmsg devices (i.e. channels)
331	is completely dynamic: the remote processor announces the existence of a
332	remote rpmsg service by sending a name service message (which contains
333	the name and rpmsg addr of the remote service, see struct rpmsg_ns_msg).
334	
335	This message is then handled by the rpmsg bus, which in turn dynamically
336	creates and registers an rpmsg channel (which represents the remote service).
337	If/when a relevant rpmsg driver is registered, it will be immediately probed
338	by the bus, and can then start sending messages to the remote service.
339	
340	The plan is also to add static creation of rpmsg channels via the virtio
341	config space, but it's not implemented yet.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.