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  *
   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 _RPMSG_H_
  36 #define _RPMSG_H_
  37
  38 #include "openamp/rpmsg_core.h"
  39
  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
  43
  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;
  64
  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;
  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 /**
  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 };
 114
 115 /**
 116  * channel_info - channel info
 117  * @name: channel name
 118  * @src: local address
 119  * @dst: destination address
 120  */
 121
 122 struct channel_info {
 123         char name[RPMSG_NAME_SIZE];
 124         unsigned long src;
 125         unsigned long dest;
 126 };
 127
 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 };
 155
 156 struct rpmsg_endpoint *rpmsg_create_ept(struct rpmsg_channel *rp_chnl,
 157                                         rpmsg_rx_cb_t cb, void *priv,
 158                                         unsigned long addr);
 159
 160 void rpmsg_destroy_ept(struct rpmsg_endpoint *rp_ept);
 161
 162 int
 163 rpmsg_send_offchannel_raw(struct rpmsg_channel *, unsigned long, unsigned long,
 164                           char *, int, int);
 165
 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;
 190
 191         return rpmsg_send_offchannel_raw(rpdev, rpdev->src, dst, (char *)data,
 192                                          len, RPMSG_TRUE);
 193 }
 194
 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;
 216
 217         return rpmsg_send_offchannel_raw(rpdev, rpdev->src, rpdev->dst,
 218                                          (char *)data, len, RPMSG_TRUE);
 219 }
 220
 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;
 247
 248         return rpmsg_send_offchannel_raw(rpdev, src, dst, (char *)data, len,
 249                                          RPMSG_TRUE);
 250 }
 251
 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 {
 271
 272         if (!rpdev || !data)
 273                 return RPMSG_ERR_PARAM;
 274
 275         return rpmsg_send_offchannel_raw(rpdev, rpdev->src, rpdev->dst,
 276                                          (char *)data, len, RPMSG_FALSE);
 277 }
 278
 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;
 301
 302         if (!rpdev || !data)
 303                 return RPMSG_ERR_PARAM;
 304
 305         src = rpdev->src;
 306
 307         return rpmsg_send_offchannel_raw(rpdev, src, dst, (char *)data, len,
 308                                          RPMSG_FALSE);
 309 }
 310
 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;
 336
 337         return rpmsg_send_offchannel_raw(rpdev, src, dst, (char *)data, len,
 338                                          RPMSG_FALSE);
 339 }
 340
 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  */
 358
 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);
 363
 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);
 376
 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);
 388
 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);
 402
 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);
 413
 414 #endif                          /* _RPMSG_H_ */