Back to home page

LXR

 
 

    


0001 Remote Processor Messaging (rpmsg) Framework
0002 
0003 Note: this document describes the rpmsg bus and how to write rpmsg drivers.
0004 To learn how to add rpmsg support for new platforms, check out remoteproc.txt
0005 (also a resident of Documentation/).
0006 
0007 1. Introduction
0008 
0009 Modern SoCs typically employ heterogeneous remote processor devices in
0010 asymmetric multiprocessing (AMP) configurations, which may be running
0011 different instances of operating system, whether it's Linux or any other
0012 flavor of real-time OS.
0013 
0014 OMAP4, for example, has dual Cortex-A9, dual Cortex-M3 and a C64x+ DSP.
0015 Typically, the dual cortex-A9 is running Linux in a SMP configuration,
0016 and each of the other three cores (two M3 cores and a DSP) is running
0017 its own instance of RTOS in an AMP configuration.
0018 
0019 Typically AMP remote processors employ dedicated DSP codecs and multimedia
0020 hardware accelerators, and therefore are often used to offload CPU-intensive
0021 multimedia tasks from the main application processor.
0022 
0023 These remote processors could also be used to control latency-sensitive
0024 sensors, drive random hardware blocks, or just perform background tasks
0025 while the main CPU is idling.
0026 
0027 Users of those remote processors can either be userland apps (e.g. multimedia
0028 frameworks talking with remote OMX components) or kernel drivers (controlling
0029 hardware accessible only by the remote processor, reserving kernel-controlled
0030 resources on behalf of the remote processor, etc..).
0031 
0032 Rpmsg is a virtio-based messaging bus that allows kernel drivers to communicate
0033 with remote processors available on the system. In turn, drivers could then
0034 expose appropriate user space interfaces, if needed.
0035 
0036 When writing a driver that exposes rpmsg communication to userland, please
0037 keep in mind that remote processors might have direct access to the
0038 system's physical memory and other sensitive hardware resources (e.g. on
0039 OMAP4, remote cores and hardware accelerators may have direct access to the
0040 physical memory, gpio banks, dma controllers, i2c bus, gptimers, mailbox
0041 devices, hwspinlocks, etc..). Moreover, those remote processors might be
0042 running RTOS where every task can access the entire memory/devices exposed
0043 to the processor. To minimize the risks of rogue (or buggy) userland code
0044 exploiting remote bugs, and by that taking over the system, it is often
0045 desired to limit userland to specific rpmsg channels (see definition below)
0046 it can send messages on, and if possible, minimize how much control
0047 it has over the content of the messages.
0048 
0049 Every rpmsg device is a communication channel with a remote processor (thus
0050 rpmsg devices are called channels). Channels are identified by a textual name
0051 and have a local ("source") rpmsg address, and remote ("destination") rpmsg
0052 address.
0053 
0054 When a driver starts listening on a channel, its rx callback is bound with
0055 a unique rpmsg local address (a 32-bit integer). This way when inbound messages
0056 arrive, the rpmsg core dispatches them to the appropriate driver according
0057 to their destination address (this is done by invoking the driver's rx handler
0058 with the payload of the inbound message).
0059 
0060 
0061 2. User API
0062 
0063   int rpmsg_send(struct rpmsg_channel *rpdev, void *data, int len);
0064    - sends a message across to the remote processor on a given channel.
0065      The caller should specify the channel, the data it wants to send,
0066      and its length (in bytes). The message will be sent on the specified
0067      channel, i.e. its source and destination address fields will be
0068      set to the channel's src and dst addresses.
0069 
0070      In case there are no TX buffers available, the function will block until
0071      one becomes available (i.e. until the remote processor consumes
0072      a tx buffer and puts it back on virtio's used descriptor ring),
0073      or a timeout of 15 seconds elapses. When the latter happens,
0074      -ERESTARTSYS is returned.
0075      The function can only be called from a process context (for now).
0076      Returns 0 on success and an appropriate error value on failure.
0077 
0078   int rpmsg_sendto(struct rpmsg_channel *rpdev, void *data, int len, u32 dst);
0079    - sends a message across to the remote processor on a given channel,
0080      to a destination address provided by the caller.
0081      The caller should specify the channel, the data it wants to send,
0082      its length (in bytes), and an explicit destination address.
0083      The message will then be sent to the remote processor to which the
0084      channel belongs, using the channel's src address, and the user-provided
0085      dst address (thus the channel's dst address will be ignored).
0086 
0087      In case there are no TX buffers available, the function will block until
0088      one becomes available (i.e. until the remote processor consumes
0089      a tx buffer and puts it back on virtio's used descriptor ring),
0090      or a timeout of 15 seconds elapses. When the latter happens,
0091      -ERESTARTSYS is returned.
0092      The function can only be called from a process context (for now).
0093      Returns 0 on success and an appropriate error value on failure.
0094 
0095   int rpmsg_send_offchannel(struct rpmsg_channel *rpdev, u32 src, u32 dst,
0096                                                         void *data, int len);
0097    - sends a message across to the remote processor, using the src and dst
0098      addresses provided by the user.
0099      The caller should specify the channel, the data it wants to send,
0100      its length (in bytes), and explicit source and destination addresses.
0101      The message will then be sent to the remote processor to which the
0102      channel belongs, but the channel's src and dst addresses will be
0103      ignored (and the user-provided addresses will be used instead).
0104 
0105      In case there are no TX buffers available, the function will block until
0106      one becomes available (i.e. until the remote processor consumes
0107      a tx buffer and puts it back on virtio's used descriptor ring),
0108      or a timeout of 15 seconds elapses. When the latter happens,
0109      -ERESTARTSYS is returned.
0110      The function can only be called from a process context (for now).
0111      Returns 0 on success and an appropriate error value on failure.
0112 
0113   int rpmsg_trysend(struct rpmsg_channel *rpdev, void *data, int len);
0114    - sends a message across to the remote processor on a given channel.
0115      The caller should specify the channel, the data it wants to send,
0116      and its length (in bytes). The message will be sent on the specified
0117      channel, i.e. its source and destination address fields will be
0118      set to the channel's src and dst addresses.
0119 
0120      In case there are no TX buffers available, the function will immediately
0121      return -ENOMEM without waiting until one becomes available.
0122      The function can only be called from a process context (for now).
0123      Returns 0 on success and an appropriate error value on failure.
0124 
0125   int rpmsg_trysendto(struct rpmsg_channel *rpdev, void *data, int len, u32 dst)
0126    - sends a message across to the remote processor on a given channel,
0127      to a destination address provided by the user.
0128      The user should specify the channel, the data it wants to send,
0129      its length (in bytes), and an explicit destination address.
0130      The message will then be sent to the remote processor to which the
0131      channel belongs, using the channel's src address, and the user-provided
0132      dst address (thus the channel's dst address will be ignored).
0133 
0134      In case there are no TX buffers available, the function will immediately
0135      return -ENOMEM without waiting until one becomes available.
0136      The function can only be called from a process context (for now).
0137      Returns 0 on success and an appropriate error value on failure.
0138 
0139   int rpmsg_trysend_offchannel(struct rpmsg_channel *rpdev, u32 src, u32 dst,
0140                                                         void *data, int len);
0141    - sends a message across to the remote processor, using source and
0142      destination addresses provided by the user.
0143      The user should specify the channel, the data it wants to send,
0144      its length (in bytes), and explicit source and destination addresses.
0145      The message will then be sent to the remote processor to which the
0146      channel belongs, but the channel's src and dst addresses will be
0147      ignored (and the user-provided addresses will be used instead).
0148 
0149      In case there are no TX buffers available, the function will immediately
0150      return -ENOMEM without waiting until one becomes available.
0151      The function can only be called from a process context (for now).
0152      Returns 0 on success and an appropriate error value on failure.
0153 
0154   struct rpmsg_endpoint *rpmsg_create_ept(struct rpmsg_channel *rpdev,
0155                 void (*cb)(struct rpmsg_channel *, void *, int, void *, u32),
0156                 void *priv, u32 addr);
0157    - every rpmsg address in the system is bound to an rx callback (so when
0158      inbound messages arrive, they are dispatched by the rpmsg bus using the
0159      appropriate callback handler) by means of an rpmsg_endpoint struct.
0160 
0161      This function allows drivers to create such an endpoint, and by that,
0162      bind a callback, and possibly some private data too, to an rpmsg address
0163      (either one that is known in advance, or one that will be dynamically
0164      assigned for them).
0165 
0166      Simple rpmsg drivers need not call rpmsg_create_ept, because an endpoint
0167      is already created for them when they are probed by the rpmsg bus
0168      (using the rx callback they provide when they registered to the rpmsg bus).
0169 
0170      So things should just work for simple drivers: they already have an
0171      endpoint, their rx callback is bound to their rpmsg address, and when
0172      relevant inbound messages arrive (i.e. messages which their dst address
0173      equals to the src address of their rpmsg channel), the driver's handler
0174      is invoked to process it.
0175 
0176      That said, more complicated drivers might do need to allocate
0177      additional rpmsg addresses, and bind them to different rx callbacks.
0178      To accomplish that, those drivers need to call this function.
0179      Drivers should provide their channel (so the new endpoint would bind
0180      to the same remote processor their channel belongs to), an rx callback
0181      function, an optional private data (which is provided back when the
0182      rx callback is invoked), and an address they want to bind with the
0183      callback. If addr is RPMSG_ADDR_ANY, then rpmsg_create_ept will
0184      dynamically assign them an available rpmsg address (drivers should have
0185      a very good reason why not to always use RPMSG_ADDR_ANY here).
0186 
0187      Returns a pointer to the endpoint on success, or NULL on error.
0188 
0189   void rpmsg_destroy_ept(struct rpmsg_endpoint *ept);
0190    - destroys an existing rpmsg endpoint. user should provide a pointer
0191      to an rpmsg endpoint that was previously created with rpmsg_create_ept().
0192 
0193   int register_rpmsg_driver(struct rpmsg_driver *rpdrv);
0194    - registers an rpmsg driver with the rpmsg bus. user should provide
0195      a pointer to an rpmsg_driver struct, which contains the driver's
0196      ->probe() and ->remove() functions, an rx callback, and an id_table
0197      specifying the names of the channels this driver is interested to
0198      be probed with.
0199 
0200   void unregister_rpmsg_driver(struct rpmsg_driver *rpdrv);
0201    - unregisters an rpmsg driver from the rpmsg bus. user should provide
0202      a pointer to a previously-registered rpmsg_driver struct.
0203      Returns 0 on success, and an appropriate error value on failure.
0204 
0205 
0206 3. Typical usage
0207 
0208 The following is a simple rpmsg driver, that sends an "hello!" message
0209 on probe(), and whenever it receives an incoming message, it dumps its
0210 content to the console.
0211 
0212 #include <linux/kernel.h>
0213 #include <linux/module.h>
0214 #include <linux/rpmsg.h>
0215 
0216 static void rpmsg_sample_cb(struct rpmsg_channel *rpdev, void *data, int len,
0217                                                 void *priv, u32 src)
0218 {
0219         print_hex_dump(KERN_INFO, "incoming message:", DUMP_PREFIX_NONE,
0220                                                 16, 1, data, len, true);
0221 }
0222 
0223 static int rpmsg_sample_probe(struct rpmsg_channel *rpdev)
0224 {
0225         int err;
0226 
0227         dev_info(&rpdev->dev, "chnl: 0x%x -> 0x%x\n", rpdev->src, rpdev->dst);
0228 
0229         /* send a message on our channel */
0230         err = rpmsg_send(rpdev, "hello!", 6);
0231         if (err) {
0232                 pr_err("rpmsg_send failed: %d\n", err);
0233                 return err;
0234         }
0235 
0236         return 0;
0237 }
0238 
0239 static void rpmsg_sample_remove(struct rpmsg_channel *rpdev)
0240 {
0241         dev_info(&rpdev->dev, "rpmsg sample client driver is removed\n");
0242 }
0243 
0244 static struct rpmsg_device_id rpmsg_driver_sample_id_table[] = {
0245         { .name = "rpmsg-client-sample" },
0246         { },
0247 };
0248 MODULE_DEVICE_TABLE(rpmsg, rpmsg_driver_sample_id_table);
0249 
0250 static struct rpmsg_driver rpmsg_sample_client = {
0251         .drv.name       = KBUILD_MODNAME,
0252         .id_table       = rpmsg_driver_sample_id_table,
0253         .probe          = rpmsg_sample_probe,
0254         .callback       = rpmsg_sample_cb,
0255         .remove         = rpmsg_sample_remove,
0256 };
0257 module_rpmsg_driver(rpmsg_sample_client);
0258 
0259 Note: a similar sample which can be built and loaded can be found
0260 in samples/rpmsg/.
0261 
0262 4. Allocations of rpmsg channels:
0263 
0264 At this point we only support dynamic allocations of rpmsg channels.
0265 
0266 This is possible only with remote processors that have the VIRTIO_RPMSG_F_NS
0267 virtio device feature set. This feature bit means that the remote
0268 processor supports dynamic name service announcement messages.
0269 
0270 When this feature is enabled, creation of rpmsg devices (i.e. channels)
0271 is completely dynamic: the remote processor announces the existence of a
0272 remote rpmsg service by sending a name service message (which contains
0273 the name and rpmsg addr of the remote service, see struct rpmsg_ns_msg).
0274 
0275 This message is then handled by the rpmsg bus, which in turn dynamically
0276 creates and registers an rpmsg channel (which represents the remote service).
0277 If/when a relevant rpmsg driver is registered, it will be immediately probed
0278 by the bus, and can then start sending messages to the remote service.
0279 
0280 The plan is also to add static creation of rpmsg channels via the virtio
0281 config space, but it's not implemented yet.