1230f6b35b4be5a2daed7a7fe26b8072bdd366d5
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)
187 {
188 return rpmsg_send_offchannel_raw(rpdev, rpdev->src, rpdev->dst,
189 (char *)data, len, RPMSG_TRUE);
190 }
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)
212 {
213 return rpmsg_send_offchannel_raw(rpdev, rpdev->src, dst, (char *)data,
214 len, RPMSG_TRUE);
215 }
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)
240 {
241 return rpmsg_send_offchannel_raw(rpdev, src, dst, (char *)data, len,
242 RPMSG_TRUE);
243 }
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)
263 {
264 return rpmsg_send_offchannel_raw(rpdev, rpdev->src, rpdev->dst,
265 (char *)data, len, RPMSG_FALSE);
266 }
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)
287 {
288 return rpmsg_send_offchannel_raw(rpdev, rpdev->src, dst, (char *)data, len,
289 RPMSG_FALSE);
290 }
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)
314 {
315 return rpmsg_send_offchannel_raw(rpdev, src, dst, (char *)data, len,
316 RPMSG_FALSE);
317 }
319 /**
320 * rpmsg_init
321 *
322 * Thus function allocates and initializes the rpmsg driver resources for given
323 * device id (cpu id).The successful return from this function leaves
324 * fully enabled IPC link.
325 *
326 * @param dev_id - rpmsg remote device for which driver is to
327 * be initialized
328 * @param rdev - pointer to newly created remote device
329 * @param channel_created - callback function for channel creation
330 * @param channel_destroyed - callback function for channel deletion
331 * @default_cb - default callback for channel
332 * @param role - role of the other device, Master or Remote
333 * @return - status of function execution
334 *
335 */
337 int rpmsg_init(int dev_id, 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_ */