Ohad Ben-Cohen | bcabbcc | 2011-10-20 21:10:55 +0200 | [diff] [blame] | 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 | */ |
| 34 | |
| 35 | #ifndef _LINUX_RPMSG_H |
| 36 | #define _LINUX_RPMSG_H |
| 37 | |
| 38 | #include <linux/types.h> |
| 39 | #include <linux/device.h> |
| 40 | #include <linux/mod_devicetable.h> |
Ohad Ben-Cohen | 5a081ca | 2012-06-06 10:09:25 +0300 | [diff] [blame^] | 41 | #include <linux/kref.h> |
Ohad Ben-Cohen | bcabbcc | 2011-10-20 21:10:55 +0200 | [diff] [blame] | 42 | |
| 43 | /* The feature bitmap for virtio rpmsg */ |
| 44 | #define VIRTIO_RPMSG_F_NS 0 /* RP supports name service notifications */ |
| 45 | |
| 46 | /** |
| 47 | * struct rpmsg_hdr - common header for all rpmsg messages |
| 48 | * @src: source address |
| 49 | * @dst: destination address |
| 50 | * @reserved: reserved for future use |
| 51 | * @len: length of payload (in bytes) |
| 52 | * @flags: message flags |
| 53 | * @data: @len bytes of message payload data |
| 54 | * |
| 55 | * Every message sent(/received) on the rpmsg bus begins with this header. |
| 56 | */ |
| 57 | struct rpmsg_hdr { |
| 58 | u32 src; |
| 59 | u32 dst; |
| 60 | u32 reserved; |
| 61 | u16 len; |
| 62 | u16 flags; |
| 63 | u8 data[0]; |
| 64 | } __packed; |
| 65 | |
| 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 | struct rpmsg_ns_msg { |
| 79 | char name[RPMSG_NAME_SIZE]; |
| 80 | u32 addr; |
| 81 | u32 flags; |
| 82 | } __packed; |
| 83 | |
| 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 | }; |
| 94 | |
| 95 | #define RPMSG_ADDR_ANY 0xFFFFFFFF |
| 96 | |
| 97 | struct virtproc_info; |
| 98 | |
| 99 | /** |
| 100 | * rpmsg_channel - devices that belong to the rpmsg bus are called channels |
| 101 | * @vrp: the remote processor this channel belongs to |
| 102 | * @dev: the device struct |
| 103 | * @id: device id (used to match between rpmsg drivers and devices) |
| 104 | * @src: local address |
| 105 | * @dst: destination address |
| 106 | * @ept: the rpmsg endpoint of this channel |
| 107 | * @announce: if set, rpmsg will announce the creation/removal of this channel |
| 108 | */ |
| 109 | struct rpmsg_channel { |
| 110 | struct virtproc_info *vrp; |
| 111 | struct device dev; |
| 112 | struct rpmsg_device_id id; |
| 113 | u32 src; |
| 114 | u32 dst; |
| 115 | struct rpmsg_endpoint *ept; |
| 116 | bool announce; |
| 117 | }; |
| 118 | |
| 119 | typedef void (*rpmsg_rx_cb_t)(struct rpmsg_channel *, void *, int, void *, u32); |
| 120 | |
| 121 | /** |
| 122 | * struct rpmsg_endpoint - binds a local rpmsg address to its user |
| 123 | * @rpdev: rpmsg channel device |
Ohad Ben-Cohen | 5a081ca | 2012-06-06 10:09:25 +0300 | [diff] [blame^] | 124 | * @refcount: when this drops to zero, the ept is deallocated |
Ohad Ben-Cohen | bcabbcc | 2011-10-20 21:10:55 +0200 | [diff] [blame] | 125 | * @cb: rx callback handler |
| 126 | * @addr: local rpmsg address |
| 127 | * @priv: private data for the driver's use |
| 128 | * |
| 129 | * In essence, an rpmsg endpoint represents a listener on the rpmsg bus, as |
| 130 | * it binds an rpmsg address with an rx callback handler. |
| 131 | * |
| 132 | * Simple rpmsg drivers shouldn't use this struct directly, because |
| 133 | * things just work: every rpmsg driver provides an rx callback upon |
| 134 | * registering to the bus, and that callback is then bound to its rpmsg |
| 135 | * address when the driver is probed. When relevant inbound messages arrive |
| 136 | * (i.e. messages which their dst address equals to the src address of |
| 137 | * the rpmsg channel), the driver's handler is invoked to process it. |
| 138 | * |
| 139 | * More complicated drivers though, that do need to allocate additional rpmsg |
| 140 | * addresses, and bind them to different rx callbacks, must explicitly |
| 141 | * create additional endpoints by themselves (see rpmsg_create_ept()). |
| 142 | */ |
| 143 | struct rpmsg_endpoint { |
| 144 | struct rpmsg_channel *rpdev; |
Ohad Ben-Cohen | 5a081ca | 2012-06-06 10:09:25 +0300 | [diff] [blame^] | 145 | struct kref refcount; |
Ohad Ben-Cohen | bcabbcc | 2011-10-20 21:10:55 +0200 | [diff] [blame] | 146 | rpmsg_rx_cb_t cb; |
| 147 | u32 addr; |
| 148 | void *priv; |
| 149 | }; |
| 150 | |
| 151 | /** |
| 152 | * struct rpmsg_driver - rpmsg driver struct |
| 153 | * @drv: underlying device driver |
| 154 | * @id_table: rpmsg ids serviced by this driver |
| 155 | * @probe: invoked when a matching rpmsg channel (i.e. device) is found |
| 156 | * @remove: invoked when the rpmsg channel is removed |
| 157 | * @callback: invoked when an inbound message is received on the channel |
| 158 | */ |
| 159 | struct rpmsg_driver { |
| 160 | struct device_driver drv; |
| 161 | const struct rpmsg_device_id *id_table; |
| 162 | int (*probe)(struct rpmsg_channel *dev); |
| 163 | void (*remove)(struct rpmsg_channel *dev); |
| 164 | void (*callback)(struct rpmsg_channel *, void *, int, void *, u32); |
| 165 | }; |
| 166 | |
| 167 | int register_rpmsg_device(struct rpmsg_channel *dev); |
| 168 | void unregister_rpmsg_device(struct rpmsg_channel *dev); |
| 169 | int register_rpmsg_driver(struct rpmsg_driver *drv); |
| 170 | void unregister_rpmsg_driver(struct rpmsg_driver *drv); |
| 171 | void rpmsg_destroy_ept(struct rpmsg_endpoint *); |
| 172 | struct rpmsg_endpoint *rpmsg_create_ept(struct rpmsg_channel *, |
| 173 | rpmsg_rx_cb_t cb, void *priv, u32 addr); |
| 174 | int |
| 175 | rpmsg_send_offchannel_raw(struct rpmsg_channel *, u32, u32, void *, int, bool); |
| 176 | |
| 177 | /** |
| 178 | * rpmsg_send() - send a message across to the remote processor |
| 179 | * @rpdev: the rpmsg channel |
| 180 | * @data: payload of message |
| 181 | * @len: length of payload |
| 182 | * |
| 183 | * This function sends @data of length @len on the @rpdev channel. |
| 184 | * The message will be sent to the remote processor which the @rpdev |
| 185 | * channel belongs to, using @rpdev's source and destination addresses. |
| 186 | * In case there are no TX buffers available, the function will block until |
| 187 | * one becomes available, or a timeout of 15 seconds elapses. When the latter |
| 188 | * happens, -ERESTARTSYS is returned. |
| 189 | * |
| 190 | * Can only be called from process context (for now). |
| 191 | * |
| 192 | * Returns 0 on success and an appropriate error value on failure. |
| 193 | */ |
| 194 | static inline int rpmsg_send(struct rpmsg_channel *rpdev, void *data, int len) |
| 195 | { |
| 196 | u32 src = rpdev->src, dst = rpdev->dst; |
| 197 | |
| 198 | return rpmsg_send_offchannel_raw(rpdev, src, dst, data, len, true); |
| 199 | } |
| 200 | |
| 201 | /** |
| 202 | * rpmsg_sendto() - send a message across to the remote processor, specify dst |
| 203 | * @rpdev: the rpmsg channel |
| 204 | * @data: payload of message |
| 205 | * @len: length of payload |
| 206 | * @dst: destination address |
| 207 | * |
| 208 | * This function sends @data of length @len to the remote @dst address. |
| 209 | * The message will be sent to the remote processor which the @rpdev |
| 210 | * channel belongs to, using @rpdev's source address. |
| 211 | * In case there are no TX buffers available, the function will block until |
| 212 | * one becomes available, or a timeout of 15 seconds elapses. When the latter |
| 213 | * happens, -ERESTARTSYS is returned. |
| 214 | * |
| 215 | * Can only be called from process context (for now). |
| 216 | * |
| 217 | * Returns 0 on success and an appropriate error value on failure. |
| 218 | */ |
| 219 | static inline |
| 220 | int rpmsg_sendto(struct rpmsg_channel *rpdev, void *data, int len, u32 dst) |
| 221 | { |
| 222 | u32 src = rpdev->src; |
| 223 | |
| 224 | return rpmsg_send_offchannel_raw(rpdev, src, dst, data, len, true); |
| 225 | } |
| 226 | |
| 227 | /** |
| 228 | * rpmsg_send_offchannel() - send a message using explicit src/dst addresses |
| 229 | * @rpdev: the rpmsg channel |
| 230 | * @src: source address |
| 231 | * @dst: destination address |
| 232 | * @data: payload of message |
| 233 | * @len: length of payload |
| 234 | * |
| 235 | * This function sends @data of length @len to the remote @dst address, |
| 236 | * and uses @src as the source address. |
| 237 | * The message will be sent to the remote processor which the @rpdev |
| 238 | * channel belongs to. |
| 239 | * In case there are no TX buffers available, the function will block until |
| 240 | * one becomes available, or a timeout of 15 seconds elapses. When the latter |
| 241 | * happens, -ERESTARTSYS is returned. |
| 242 | * |
| 243 | * Can only be called from process context (for now). |
| 244 | * |
| 245 | * Returns 0 on success and an appropriate error value on failure. |
| 246 | */ |
| 247 | static inline |
| 248 | int rpmsg_send_offchannel(struct rpmsg_channel *rpdev, u32 src, u32 dst, |
| 249 | void *data, int len) |
| 250 | { |
| 251 | return rpmsg_send_offchannel_raw(rpdev, src, dst, data, len, true); |
| 252 | } |
| 253 | |
| 254 | /** |
| 255 | * rpmsg_send() - send a message across to the remote processor |
| 256 | * @rpdev: the rpmsg channel |
| 257 | * @data: payload of message |
| 258 | * @len: length of payload |
| 259 | * |
| 260 | * This function sends @data of length @len on the @rpdev channel. |
| 261 | * The message will be sent to the remote processor which the @rpdev |
| 262 | * channel belongs to, using @rpdev's source and destination addresses. |
| 263 | * In case there are no TX buffers available, the function will immediately |
| 264 | * return -ENOMEM without waiting until one becomes available. |
| 265 | * |
| 266 | * Can only be called from process context (for now). |
| 267 | * |
| 268 | * Returns 0 on success and an appropriate error value on failure. |
| 269 | */ |
| 270 | static inline |
| 271 | int rpmsg_trysend(struct rpmsg_channel *rpdev, void *data, int len) |
| 272 | { |
| 273 | u32 src = rpdev->src, dst = rpdev->dst; |
| 274 | |
| 275 | return rpmsg_send_offchannel_raw(rpdev, src, dst, data, len, false); |
| 276 | } |
| 277 | |
| 278 | /** |
| 279 | * rpmsg_sendto() - send a message across to the remote processor, specify dst |
| 280 | * @rpdev: the rpmsg channel |
| 281 | * @data: payload of message |
| 282 | * @len: length of payload |
| 283 | * @dst: destination address |
| 284 | * |
| 285 | * This function sends @data of length @len to the remote @dst address. |
| 286 | * The message will be sent to the remote processor which the @rpdev |
| 287 | * channel belongs to, using @rpdev's source address. |
| 288 | * In case there are no TX buffers available, the function will immediately |
| 289 | * return -ENOMEM without waiting until one becomes available. |
| 290 | * |
| 291 | * Can only be called from process context (for now). |
| 292 | * |
| 293 | * Returns 0 on success and an appropriate error value on failure. |
| 294 | */ |
| 295 | static inline |
| 296 | int rpmsg_trysendto(struct rpmsg_channel *rpdev, void *data, int len, u32 dst) |
| 297 | { |
| 298 | u32 src = rpdev->src; |
| 299 | |
| 300 | return rpmsg_send_offchannel_raw(rpdev, src, dst, data, len, false); |
| 301 | } |
| 302 | |
| 303 | /** |
| 304 | * rpmsg_send_offchannel() - send a message using explicit src/dst addresses |
| 305 | * @rpdev: the rpmsg channel |
| 306 | * @src: source address |
| 307 | * @dst: destination address |
| 308 | * @data: payload of message |
| 309 | * @len: length of payload |
| 310 | * |
| 311 | * This function sends @data of length @len to the remote @dst address, |
| 312 | * and uses @src as the source address. |
| 313 | * The message will be sent to the remote processor which the @rpdev |
| 314 | * channel belongs to. |
| 315 | * In case there are no TX buffers available, the function will immediately |
| 316 | * return -ENOMEM without waiting until one becomes available. |
| 317 | * |
| 318 | * Can only be called from process context (for now). |
| 319 | * |
| 320 | * Returns 0 on success and an appropriate error value on failure. |
| 321 | */ |
| 322 | static inline |
| 323 | int rpmsg_trysend_offchannel(struct rpmsg_channel *rpdev, u32 src, u32 dst, |
| 324 | void *data, int len) |
| 325 | { |
| 326 | return rpmsg_send_offchannel_raw(rpdev, src, dst, data, len, false); |
| 327 | } |
| 328 | |
| 329 | #endif /* _LINUX_RPMSG_H */ |