linux/Documentation/rpmsg.txt
<<
>>
Prefs
   1Remote Processor Messaging (rpmsg) Framework
   2
   3Note: this document describes the rpmsg bus and how to write rpmsg drivers.
   4To learn how to add rpmsg support for new platforms, check out remoteproc.txt
   5(also a resident of Documentation/).
   6
   71. Introduction
   8
   9Modern SoCs typically employ heterogeneous remote processor devices in
  10asymmetric multiprocessing (AMP) configurations, which may be running
  11different instances of operating system, whether it's Linux or any other
  12flavor of real-time OS.
  13
  14OMAP4, for example, has dual Cortex-A9, dual Cortex-M3 and a C64x+ DSP.
  15Typically, the dual cortex-A9 is running Linux in a SMP configuration,
  16and each of the other three cores (two M3 cores and a DSP) is running
  17its own instance of RTOS in an AMP configuration.
  18
  19Typically AMP remote processors employ dedicated DSP codecs and multimedia
  20hardware accelerators, and therefore are often used to offload CPU-intensive
  21multimedia tasks from the main application processor.
  22
  23These remote processors could also be used to control latency-sensitive
  24sensors, drive random hardware blocks, or just perform background tasks
  25while the main CPU is idling.
  26
  27Users of those remote processors can either be userland apps (e.g. multimedia
  28frameworks talking with remote OMX components) or kernel drivers (controlling
  29hardware accessible only by the remote processor, reserving kernel-controlled
  30resources on behalf of the remote processor, etc..).
  31
  32Rpmsg is a virtio-based messaging bus that allows kernel drivers to communicate
  33with remote processors available on the system. In turn, drivers could then
  34expose appropriate user space interfaces, if needed.
  35
  36When writing a driver that exposes rpmsg communication to userland, please
  37keep in mind that remote processors might have direct access to the
  38system's physical memory and other sensitive hardware resources (e.g. on
  39OMAP4, remote cores and hardware accelerators may have direct access to the
  40physical memory, gpio banks, dma controllers, i2c bus, gptimers, mailbox
  41devices, hwspinlocks, etc..). Moreover, those remote processors might be
  42running RTOS where every task can access the entire memory/devices exposed
  43to the processor. To minimize the risks of rogue (or buggy) userland code
  44exploiting remote bugs, and by that taking over the system, it is often
  45desired to limit userland to specific rpmsg channels (see definition below)
  46it can send messages on, and if possible, minimize how much control
  47it has over the content of the messages.
  48
  49Every rpmsg device is a communication channel with a remote processor (thus
  50rpmsg devices are called channels). Channels are identified by a textual name
  51and have a local ("source") rpmsg address, and remote ("destination") rpmsg
  52address.
  53
  54When a driver starts listening on a channel, its rx callback is bound with
  55a unique rpmsg local address (a 32-bit integer). This way when inbound messages
  56arrive, the rpmsg core dispatches them to the appropriate driver according
  57to their destination address (this is done by invoking the driver's rx handler
  58with the payload of the inbound message).
  59
  60
  612. User API
  62
  63  int rpmsg_send(struct rpmsg_channel *rpdev, void *data, int len);
  64   - sends a message across to the remote processor on a given channel.
  65     The caller should specify the channel, the data it wants to send,
  66     and its length (in bytes). The message will be sent on the specified
  67     channel, i.e. its source and destination address fields will be
  68     set to the channel's src and dst addresses.
  69
  70     In case there are no TX buffers available, the function will block until
  71     one becomes available (i.e. until the remote processor consumes
  72     a tx buffer and puts it back on virtio's used descriptor ring),
  73     or a timeout of 15 seconds elapses. When the latter happens,
  74     -ERESTARTSYS is returned.
  75     The function can only be called from a process context (for now).
  76     Returns 0 on success and an appropriate error value on failure.
  77
  78  int rpmsg_sendto(struct rpmsg_channel *rpdev, void *data, int len, u32 dst);
  79   - sends a message across to the remote processor on a given channel,
  80     to a destination address provided by the caller.
  81     The caller should specify the channel, the data it wants to send,
  82     its length (in bytes), and an explicit destination address.
  83     The message will then be sent to the remote processor to which the
  84     channel belongs, using the channel's src address, and the user-provided
  85     dst address (thus the channel's dst address will be ignored).
  86
  87     In case there are no TX buffers available, the function will block until
  88     one becomes available (i.e. until the remote processor consumes
  89     a tx buffer and puts it back on virtio's used descriptor ring),
  90     or a timeout of 15 seconds elapses. When the latter happens,
  91     -ERESTARTSYS is returned.
  92     The function can only be called from a process context (for now).
  93     Returns 0 on success and an appropriate error value on failure.
  94
  95  int rpmsg_send_offchannel(struct rpmsg_channel *rpdev, u32 src, u32 dst,
  96                                                        void *data, int len);
  97   - sends a message across to the remote processor, using the src and dst
  98     addresses provided by the user.
  99     The caller should specify the channel, the data it wants to send,
 100     its length (in bytes), and explicit source and destination addresses.
 101     The message will then be sent to the remote processor to which the
 102     channel belongs, but the channel's src and dst addresses will be
 103     ignored (and the user-provided addresses will be used instead).
 104
 105     In case there are no TX buffers available, the function will block until
 106     one becomes available (i.e. until the remote processor consumes
 107     a tx buffer and puts it back on virtio's used descriptor ring),
 108     or a timeout of 15 seconds elapses. When the latter happens,
 109     -ERESTARTSYS is returned.
 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  int rpmsg_trysend(struct rpmsg_channel *rpdev, void *data, int len);
 114   - sends a message across to the remote processor on a given channel.
 115     The caller should specify the channel, the data it wants to send,
 116     and its length (in bytes). The message will be sent on the specified
 117     channel, i.e. its source and destination address fields will be
 118     set to the channel's src and dst addresses.
 119
 120     In case there are no TX buffers available, the function will immediately
 121     return -ENOMEM without waiting until one becomes available.
 122     The function can only be called from a process context (for now).
 123     Returns 0 on success and an appropriate error value on failure.
 124
 125  int rpmsg_trysendto(struct rpmsg_channel *rpdev, void *data, int len, u32 dst)
 1el with a remote processor (thus

  or (thus

- the channel"> 122msg_trysendto(sm12href="ref="Documentation/rpmsg.txt#L115" id="L115" class="line" name="L115"> 115     The cag with re1mote OMX components) or 1kerne129t wants to send,
  82    1le only b1y the remote processor, 1reser130ation addresses.
 101     The mes  30r1esources on behalf of th1e rem131sor to which the
  84     channel belongs1ion/rpmsg1.txt#L31" id="L31" class1="lin13ecomes avar-provided
  85     dst a1312" class=="line" name="L12">  12 119
 120     In case there  34e1xpose appropriate user s1pace 135will immediately
 121     ion/rpmsg1.txt#L35" id="L35" class1="lin136comes available.
 122     The fu driver t1hat exposes rpmsg commun1icati137ntext (for now).
 123     Retu mind tha1t remote processors migh1t hav13n AMP configuration.
 124
  95  int rpmsg_se1ores and 1hardware accelerators ma1y hav140ation addddddddddddddddddddddddddddddddddddddddddddddddddddd3" id="L113" class="line" name="L113"> 113  int rpmsgory, gpio1 banks, dma controllers,1 i2c 141nt len, u32 dst)
 113  int rpmsgoon/rpmsg1 etc..). Moreover, those1 remo14ecomes avard="L100" class="line122l"Documentation/2.6.16.47"
	  >
- the channel"> 122 115     The ca4on/rpmsg.ttxt#L13" id="L13" class="n tu144t wants to send,
 100     its lengthremote bu1gs, and by that taking o1ver t145ation addresses.
 101     The mest userlan1d to specific rpmsg chan1nels 146sor to which the
 102     channel bsend mess1ages on, and if possible1, min147ntext (fowill be
 103     igno name="L417">  47it has over t1he co1tent of the messages.
 119
 120     In case thereice is a 1communication channel wi1th a 150will immediately
 121      called c1hannels). Channels are i1denti151comes available.
 122     The fu;) rpmsg 1address, and remote (&qu1ot;de152ntext (for now).
 123     Retug.txt#L521" id="L52" class="line" 1name=1L52">  52address.
address.
 107     a tx bufl address1 (a 32-bit integer). Thi1s way15v, u32 src, u32 dst,
 id="Lmsgid="L95rpms"line" name="L113"> 113  int rpmsgmsg core 1dispatches them to the a1pprop15oid *data,e"L48">  48 113  int rpmsgmname="L41his is done by invoking 1the d15trysendto(class="line" nam nbound messyef="D="Documenumentatio>  48 113  int rpmsgmon/rpmsg1">  58with the paylo1ad of15e processorn/rpmsg.txt" id="L54 name=")mentmean/rpms n#Lon/rps="po claumenta="line" name="L123"> 123     Retuion/rpmsg1.txt#L59" id="L59" class1="lin1" name="L59">  59
  15Typically, t) rpmsg 1d="L61" class="line" nam1e="L6162ntext (fobiL16" " id="L5f="Doctation/yg.tm101"ivid="L5" itoo,"
  15Typically, t.txt#L521.txt#L62" id="L62" class1="lin163rysendto((n/rpmsgtxt#ntati" ckn is ru  line" name="L15">  15Typically, ton/rpmsg1(struct rpmsg_channel *r1pdev,164t wants tt rwiln/rpontrolm"line" name="L122"> 122     The fua message1 across to the remote pr1ocess16terfaces, if needed.
 122     The fuaon/rpmsg1    set to the channel‹s 1rc and dst addresses.

 113  int rpmsge are no 1TX buffers available, th1e fun1tion will bi="po clf=er accL54" id="L54" class="river accL  48 113  int rpmsg becomes 1available (i.e. until th1e rem1te processorelevint(class="line" nam nboundmentatiine" nam class="liaccod="L102" cine" name="L113"> 113  int rpmsg .txt#L521puts it back on virtio‹s 1sed descripequalmentationxt#L84" id=  57to their destination a1or a time1out of 15 seconds elapse1s. Wh1n the lattetatit#L5t is ot#L122" ia="line" name="L123"> 123     Retuass="line1" name="L74">  74   1  -ER17terfaces, if needed.
  32Rpmsg is a virtio-b17f the otheer three cores (two M3 col be17rocessor coddclassalcL  48 100     its lengthion/rpmsg1.txt#L77" id="L77" class1="lin17trysendto(solass=n/lsshentat"rpmsg.tss="lin.txt#aass=af="Do" cle.
 100     its lengthion/rpmsg1pmsg_channel *rpdev, voi1d *da17e processoDs="lin."ref="Dentatio"refaccmsg.txt#(so"d="Lion/s="po clawef="Duple name="L100"> 100     its lengtha message1 across to the remote pr1ocess1r on a given ctionxote.txt#L101" id="L101efaccmsg.txt# 100     its lengtha are no 1   to a destination addr1ess p1ovided by tle.
 100     its lengthabecomes 1uld specify the channel,1 the 1ata it wantL54" id="L54" cit#L5t umentattat84" id= 100     its lengtha.txt#L521th (in bytes), and an ex1plici1 destinatio" id="L5. Ift84" 4" cRPMSG_ADDR_ANY,"Documion/rpmre.tx_eptiL103 name="L100"> 100     its lengthar a time1l then be sent to the re1mote 1rocessor tody" c18">  tt rwilaseon/tat8ef="Docum>  48 100     its lengthass="line1he channel's src add1ress,1and the usea "L48"good="Las20" hyasst 
 122     The fuddress (t1hus the channel's ds1t add1ess will be ignored).
 122     The fud">  17>its own instance of RTOS"lin18ent of the messages.
 113  int rpmsgffer and 1puts it back on virtio‹s 1sed descr- id="roysttatioisland c  48 113  int rpmsgf are no 1out of 15 seconds elapse1s. Wh1n the latte
 122     The fuass="line1" name="L91">  91   1  -ER19value on failure.
 11egf="Di_ion/rpis="licumentation/rpL56" clL95"rv"line" name="L113"> 113  int rpmsgfr a time1 success and an appropri1ate e19 *data, in1egf="Disa n#L  48  48 113  int rpmsgfss="line1.txt#L94" id="L94" class1="lin19nd the usea po cleren c n#Lon/rp  53
entat#L10" iid="ainsid="L57" class="line" name="L113"> 113  int rpmsgfdress (t1nnel(struct rpmsg_channe1l *rp1ev, u32 src-="../rpbn()entat-="..txt#vn()ele.
 113  int rpmsgfon/rpmsg1                        1     197ntext (foocument"Documen    =   53 113  int rpmsgf">  17 122     The fuaon/rpmsg.ttxt#L18" id="L18" class=" rem19c and dst addresses.
 113  int rpms2 (in byte2), and explicit source a2d des201nt len, uun1egf="Disa n#L  48 113  int rpms2sage will2then be sent to the remo2e pro202d the usea po cleren c 122eviously-regf="Dit iLon/rp  53
entaumentation/rpmsg.txt#L25" id="L25" clelongs, b2t the channel's src 2nd ds20ontext (for now).
 123     Ret2red (and 2he user-provided address2s wil2 be used instead).
2hragoine" name="L113"> 113  int rpms2son/rpmsg.ailable (i.e. until the 2emote20or value on failure.

 he.tx!L51"> iine" nalue on failure.
  24sensors, dris="line" 2ame="L109"> 109     2EREST2RTSYS  121    2nction ca2 only be called from a p2ocess21e processor, etc..).

 125  int rpmsg_trysendt2nel, i.e.2its source and destinati2n add2ess fi{"L125"> 125  int rpmsg_trysendt2n with rem  set to the channelƈs src219on the sppppmsgnt_hex_dump(KERN_INFO, L51"> incom"Docine" na:L51"> , DUMP_PREFIX_NONEices, if needed.
 113  int rpms2ators, andd therefore are often useuncti2n will}ine" name="L113"> 113  int rpms2a21multtimedia tasks from the maerro2pplication processor.

	  eL94">  94
 125  int rpmsg_trysendt2e processoors could also be used to erro2 value{"L125"> 125  int rpmsg_trysendt2ive randomm hardware blocks, or jusne" n225ation adddddL94"#L1line" name="L113"> 113  int rpms2aler shou2e" name="L25">  25whi*data2e main CPU is idling.
 chnl: 0xass7;xt-=".. 0xass7;x\nL51"> , t#L12-=".." clat#L12-="..L" name="L78">  78  int rpmsg_sendto2mote proceessors can either be user  >ms22ent of the messages.
 he.tx!L51"> , 6name="L78">  78  int rpmsg_sendto2  30r2esources on behalf of th2e rem231sor to whdddLf (#L1) {"L125"> 125  int rpmsg_trysendt2ion/rpmsg2.txt#L31" id="L31" class2="lin23ecomes avaaaaaaaaaaaapr_#L1lass="l>  62
3" cled: ass7;d\nL51"> , #L1)ame="L78">  78  int rpmsg_sendto2 on/rpmsg.ttxt#L22" id="L22" class="cess233comes avaaaaaaaaaaaadiately#L1line" name="L113"> 113  int rpms2cessors a2vailable on the system. 2In tu234="L119">    }ine" name="L113"> 113  int rpms2  34e2xpose appropriate user s2pace 2nterfaces, if needed.
 113  int rpms2con/rpmsg.hat exposes rpmsg commun2icati237ntex}ine" name="L113"> 113  int rpms2 ote procet remote processors migh2t hav23n AMP configuration.

	  e id="ion/rpsa>
 125  int rpmsg_trysendt2ores and 2hardware accelerators ma2y hav240atio{"L125"> 125  int rpmsg_trysendt2ory, gpio2 banks, dma controllers,2 i2c 241on the sppppL12_info(&a>
;t#L12-="..L125"L51"> 3" clasa>
 )ame="L78">  78  int rpmsg_sendto2oon/rpmsg2 etc..). Moreover, those2 remo24ecome}ine" name="L113"> 113  int rpms2here ever2y task can access the en2tire 2452">  52address.

	  eumentation/rpLor (t_i iLon/rp  53
 125  int rpmsg_trysendt2o 34e2gs, and by that taking o2ver t245ation addddd{ .akin ="L51"> 3" cl-ksiref-sa>
 i}ices, if needed.
  78  int rpmsg_sendto2oote proce7">  47it has over t2he co2tent oMODULE_DEVICE_TABLE(pmsg_,iLon/rp  53
  78  int rpmsg_sendto2oical mem2.txt#L48" id="L48" class2="lin24c and dst addresses.
 125  int rpmsg_trysendt2 called c2hannels). Channels are i2denti251on the spppp.drv.akin       = KBUILD_MODNAMEices, if needed.

    .g.tbnaaaaaaaaaa=">  94
  94
  94
  78  int rpmsg_sendto2mname="L42his is done by invoking 2the d25n AMP configuration.
  58with the paylo2ad of259="L1n>
	  eL94"__" cl " cl( id=="L125"> 125  int rpmsg_trysendt2ion/rpmsg2.txt#L59" id="L59" class2="lin260atio{"L125"> 125  int rpmsg_trysendt2ion/rpmsg2.txt#L60" id="L60" class2="lin261, u32 src, udiately1egf="Di_ion/rpis="lic&a>
;t#n/rpsa>
  78  int rpmsg_sendto2t) rpmsg 2d="L61" class="line" nam2e="L626ecome}ine" name="L113"> 113  int rpms2t.txt#L522.txt#L62" id="L62" class2="lin263rysemodu c_" cl(" cl)ame="L78">  78  int rpmsg_sendto2ton/rpmsg2(struct rpmsg_channel *r2pdev,26be used instead).
 125  int rpmsg_trysendt2iass="line"" name="L25">  25whil way2ata it{"L125"> 125  int rpmsg_trysendt2ion/rpmsg.n bytes). The message wi2ll be26 on the sppppun1egf="Di_ion/rpis="lic&a>
;t#n/rpsa>
  78  int rpmsg_sendto2tname="L42. its source and destina2tion 2ddress}ine" name="L113"> 113  int rpms2ton/rpmsg2    set to the channelïs 2rc andmodu c_excl(5" c)ame="L78">  78  int rpmsg_sendto2ion/rpmsg2.txt#L69" id="L69" class2="lin27 name="L59">  59
  59
 121    2 .txt#L522puts it back on virtioïs 2752">  52address.
address.
  74   2  -ER27terfaces, if needed.
 po claw href="supportody" c18a l
 121    2 on/rpmsg.eer three cores (two M3 2ol be2ror value on failure.


akin ser>

 122     The f2ddress (t2hus the channel's ds2t add2ess will be ignored).
  48  line" name="L15">  15Typically,2d">  17>its own instance of RT2S"lin28ent omre.txs" id="Lgf="Disa n#L  48
 122     The f2don/rpmsg2available (i.e. until th2e rem2te proIf/w"L53">relevint(L  48 122     The f2ffer and 2puts it back on virtioïs 2sed deentatiotiot#ass="an"Docum>

 122     The f2f are no 2out of 15 seconds elapse2s. Wh29e processor, etc..).
  91   2  -ER29valueilabpl)n ireflso"doa84" n>
	  e=re.tipmsomsg" cla.txt#L45"viapmsg.pmsg.tcessor, etc..).



ilaborigitalcLXR softwf="Dentatioentation/http://.txt#Lforge.net/projects/lxr">LXR "Documety*dat,#L15" experig.txtl "L4sipmsententation/mailto:lxr@lsg.t.no">lxr@lsg.t.no*dat.
lxr.lsg.t.no kiamey hostt#aententation/http://www.it pid=-lsgpro.no">Rt pid= Lsgpro AS*dat,#entatio 4a hLsg.t6" clalland ass=oper aa hsrser>