022cfd1b2c1cbbd410289163e1ab437b6cc0993e
[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
45 #define RPMSG_LOCATE_DATA(p)  ((unsigned char *) p + sizeof (struct rpmsg_hdr))
47 /**
48  * struct rpmsg_hdr - common header for all rpmsg messages
49  * @src: source address
50  * @dst: destination address
51  * @reserved: reserved for future use
52  * @len: length of payload (in bytes)
53  * @flags: message flags
54  *
55  * Every message sent(/received) on the rpmsg bus begins with this header.
56  */
57 OPENAMP_PACKED_BEGIN
58 struct rpmsg_hdr {
59         uint32_t src;
60         uint32_t dst;
61         uint32_t reserved;
62         uint16_t len;
63         uint16_t flags;
64 } OPENAMP_PACKED_END;
66 /**
67  * struct rpmsg_ns_msg - dynamic name service announcement message
68  * @name: name of remote service that is published
69  * @addr: address of remote service that is published
70  * @flags: indicates whether service is created or destroyed
71  *
72  * This message is sent across to publish a new service, or announce
73  * about its removal. When we receive these messages, an appropriate
74  * rpmsg channel (i.e device) is created/destroyed. In turn, the ->probe()
75  * or ->remove() handler of the appropriate rpmsg driver will be invoked
76  * (if/as-soon-as one is registered).
77  */
78 OPENAMP_PACKED_BEGIN
79 struct rpmsg_ns_msg {
80         char name[RPMSG_NAME_SIZE];
81         uint32_t addr;
82         uint32_t flags;
83 } OPENAMP_PACKED_END;
85 /**
86  * enum rpmsg_ns_flags - dynamic name service announcement flags
87  *
88  * @RPMSG_NS_CREATE: a new remote service was just created
89  * @RPMSG_NS_DESTROY: a known remote service was just destroyed
90  */
91 enum rpmsg_ns_flags {
92         RPMSG_NS_CREATE = 0,
93         RPMSG_NS_DESTROY = 1,
94 };
96 #define RPMSG_ADDR_ANY          0xFFFFFFFF
98 /**
99  * rpmsg_channel - devices that belong to the rpmsg bus are called channels
100  * @name: channel name
101  * @src: local address
102  * @dst: destination address
103  * rdev: rpmsg remote device
104  * @ept: the rpmsg endpoint of this channel
105  * @state: channel state
106  */
107 struct rpmsg_channel {
108         char name[RPMSG_NAME_SIZE];
109         uint32_t src;
110         uint32_t dst;
111         struct remote_device *rdev;
112         struct rpmsg_endpoint *rp_ept;
113         unsigned int state;
114         struct metal_list node;
115 };
117 /**
118  * channel_info - channel info
119  * @name: channel name
120  * @src: local address
121  * @dst: destination address
122  */
124 struct channel_info {
125         char name[RPMSG_NAME_SIZE];
126         uint32_t src;
127         uint32_t dest;
128 };
130 /**
131  * struct rpmsg_endpoint - binds a local rpmsg address to its user
132  * @rp_chnl: rpmsg channel device
133  * @cb: rx callback handler
134  * @addr: local rpmsg address
135  * @priv: private data for the driver's use
136  *
137  * In essence, an rpmsg endpoint represents a listener on the rpmsg bus, as
138  * it binds an rpmsg address with an rx callback handler.
139  *
140  * Simple rpmsg drivers shouldn't use this struct directly, because
141  * things just work: every rpmsg driver provides an rx callback upon
142  * registering to the bus, and that callback is then bound to its rpmsg
143  * address when the driver is probed. When relevant inbound messages arrive
144  * (i.e. messages which their dst address equals to the src address of
145  * the rpmsg channel), the driver's handler is invoked to process it.
146  *
147  * More complicated drivers though, that do need to allocate additional rpmsg
148  * addresses, and bind them to different rx callbacks, must explicitly
149  * create additional endpoints by themselves (see rpmsg_create_ept()).
150  */
151 struct rpmsg_endpoint {
152         struct rpmsg_channel *rp_chnl;
153         rpmsg_rx_cb_t cb;
154         uint32_t addr;
155         void *priv;
156         struct metal_list node;
157 };
159 struct rpmsg_endpoint *rpmsg_create_ept(struct rpmsg_channel *rp_chnl,
160                                         rpmsg_rx_cb_t cb, void *priv,
161                                         uint32_t addr);
163 void rpmsg_destroy_ept(struct rpmsg_endpoint *rp_ept);
165 int
166 rpmsg_send_offchannel_raw(struct rpmsg_channel *, uint32_t, uint32_t,
167                           char *, int, int);
169 /**
170  * rpmsg_send() - send a message across to the remote processor
171  * @rpdev: the rpmsg channel
172  * @data: payload of message
173  * @len: length of payload
174  *
175  * This function sends @data of length @len on the @rpdev channel.
176  * The message will be sent to the remote processor which the @rpdev
177  * channel belongs to, using @rpdev's source and destination addresses.
178  * In case there are no TX buffers available, the function will block until
179  * one becomes available, or a timeout of 15 seconds elapses. When the latter
180  * happens, -ERESTARTSYS is returned.
181  *
182  * Can only be called from process context (for now).
183  *
184  * Returns 0 on success and an appropriate error value on failure.
185  */
186 static inline int rpmsg_send(struct rpmsg_channel *rpdev, void *data, int len)
188         return rpmsg_send_offchannel_raw(rpdev, rpdev->src, rpdev->dst,
189                                          (char *)data, len, RPMSG_TRUE);
192 /**
193  * rpmsg_sendto() - send a message across to the remote processor, specify dst
194  * @rpdev: the rpmsg channel
195  * @data: payload of message
196  * @len: length of payload
197  * @dst: destination address
198  *
199  * This function sends @data of length @len to the remote @dst address.
200  * The message will be sent to the remote processor which the @rpdev
201  * channel belongs to, using @rpdev's source address.
202  * In case there are no TX buffers available, the function will block until
203  * one becomes available, or a timeout of 15 seconds elapses. When the latter
204  * happens, -ERESTARTSYS is returned.
205  *
206  * Can only be called from process context (for now).
207  *
208  * Returns 0 on success and an appropriate error value on failure.
209  */
210 static inline int rpmsg_sendto(struct rpmsg_channel *rpdev, void *data,
211                                int len, uint32_t dst)
213         return rpmsg_send_offchannel_raw(rpdev, rpdev->src, dst, (char *)data,
214                                          len, RPMSG_TRUE);
217 /**
218  * rpmsg_send_offchannel() - send a message using explicit src/dst addresses
219  * @rpdev: the rpmsg channel
220  * @src: source address
221  * @dst: destination address
222  * @data: payload of message
223  * @len: length of payload
224  *
225  * This function sends @data of length @len to the remote @dst address,
226  * and uses @src as the source address.
227  * The message will be sent to the remote processor which the @rpdev
228  * channel belongs to.
229  * In case there are no TX buffers available, the function will block until
230  * one becomes available, or a timeout of 15 seconds elapses. When the latter
231  * happens, -ERESTARTSYS is returned.
232  *
233  * Can only be called from process context (for now).
234  *
235  * Returns 0 on success and an appropriate error value on failure.
236  */
237 static inline int rpmsg_send_offchannel(struct rpmsg_channel *rpdev,
238                                         uint32_t src, uint32_t dst,
239                                         void *data, int len)
241         return rpmsg_send_offchannel_raw(rpdev, src, dst, (char *)data, len,
242                                          RPMSG_TRUE);
245 /**
246  * rpmsg_trysend() - send a message across to the remote processor
247  * @rpdev: the rpmsg channel
248  * @data: payload of message
249  * @len: length of payload
250  *
251  * This function sends @data of length @len on the @rpdev channel.
252  * The message will be sent to the remote processor which the @rpdev
253  * channel belongs to, using @rpdev's source and destination addresses.
254  * In case there are no TX buffers available, the function will immediately
255  * return -ENOMEM without waiting until one becomes available.
256  *
257  * Can only be called from process context (for now).
258  *
259  * Returns 0 on success and an appropriate error value on failure.
260  */
261 static inline int rpmsg_trysend(struct rpmsg_channel *rpdev, void *data,
262                                 int len)
264         return rpmsg_send_offchannel_raw(rpdev, rpdev->src, rpdev->dst,
265                                          (char *)data, len, RPMSG_FALSE);
268 /**
269  * rpmsg_trysendto() - send a message across to the remote processor, specify dst
270  * @rpdev: the rpmsg channel
271  * @data: payload of message
272  * @len: length of payload
273  * @dst: destination address
274  *
275  * This function sends @data of length @len to the remote @dst address.
276  * The message will be sent to the remote processor which the @rpdev
277  * channel belongs to, using @rpdev's source address.
278  * In case there are no TX buffers available, the function will immediately
279  * return -ENOMEM without waiting until one becomes available.
280  *
281  * Can only be called from process context (for now).
282  *
283  * Returns 0 on success and an appropriate error value on failure.
284  */
285 static inline int rpmsg_trysendto(struct rpmsg_channel *rpdev, void *data,
286                                   int len, uint32_t dst)
288         return rpmsg_send_offchannel_raw(rpdev, rpdev->src, dst, (char *)data, len,
289                                          RPMSG_FALSE);
292 /**
293  * rpmsg_trysend_offchannel() - send a message using explicit src/dst addresses
294  * @rpdev: the rpmsg channel
295  * @src: source address
296  * @dst: destination address
297  * @data: payload of message
298  * @len: length of payload
299  *
300  * This function sends @data of length @len to the remote @dst address,
301  * and uses @src as the source address.
302  * The message will be sent to the remote processor which the @rpdev
303  * channel belongs to.
304  * In case there are no TX buffers available, the function will immediately
305  * return -ENOMEM without waiting until one becomes available.
306  *
307  * Can only be called from process context (for now).
308  *
309  * Returns 0 on success and an appropriate error value on failure.
310  */
311 static inline int rpmsg_trysend_offchannel(struct rpmsg_channel *rpdev,
312                                            uint32_t src, uint32_t dst,
313                                            void *data, int len)
315         return rpmsg_send_offchannel_raw(rpdev, src, dst, (char *)data, len,
316                                          RPMSG_FALSE);
319 /**
320  * rpmsg_init
321  *
322  * Thus function allocates and initializes the rpmsg driver resources for
323  * the given hil_proc.The successful return from this function leaves
324  * fully enabled IPC link.
325  *
326  * @param proc              - pointer to hil_proc
327  * @param rdev              - pointer to newly created remote device
328  * @param channel_created   - callback function for channel creation
329  * @param channel_destroyed - callback function for channel deletion
330  * @default_cb              - default callback for channel
331  * @param role              - role of the other device, Master or Remote
332  * @return - status of function execution
333  *
334  */
336 int rpmsg_init(struct hil_proc *proc,
337                struct remote_device **rdev,
338                rpmsg_chnl_cb_t channel_created,
339                rpmsg_chnl_cb_t channel_destroyed,
340                rpmsg_rx_cb_t default_cb, int role);
342 /**
343  * rpmsg_deinit
344  *
345  * Thus function releases the rpmsg driver resources for given remote
346  * instance.
347  *
348  * @param rdev  -  pointer to device de-init
349  *
350  * @return - none
351  *
352  */
353 void rpmsg_deinit(struct remote_device *rdev);
355 /**
356  * rpmsg_get_buffer_size
357  *
358  * Returns buffer size available for sending messages.
359  *
360  * @param channel - pointer to rpmsg channel/device
361  *
362  * @return - buffer size
363  *
364  */
365 int rpmsg_get_buffer_size(struct rpmsg_channel *rp_chnl);
367 /**
368  * rpmsg_create_channel
369  *
370  * Creates RPMSG channel with the given name for remote device.
371  *
372  * @param rdev - pointer to rpmsg remote device
373  * @param name - channel name
374  *
375  * @return - pointer to new rpmsg channel
376  *
377  */
378 struct rpmsg_channel *rpmsg_create_channel(struct remote_device *rdev,
379                                            char *name);
381 /**
382  * rpmsg_delete_channel
383  *
384  * Deletes the given RPMSG channel. The channel must first be created with the
385  * rpmsg_create_channel API.
386  *
387  * @param rp_chnl - pointer to rpmsg channel to delete
388  *
389  */
390 void rpmsg_delete_channel(struct rpmsg_channel *rp_chnl);
392 #endif                          /* _RPMSG_H_ */