Adding RPMsg Extension layer implementing zero-copy send and receive.
[processor-sdk/open-amp.git] / lib / include / openamp / rpmsg.h
1 /*
2  * Remote processor messaging
3  *
4  * Copyright (C) 2011 Texas Instruments, Inc.
5  * Copyright (C) 2011 Google, Inc.
6  * All rights reserved.
7  * Copyright (c) 2016 Freescale Semiconductor, Inc. All rights reserved.
8  *
9  * Redistribution and use in source and binary forms, with or without
10  * modification, are permitted provided that the following conditions
11  * are met:
12  *
13  * * Redistributions of source code must retain the above copyright
14  *   notice, this list of conditions and the following disclaimer.
15  * * Redistributions in binary form must reproduce the above copyright
16  *   notice, this list of conditions and the following disclaimer in
17  *   the documentation and/or other materials provided with the
18  *   distribution.
19  * * Neither the name Texas Instruments nor the names of its
20  *   contributors may be used to endorse or promote products derived
21  *   from this software without specific prior written permission.
22  *
23  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
24  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
25  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
26  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
27  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
28  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
29  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
30  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
31  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
32  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
33  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
34  */
36 #ifndef _RPMSG_H_
37 #define _RPMSG_H_
39 #include "openamp/rpmsg_core.h"
41 /* The feature bitmap for virtio rpmsg */
42 #define VIRTIO_RPMSG_F_NS       0       /* RP supports name service notifications */
43 #define RPMSG_NAME_SIZE     32
44 #define RPMSG_BUF_HELD      (1U << 31) /* Flag to suggest to hold the buffer */
46 #define RPMSG_LOCATE_DATA(p)  ((unsigned char *) p + sizeof (struct rpmsg_hdr))
48 /**
49  * struct rpmsg_hdr - common header for all rpmsg messages
50  * @src: source address
51  * @dst: destination address
52  * @reserved: reserved for future use
53  * @len: length of payload (in bytes)
54  * @flags: message flags
55  *
56  * Every message sent(/received) on the rpmsg bus begins with this header.
57  */
58 OPENAMP_PACKED_BEGIN
59 struct rpmsg_hdr {
60         uint32_t src;
61         uint32_t dst;
62         uint32_t reserved;
63         uint16_t len;
64         uint16_t flags;
65 } OPENAMP_PACKED_END;
67 /**
68  * struct rpmsg_hdr_reserved - this is the "union" of the rpmsg_hdr->reserved
69  * @rfu: reserved for future usage
70  * @idx: index of a buffer (not to be returned back to the buffer's pool)
71  *
72  * This structure has been introduced to keep the backward compatibility. 
73  * It could be integrated into rpmsg_hdr struct, replacing the reserved field.
74  */
75 struct rpmsg_hdr_reserved
76 {
77         uint16_t rfu; /* reserved for future usage */
78         uint16_t idx;
79 };
81 /**
82  * struct rpmsg_ns_msg - dynamic name service announcement message
83  * @name: name of remote service that is published
84  * @addr: address of remote service that is published
85  * @flags: indicates whether service is created or destroyed
86  *
87  * This message is sent across to publish a new service, or announce
88  * about its removal. When we receive these messages, an appropriate
89  * rpmsg channel (i.e device) is created/destroyed. In turn, the ->probe()
90  * or ->remove() handler of the appropriate rpmsg driver will be invoked
91  * (if/as-soon-as one is registered).
92  */
93 OPENAMP_PACKED_BEGIN
94 struct rpmsg_ns_msg {
95         char name[RPMSG_NAME_SIZE];
96         uint32_t addr;
97         uint32_t flags;
98 } OPENAMP_PACKED_END;
100 /**
101  * enum rpmsg_ns_flags - dynamic name service announcement flags
102  *
103  * @RPMSG_NS_CREATE: a new remote service was just created
104  * @RPMSG_NS_DESTROY: a known remote service was just destroyed
105  */
106 enum rpmsg_ns_flags {
107         RPMSG_NS_CREATE = 0,
108         RPMSG_NS_DESTROY = 1,
109 };
111 #define RPMSG_ADDR_ANY          0xFFFFFFFF
113 /**
114  * rpmsg_channel - devices that belong to the rpmsg bus are called channels
115  * @name: channel name
116  * @src: local address
117  * @dst: destination address
118  * rdev: rpmsg remote device
119  * @ept: the rpmsg endpoint of this channel
120  * @state: channel state
121  */
122 struct rpmsg_channel {
123         char name[RPMSG_NAME_SIZE];
124         uint32_t src;
125         uint32_t dst;
126         struct remote_device *rdev;
127         struct rpmsg_endpoint *rp_ept;
128         unsigned int state;
129         struct metal_list node;
130 };
132 /**
133  * channel_info - channel info
134  * @name: channel name
135  * @src: local address
136  * @dst: destination address
137  */
139 struct channel_info {
140         char name[RPMSG_NAME_SIZE];
141         uint32_t src;
142         uint32_t dest;
143 };
145 /**
146  * struct rpmsg_endpoint - binds a local rpmsg address to its user
147  * @rp_chnl: rpmsg channel device
148  * @cb: rx callback handler
149  * @addr: local rpmsg address
150  * @priv: private data for the driver's use
151  *
152  * In essence, an rpmsg endpoint represents a listener on the rpmsg bus, as
153  * it binds an rpmsg address with an rx callback handler.
154  *
155  * Simple rpmsg drivers shouldn't use this struct directly, because
156  * things just work: every rpmsg driver provides an rx callback upon
157  * registering to the bus, and that callback is then bound to its rpmsg
158  * address when the driver is probed. When relevant inbound messages arrive
159  * (i.e. messages which their dst address equals to the src address of
160  * the rpmsg channel), the driver's handler is invoked to process it.
161  *
162  * More complicated drivers though, that do need to allocate additional rpmsg
163  * addresses, and bind them to different rx callbacks, must explicitly
164  * create additional endpoints by themselves (see rpmsg_create_ept()).
165  */
166 struct rpmsg_endpoint {
167         struct rpmsg_channel *rp_chnl;
168         rpmsg_rx_cb_t cb;
169         uint32_t addr;
170         void *priv;
171         struct metal_list node;
172 };
174 struct rpmsg_endpoint *rpmsg_create_ept(struct rpmsg_channel *rp_chnl,
175                                         rpmsg_rx_cb_t cb, void *priv,
176                                         uint32_t addr);
178 void rpmsg_destroy_ept(struct rpmsg_endpoint *rp_ept);
180 int
181 rpmsg_send_offchannel_raw(struct rpmsg_channel *, uint32_t, uint32_t,
182                           char *, int, int);
184 /**
185  * rpmsg_send() - send a message across to the remote processor
186  * @rpdev: the rpmsg channel
187  * @data: payload of message
188  * @len: length of payload
189  *
190  * This function sends @data of length @len on the @rpdev channel.
191  * The message will be sent to the remote processor which the @rpdev
192  * channel belongs to, using @rpdev's source and destination addresses.
193  * In case there are no TX buffers available, the function will block until
194  * one becomes available, or a timeout of 15 seconds elapses. When the latter
195  * happens, -ERESTARTSYS is returned.
196  *
197  * Can only be called from process context (for now).
198  *
199  * Returns 0 on success and an appropriate error value on failure.
200  */
201 static inline int rpmsg_send(struct rpmsg_channel *rpdev, void *data, int len)
203         return rpmsg_send_offchannel_raw(rpdev, rpdev->src, rpdev->dst,
204                                          (char *)data, len, RPMSG_TRUE);
207 /**
208  * rpmsg_sendto() - send a message across to the remote processor, specify dst
209  * @rpdev: the rpmsg channel
210  * @data: payload of message
211  * @len: length of payload
212  * @dst: destination address
213  *
214  * This function sends @data of length @len to the remote @dst address.
215  * The message will be sent to the remote processor which the @rpdev
216  * channel belongs to, using @rpdev's source address.
217  * In case there are no TX buffers available, the function will block until
218  * one becomes available, or a timeout of 15 seconds elapses. When the latter
219  * happens, -ERESTARTSYS is returned.
220  *
221  * Can only be called from process context (for now).
222  *
223  * Returns 0 on success and an appropriate error value on failure.
224  */
225 static inline int rpmsg_sendto(struct rpmsg_channel *rpdev, void *data,
226                                int len, uint32_t dst)
228         return rpmsg_send_offchannel_raw(rpdev, rpdev->src, dst, (char *)data,
229                                          len, RPMSG_TRUE);
232 /**
233  * rpmsg_send_offchannel() - send a message using explicit src/dst addresses
234  * @rpdev: the rpmsg channel
235  * @src: source address
236  * @dst: destination address
237  * @data: payload of message
238  * @len: length of payload
239  *
240  * This function sends @data of length @len to the remote @dst address,
241  * and uses @src as the source address.
242  * The message will be sent to the remote processor which the @rpdev
243  * channel belongs to.
244  * In case there are no TX buffers available, the function will block until
245  * one becomes available, or a timeout of 15 seconds elapses. When the latter
246  * happens, -ERESTARTSYS is returned.
247  *
248  * Can only be called from process context (for now).
249  *
250  * Returns 0 on success and an appropriate error value on failure.
251  */
252 static inline int rpmsg_send_offchannel(struct rpmsg_channel *rpdev,
253                                         uint32_t src, uint32_t dst,
254                                         void *data, int len)
256         return rpmsg_send_offchannel_raw(rpdev, src, dst, (char *)data, len,
257                                          RPMSG_TRUE);
260 /**
261  * rpmsg_trysend() - send a message across to the remote processor
262  * @rpdev: the rpmsg channel
263  * @data: payload of message
264  * @len: length of payload
265  *
266  * This function sends @data of length @len on the @rpdev channel.
267  * The message will be sent to the remote processor which the @rpdev
268  * channel belongs to, using @rpdev's source and destination addresses.
269  * In case there are no TX buffers available, the function will immediately
270  * return -ENOMEM without waiting until one becomes available.
271  *
272  * Can only be called from process context (for now).
273  *
274  * Returns 0 on success and an appropriate error value on failure.
275  */
276 static inline int rpmsg_trysend(struct rpmsg_channel *rpdev, void *data,
277                                 int len)
279         return rpmsg_send_offchannel_raw(rpdev, rpdev->src, rpdev->dst,
280                                          (char *)data, len, RPMSG_FALSE);
283 /**
284  * rpmsg_trysendto() - send a message across to the remote processor, specify dst
285  * @rpdev: the rpmsg channel
286  * @data: payload of message
287  * @len: length of payload
288  * @dst: destination address
289  *
290  * This function sends @data of length @len to the remote @dst address.
291  * The message will be sent to the remote processor which the @rpdev
292  * channel belongs to, using @rpdev's source address.
293  * In case there are no TX buffers available, the function will immediately
294  * return -ENOMEM without waiting until one becomes available.
295  *
296  * Can only be called from process context (for now).
297  *
298  * Returns 0 on success and an appropriate error value on failure.
299  */
300 static inline int rpmsg_trysendto(struct rpmsg_channel *rpdev, void *data,
301                                   int len, uint32_t dst)
303         return rpmsg_send_offchannel_raw(rpdev, rpdev->src, dst, (char *)data, len,
304                                          RPMSG_FALSE);
307 /**
308  * rpmsg_trysend_offchannel() - send a message using explicit src/dst addresses
309  * @rpdev: the rpmsg channel
310  * @src: source address
311  * @dst: destination address
312  * @data: payload of message
313  * @len: length of payload
314  *
315  * This function sends @data of length @len to the remote @dst address,
316  * and uses @src as the source address.
317  * The message will be sent to the remote processor which the @rpdev
318  * channel belongs to.
319  * In case there are no TX buffers available, the function will immediately
320  * return -ENOMEM without waiting until one becomes available.
321  *
322  * Can only be called from process context (for now).
323  *
324  * Returns 0 on success and an appropriate error value on failure.
325  */
326 static inline int rpmsg_trysend_offchannel(struct rpmsg_channel *rpdev,
327                                            uint32_t src, uint32_t dst,
328                                            void *data, int len)
330         return rpmsg_send_offchannel_raw(rpdev, src, dst, (char *)data, len,
331                                          RPMSG_FALSE);
334 /**
335  * @brief Holds the rx buffer for usage outside the receive callback.
336  *
337  * Calling this function prevents the RPMsg receive buffer from being released
338  * back to the pool of shmem buffers. This API can only be called at rx
339  * callback context (rpmsg_rx_cb_t). With this API, the application doesn't
340  * need to copy the message in rx callback. Instead, the rx buffer base address
341  * is saved in application context and further processed in application
342  * process. After the message is processed, the application can release the rx
343  * buffer for future reuse in vring by calling the rpmsg_release_rx_buffer()
344  * function.
345  *
346  * @param[in] rpdev The rpmsg channel
347  * @param[in] rxbuf RX buffer with message payload
348  *
349  * @see rpmsg_release_rx_buffer
350  */
351 void rpmsg_hold_rx_buffer(struct rpmsg_channel *rpdev, void *rxbuf);
353 /**
354  * @brief Releases the rx buffer for future reuse in vring.
355  *
356  * This API can be called at process context when the message in rx buffer is
357  * processed.
358  *
359  * @param rpdev - the rpmsg channel
360  * @param rxbuf - rx buffer with message payload
361  *
362  * @see rpmsg_hold_rx_buffer
363  */
364 void rpmsg_release_rx_buffer(struct rpmsg_channel *rpdev, void *rxbuf);
366 /**
367  * @brief Gets the tx buffer for message payload.
368  *
369  * This API can only be called at process context to get the tx buffer in vring.
370  * By this way, the application can directly put its message into the vring tx
371  * buffer without copy from an application buffer.
372  * It is the application responsibility to correctly fill the allocated tx
373  * buffer by data and passing correct parameters to the rpmsg_send_nocopy() or
374  * rpmsg_sendto_nocopy() function to perform data no-copy-send mechanism.
375  *
376  * @param[in] rpdev Pointer to rpmsg channel
377  * @param[in] size  Pointer to store tx buffer size
378  * @param[in] wait  Boolean, wait or not for buffer to become available
379  *
380  * @return The tx buffer address on success and NULL on failure
381  *
382  * @see rpmsg_send_offchannel_nocopy
383  * @see rpmsg_sendto_nocopy
384  * @see rpmsg_send_nocopy
385  */
386 void *rpmsg_get_tx_payload_buffer(struct rpmsg_channel *rpdev, uint32_t *size,
387                             int wait);
389 /**
390  * @brief Sends a message in tx buffer allocated by rpmsg_alloc_tx_buffer()
391  * using explicit src/dst addresses.
392  *
393  * This function sends txbuf of length len to the remote dst address,
394  * and uses src as the source address.
395  * The message will be sent to the remote processor which the rpdev
396  * channel belongs to.
397  * The application has to take the responsibility for:
398  *  1. tx buffer allocation (rpmsg_alloc_tx_buffer() )
399  *  2. filling the data to be sent into the pre-allocated tx buffer
400  *  3. not exceeding the buffer size when filling the data
401  *  4. data cache coherency
402  *
403  * After the rpmsg_send_offchannel_nocopy() function is issued the tx buffer is
404  * no more owned by the sending task and must not be touched anymore unless the
405  * rpmsg_send_offchannel_nocopy() function fails and returns an error. In that
406  * case the application should try to re-issue the
407  * rpmsg_send_offchannel_nocopy() again and if it is still not possible to send
408  * the message and the application wants to give it up from whatever reasons
409  * the rpmsg_release_rx_buffer function could be called, passing the pointer to
410  * the tx buffer to be released as a parameter.
411  *
412  * @param[in] rpdev The rpmsg channel
413  * @param[in] src   Source address
414  * @param[in] dst   Destination address
415  * @param[in] txbuf TX buffer with message filled
416  * @param[in] len   Length of payload
417  *
418  * @return 0 on success and an appropriate error value on failure
419  *
420  * @see rpmsg_alloc_tx_buffer
421  * @see rpmsg_sendto_nocopy
422  * @see rpmsg_send_nocopy
423  */
424 int rpmsg_send_offchannel_nocopy(struct rpmsg_channel *rpdev, uint32_t src,
425                                  uint32_t dst, void *txbuf, int len);
427 /**
428  * @brief Sends a message in tx buffer allocated by rpmsg_alloc_tx_buffer()
429  * across to the remote processor, specify dst.
430  *
431  * This function sends txbuf of length len to the remote dst address.
432  * The message will be sent to the remote processor which the rpdev
433  * channel belongs to, using rpdev's source address.
434  * The application has to take the responsibility for:
435  *  1. tx buffer allocation (rpmsg_alloc_tx_buffer() )
436  *  2. filling the data to be sent into the pre-allocated tx buffer
437  *  3. not exceeding the buffer size when filling the data
438  *  4. data cache coherency
439  *
440  * After the rpmsg_sendto_nocopy() function is issued the tx buffer is no more
441  * owned by the sending task and must not be touched anymore unless the
442  * rpmsg_sendto_nocopy() function fails and returns an error. In that case the
443  * application should try to re-issue the rpmsg_sendto_nocopy() again and if
444  * it is still not possible to send the message and the application wants to
445  * give it up from whatever reasons the rpmsg_release_rx_buffer function
446  * could be called,
447  * passing the pointer to the tx buffer to be released as a parameter.
448  *
449  * @param[in] rpdev The rpmsg channel
450  * @param[in] txbuf TX buffer with message filled
451  * @param[in] len   Length of payload
452  * @param[in] dst   Destination address
453  *
454  * @return 0 on success and an appropriate error value on failure
455  *
456  * @see rpmsg_alloc_tx_buffer
457  * @see rpmsg_send_offchannel_nocopy
458  * @see rpmsg_send_nocopy
459  */
460 static inline
461 int rpmsg_sendto_nocopy(struct rpmsg_channel *rpdev, void *txbuf, int len,
462                         uint32_t dst)
464         if (!rpdev)
465                 return RPMSG_ERR_PARAM;
467         return rpmsg_send_offchannel_nocopy(rpdev, (uint32_t)rpdev->src, dst,
468                                             txbuf, len);
471 /**
472  * @brief Sends a message in tx buffer allocated by
473  * rpmsg_alloc_tx_buffer() across to the remote processor.
474  *
475  * This function sends txbuf of length len on the rpdev channel.
476  * The message will be sent to the remote processor which the rpdev
477  * channel belongs to, using rpdev's source and destination addresses.
478  * The application has to take the responsibility for:
479  *  1. tx buffer allocation (rpmsg_alloc_tx_buffer() )
480  *  2. filling the data to be sent into the pre-allocated tx buffer
481  *  3. not exceeding the buffer size when filling the data
482  *  4. data cache coherency
483  *
484  * After the rpmsg_send_nocopy() function is issued the tx buffer is no more
485  * owned by the sending task and must not be touched anymore unless the
486  * rpmsg_send_nocopy() function fails and returns an error. In that case the
487  * application should try to re-issue the rpmsg_send_nocopy() again and if
488  * it is still not possible to send the message and the application wants to
489  * give it up from whatever reasons the rpmsg_release_rx_buffer function
490  * could be called, passing the pointer to the tx buffer to be released as a
491  * parameter.
492  *
493  * @param[in] rpdev The rpmsg channel
494  * @param[in] txbuf TX buffer with message filled
495  * @param[in] len   Length of payload
496  *
497  * @return 0 on success and an appropriate error value on failure
498  *
499  * @see rpmsg_alloc_tx_buffer
500  * @see rpmsg_send_offchannel_nocopy
501  * @see rpmsg_sendto_nocopy
502  */
503 static inline
504 int rpmsg_send_nocopy(struct rpmsg_channel *rpdev, void *txbuf, int len)
506         if (!rpdev)
507                 return RPMSG_ERR_PARAM;
509         return rpmsg_send_offchannel_nocopy(rpdev, rpdev->src, rpdev->dst,
510                                             txbuf, len);
513 /**
514  * rpmsg_init
515  *
516  * Thus function allocates and initializes the rpmsg driver resources for
517  * the given hil_proc.The successful return from this function leaves
518  * fully enabled IPC link.
519  *
520  * @param proc              - pointer to hil_proc
521  * @param rdev              - pointer to newly created remote device
522  * @param channel_created   - callback function for channel creation
523  * @param channel_destroyed - callback function for channel deletion
524  * @default_cb              - default callback for channel
525  * @param role              - role of the other device, Master or Remote
526  * @return - status of function execution
527  *
528  */
530 int rpmsg_init(struct hil_proc *proc,
531                struct remote_device **rdev,
532                rpmsg_chnl_cb_t channel_created,
533                rpmsg_chnl_cb_t channel_destroyed,
534                rpmsg_rx_cb_t default_cb, int role);
536 /**
537  * rpmsg_deinit
538  *
539  * Thus function releases the rpmsg driver resources for given remote
540  * instance.
541  *
542  * @param rdev  -  pointer to device de-init
543  *
544  * @return - none
545  *
546  */
547 void rpmsg_deinit(struct remote_device *rdev);
549 /**
550  * rpmsg_get_buffer_size
551  *
552  * Returns buffer size available for sending messages.
553  *
554  * @param channel - pointer to rpmsg channel/device
555  *
556  * @return - buffer size
557  *
558  */
559 int rpmsg_get_buffer_size(struct rpmsg_channel *rp_chnl);
561 /**
562  * rpmsg_create_channel
563  *
564  * Creates RPMSG channel with the given name for remote device.
565  *
566  * @param rdev - pointer to rpmsg remote device
567  * @param name - channel name
568  *
569  * @return - pointer to new rpmsg channel
570  *
571  */
572 struct rpmsg_channel *rpmsg_create_channel(struct remote_device *rdev,
573                                            char *name);
575 /**
576  * rpmsg_delete_channel
577  *
578  * Deletes the given RPMSG channel. The channel must first be created with the
579  * rpmsg_create_channel API.
580  *
581  * @param rp_chnl - pointer to rpmsg channel to delete
582  *
583  */
584 void rpmsg_delete_channel(struct rpmsg_channel *rp_chnl);
586 #endif                          /* _RPMSG_H_ */