1 /*
2 * Remote processor messaging
3 *
4 * Copyright (C) 2011 Texas Instruments, Inc.
5 * Copyright (C) 2011 Google, Inc.
6 * All rights reserved.
7 *
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions
10 * are met:
11 *
12 * * Redistributions of source code must retain the above copyright
13 * notice, this list of conditions and the following disclaimer.
14 * * Redistributions in binary form must reproduce the above copyright
15 * notice, this list of conditions and the following disclaimer in
16 * the documentation and/or other materials provided with the
17 * distribution.
18 * * Neither the name Texas Instruments nor the names of its
19 * contributors may be used to endorse or promote products derived
20 * from this software without specific prior written permission.
21 *
22 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
23 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
24 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
25 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
26 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
27 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
28 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
29 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
30 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
31 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
32 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33 */
35 #ifndef _RPMSG_H_
36 #define _RPMSG_H_
38 #include "openamp/rpmsg_core.h"
40 /* The feature bitmap for virtio rpmsg */
41 #define VIRTIO_RPMSG_F_NS 0 /* RP supports name service notifications */
42 #define RPMSG_NAME_SIZE 32
44 /**
45 * struct rpmsg_hdr - common header for all rpmsg messages
46 * @src: source address
47 * @dst: destination address
48 * @reserved: reserved for future use
49 * @len: length of payload (in bytes)
50 * @flags: message flags
51 * @data: @len bytes of message payload data
52 *
53 * Every message sent(/received) on the rpmsg bus begins with this header.
54 */
55 OPENAMP_PACKED_BEGIN
56 struct rpmsg_hdr {
57 unsigned long src;
58 unsigned long dst;
59 unsigned long reserved;
60 unsigned short len;
61 unsigned short flags;
62 unsigned char data[0];
63 } OPENAMP_PACKED_END;
65 /**
66 * struct rpmsg_ns_msg - dynamic name service announcement message
67 * @name: name of remote service that is published
68 * @addr: address of remote service that is published
69 * @flags: indicates whether service is created or destroyed
70 *
71 * This message is sent across to publish a new service, or announce
72 * about its removal. When we receive these messages, an appropriate
73 * rpmsg channel (i.e device) is created/destroyed. In turn, the ->probe()
74 * or ->remove() handler of the appropriate rpmsg driver will be invoked
75 * (if/as-soon-as one is registered).
76 */
77 OPENAMP_PACKED_BEGIN
78 struct rpmsg_ns_msg {
79 char name[RPMSG_NAME_SIZE];
80 unsigned long addr;
81 unsigned long flags;
82 } OPENAMP_PACKED_END;
84 /**
85 * enum rpmsg_ns_flags - dynamic name service announcement flags
86 *
87 * @RPMSG_NS_CREATE: a new remote service was just created
88 * @RPMSG_NS_DESTROY: a known remote service was just destroyed
89 */
90 enum rpmsg_ns_flags {
91 RPMSG_NS_CREATE = 0,
92 RPMSG_NS_DESTROY = 1,
93 };
95 #define RPMSG_ADDR_ANY 0xFFFFFFFF
97 /**
98 * rpmsg_channel - devices that belong to the rpmsg bus are called channels
99 * @name: channel name
100 * @src: local address
101 * @dst: destination address
102 * rdev: rpmsg remote device
103 * @ept: the rpmsg endpoint of this channel
104 * @state: channel state
105 */
106 struct rpmsg_channel {
107 char name[RPMSG_NAME_SIZE];
108 unsigned long src;
109 unsigned long dst;
110 struct remote_device *rdev;
111 struct rpmsg_endpoint *rp_ept;
112 unsigned int state;
113 };
115 /**
116 * channel_info - channel info
117 * @name: channel name
118 * @src: local address
119 * @dst: destination address
120 */
122 struct channel_info {
123 char name[RPMSG_NAME_SIZE];
124 unsigned long src;
125 unsigned long dest;
126 };
128 /**
129 * struct rpmsg_endpoint - binds a local rpmsg address to its user
130 * @rp_chnl: rpmsg channel device
131 * @cb: rx callback handler
132 * @addr: local rpmsg address
133 * @priv: private data for the driver's use
134 *
135 * In essence, an rpmsg endpoint represents a listener on the rpmsg bus, as
136 * it binds an rpmsg address with an rx callback handler.
137 *
138 * Simple rpmsg drivers shouldn't use this struct directly, because
139 * things just work: every rpmsg driver provides an rx callback upon
140 * registering to the bus, and that callback is then bound to its rpmsg
141 * address when the driver is probed. When relevant inbound messages arrive
142 * (i.e. messages which their dst address equals to the src address of
143 * the rpmsg channel), the driver's handler is invoked to process it.
144 *
145 * More complicated drivers though, that do need to allocate additional rpmsg
146 * addresses, and bind them to different rx callbacks, must explicitly
147 * create additional endpoints by themselves (see rpmsg_create_ept()).
148 */
149 struct rpmsg_endpoint {
150 struct rpmsg_channel *rp_chnl;
151 rpmsg_rx_cb_t cb;
152 unsigned long addr;
153 void *priv;
154 };
156 struct rpmsg_endpoint *rpmsg_create_ept(struct rpmsg_channel *rp_chnl,
157 rpmsg_rx_cb_t cb, void *priv,
158 unsigned long addr);
160 void rpmsg_destroy_ept(struct rpmsg_endpoint *rp_ept);
162 int
163 rpmsg_send_offchannel_raw(struct rpmsg_channel *, unsigned long, unsigned long,
164 char *, int, int);
166 /**
167 * rpmsg_sendto() - send a message across to the remote processor, specify dst
168 * @rpdev: the rpmsg channel
169 * @data: payload of message
170 * @len: length of payload
171 * @dst: destination address
172 *
173 * This function sends @data of length @len to the remote @dst address.
174 * The message will be sent to the remote processor which the @rpdev
175 * channel belongs to, using @rpdev's source address.
176 * In case there are no TX buffers available, the function will block until
177 * one becomes available, or a timeout of 15 seconds elapses. When the latter
178 * happens, -ERESTARTSYS is returned.
179 *
180 * Can only be called from process context (for now).
181 *
182 * Returns 0 on success and an appropriate error value on failure.
183 */
184 static inline
185 int rpmsg_sendto(struct rpmsg_channel *rpdev, void *data, int len,
186 unsigned long dst)
187 {
188 if (!rpdev || !data)
189 return RPMSG_ERR_PARAM;
191 return rpmsg_send_offchannel_raw(rpdev, rpdev->src, dst, (char *)data,
192 len, RPMSG_TRUE);
193 }
195 /**
196 * rpmsg_send() - send a message across to the remote processor
197 * @rpdev: the rpmsg channel
198 * @data: payload of message
199 * @len: length of payload
200 *
201 * This function sends @data of length @len on the @rpdev channel.
202 * The message will be sent to the remote processor which the @rpdev
203 * channel belongs to, using @rpdev's source and destination addresses.
204 * In case there are no TX buffers available, the function will block until
205 * one becomes available, or a timeout of 15 seconds elapses. When the latter
206 * happens, -ERESTARTSYS is returned.
207 *
208 * Can only be called from process context (for now).
209 *
210 * Returns 0 on success and an appropriate error value on failure.
211 */
212 static inline int rpmsg_send(struct rpmsg_channel *rpdev, void *data, int len)
213 {
214 if (!rpdev || !data)
215 return RPMSG_ERR_PARAM;
217 return rpmsg_send_offchannel_raw(rpdev, rpdev->src, rpdev->dst,
218 (char *)data, len, RPMSG_TRUE);
219 }
221 /**
222 * rpmsg_send_offchannel() - send a message using explicit src/dst addresses
223 * @rpdev: the rpmsg channel
224 * @src: source address
225 * @dst: destination address
226 * @data: payload of message
227 * @len: length of payload
228 *
229 * This function sends @data of length @len to the remote @dst address,
230 * and uses @src as the source address.
231 * The message will be sent to the remote processor which the @rpdev
232 * channel belongs to.
233 * In case there are no TX buffers available, the function will block until
234 * one becomes available, or a timeout of 15 seconds elapses. When the latter
235 * happens, -ERESTARTSYS is returned.
236 *
237 * Can only be called from process context (for now).
238 *
239 * Returns 0 on success and an appropriate error value on failure.
240 */
241 static inline
242 int rpmsg_send_offchannel(struct rpmsg_channel *rpdev, unsigned long src,
243 unsigned long dst, void *data, int len)
244 {
245 if (!rpdev || !data)
246 return RPMSG_ERR_PARAM;
248 return rpmsg_send_offchannel_raw(rpdev, src, dst, (char *)data, len,
249 RPMSG_TRUE);
250 }
252 /**
253 * rpmsg_trysend() - send a message across to the remote processor
254 * @rpdev: the rpmsg channel
255 * @data: payload of message
256 * @len: length of payload
257 *
258 * This function sends @data of length @len on the @rpdev channel.
259 * The message will be sent to the remote processor which the @rpdev
260 * channel belongs to, using @rpdev's source and destination addresses.
261 * In case there are no TX buffers available, the function will immediately
262 * return -ENOMEM without waiting until one becomes available.
263 *
264 * Can only be called from process context (for now).
265 *
266 * Returns 0 on success and an appropriate error value on failure.
267 */
268 static inline
269 int rpmsg_trysend(struct rpmsg_channel *rpdev, void *data, int len)
270 {
272 if (!rpdev || !data)
273 return RPMSG_ERR_PARAM;
275 return rpmsg_send_offchannel_raw(rpdev, rpdev->src, rpdev->dst,
276 (char *)data, len, RPMSG_FALSE);
277 }
279 /**
280 * rpmsg_trysendto() - send a message across to the remote processor, specify dst
281 * @rpdev: the rpmsg channel
282 * @data: payload of message
283 * @len: length of payload
284 * @dst: destination address
285 *
286 * This function sends @data of length @len to the remote @dst address.
287 * The message will be sent to the remote processor which the @rpdev
288 * channel belongs to, using @rpdev's source address.
289 * In case there are no TX buffers available, the function will immediately
290 * return -ENOMEM without waiting until one becomes available.
291 *
292 * Can only be called from process context (for now).
293 *
294 * Returns 0 on success and an appropriate error value on failure.
295 */
296 static inline
297 int rpmsg_trysendto(struct rpmsg_channel *rpdev, void *data, int len,
298 unsigned long dst)
299 {
300 unsigned long src;
302 if (!rpdev || !data)
303 return RPMSG_ERR_PARAM;
305 src = rpdev->src;
307 return rpmsg_send_offchannel_raw(rpdev, src, dst, (char *)data, len,
308 RPMSG_FALSE);
309 }
311 /**
312 * rpmsg_trysend_offchannel() - send a message using explicit src/dst addresses
313 * @rpdev: the rpmsg channel
314 * @src: source address
315 * @dst: destination address
316 * @data: payload of message
317 * @len: length of payload
318 *
319 * This function sends @data of length @len to the remote @dst address,
320 * and uses @src as the source address.
321 * The message will be sent to the remote processor which the @rpdev
322 * channel belongs to.
323 * In case there are no TX buffers available, the function will immediately
324 * return -ENOMEM without waiting until one becomes available.
325 *
326 * Can only be called from process context (for now).
327 *
328 * Returns 0 on success and an appropriate error value on failure.
329 */
330 static inline
331 int rpmsg_trysend_offchannel(struct rpmsg_channel *rpdev, unsigned long src,
332 unsigned long dst, void *data, int len)
333 {
334 if (!rpdev || !data)
335 return RPMSG_ERR_PARAM;
337 return rpmsg_send_offchannel_raw(rpdev, src, dst, (char *)data, len,
338 RPMSG_FALSE);
339 }
341 /**
342 * rpmsg_init
343 *
344 * Thus function allocates and initializes the rpmsg driver resources for given
345 * device id (cpu id).The successful return from this function leaves
346 * fully enabled IPC link.
347 *
348 * @param dev_id - rpmsg remote device for which driver is to
349 * be initialized
350 * @param rdev - pointer to newly created remote device
351 * @param channel_created - callback function for channel creation
352 * @param channel_destroyed - callback function for channel deletion
353 * @default_cb - default callback for channel
354 * @param role - role of the other device, Master or Remote
355 * @return - status of function execution
356 *
357 */
359 int rpmsg_init(int dev_id, struct remote_device **rdev,
360 rpmsg_chnl_cb_t channel_created,
361 rpmsg_chnl_cb_t channel_destroyed,
362 rpmsg_rx_cb_t default_cb, int role);
364 /**
365 * rpmsg_deinit
366 *
367 * Thus function releases the rpmsg driver resources for given remote
368 * instance.
369 *
370 * @param rdev - pointer to device de-init
371 *
372 * @return - none
373 *
374 */
375 void rpmsg_deinit(struct remote_device *rdev);
377 /**
378 * rpmsg_get_buffer_size
379 *
380 * Returns buffer size available for sending messages.
381 *
382 * @param channel - pointer to rpmsg channel/device
383 *
384 * @return - buffer size
385 *
386 */
387 int rpmsg_get_buffer_size(struct rpmsg_channel *rp_chnl);
389 /**
390 * rpmsg_create_channel
391 *
392 * Creates RPMSG channel with the given name for remote device.
393 *
394 * @param rdev - pointer to rpmsg remote device
395 * @param name - channel name
396 *
397 * @return - pointer to new rpmsg channel
398 *
399 */
400 struct rpmsg_channel *rpmsg_create_channel(struct remote_device *rdev,
401 char *name);
403 /**
404 * rpmsg_delete_channel
405 *
406 * Deletes the given RPMSG channel. The channel must first be created with the
407 * rpmsg_create_channel API.
408 *
409 * @param rp_chnl - pointer to rpmsg channel to delete
410 *
411 */
412 void rpmsg_delete_channel(struct rpmsg_channel *rp_chnl);
414 #endif /* _RPMSG_H_ */