include/linux/rpmsg.h

   1 /* SPDX-License-Identifier: BSD-3-Clause */
   2 /*
   3  * Remote processor messaging
   4  *
   5  * Copyright (C) 2011 Texas Instruments, Inc.
   6  * Copyright (C) 2011 Google, Inc.
   7  * All rights reserved.
   8  */
   9
  10 #ifndef _LINUX_RPMSG_H
  11 #define _LINUX_RPMSG_H
  12
  13 #include <linux/types.h>
  14 #include <linux/device.h>
  15 #include <linux/err.h>
  16 #include <linux/mod_devicetable.h>
  17 #include <linux/kref.h>
  18 #include <linux/mutex.h>
  19 #include <linux/poll.h>
  20 #include <linux/rpmsg/byteorder.h>
  21
  22 #define RPMSG_ADDR_ANY          0xFFFFFFFF
  23
  24 struct rpmsg_device;
  25 struct rpmsg_endpoint;
  26 struct rpmsg_device_ops;
  27 struct rpmsg_endpoint_ops;
  28
  29 /**
  30  * struct rpmsg_channel_info - channel info representation
  31  * @name: name of service
  32  * @src: local address
  33  * @dst: destination address
  34  */
  35 struct rpmsg_channel_info {
  36         char name[RPMSG_NAME_SIZE];
  37         u32 src;
  38         u32 dst;
  39 };
  40
  41 /**
  42  * rpmsg_device - device that belong to the rpmsg bus
  43  * @dev: the device struct
  44  * @id: device id (used to match between rpmsg drivers and devices)
  45  * @driver_override: driver name to force a match
  46  * @src: local address
  47  * @dst: destination address
  48  * @ept: the rpmsg endpoint of this channel
  49  * @announce: if set, rpmsg will announce the creation/removal of this channel
  50  * @little_endian: True if transport is using little endian byte representation
  51  */
  52 struct rpmsg_device {
  53         struct device dev;
  54         struct rpmsg_device_id id;
  55         char *driver_override;
  56         u32 src;
  57         u32 dst;
  58         struct rpmsg_endpoint *ept;
  59         bool announce;
  60         bool little_endian;
  61
  62         const struct rpmsg_device_ops *ops;
  63 };
  64
  65 typedef int (*rpmsg_rx_cb_t)(struct rpmsg_device *, void *, int, void *, u32);
  66
  67 /**
  68  * struct rpmsg_endpoint - binds a local rpmsg address to its user
  69  * @rpdev: rpmsg channel device
  70  * @refcount: when this drops to zero, the ept is deallocated
  71  * @cb: rx callback handler
  72  * @cb_lock: must be taken before accessing/changing @cb
  73  * @addr: local rpmsg address
  74  * @priv: private data for the driver's use
  75  *
  76  * In essence, an rpmsg endpoint represents a listener on the rpmsg bus, as
  77  * it binds an rpmsg address with an rx callback handler.
  78  *
  79  * Simple rpmsg drivers shouldn't use this struct directly, because
  80  * things just work: every rpmsg driver provides an rx callback upon
  81  * registering to the bus, and that callback is then bound to its rpmsg
  82  * address when the driver is probed. When relevant inbound messages arrive
  83  * (i.e. messages which their dst address equals to the src address of
  84  * the rpmsg channel), the driver's handler is invoked to process it.
  85  *
  86  * More complicated drivers though, that do need to allocate additional rpmsg
  87  * addresses, and bind them to different rx callbacks, must explicitly
  88  * create additional endpoints by themselves (see rpmsg_create_ept()).
  89  */
  90 struct rpmsg_endpoint {
  91         struct rpmsg_device *rpdev;
  92         struct kref refcount;
  93         rpmsg_rx_cb_t cb;
  94         struct mutex cb_lock;
  95         u32 addr;
  96         void *priv;
  97
  98         const struct rpmsg_endpoint_ops *ops;
  99 };
 100
 101 /**
 102  * struct rpmsg_driver - rpmsg driver struct
 103  * @drv: underlying device driver
 104  * @id_table: rpmsg ids serviced by this driver
 105  * @probe: invoked when a matching rpmsg channel (i.e. device) is found
 106  * @remove: invoked when the rpmsg channel is removed
 107  * @callback: invoked when an inbound message is received on the channel
 108  */
 109 struct rpmsg_driver {
 110         struct device_driver drv;
 111         const struct rpmsg_device_id *id_table;
 112         int (*probe)(struct rpmsg_device *dev);
 113         void (*remove)(struct rpmsg_device *dev);
 114         int (*callback)(struct rpmsg_device *, void *, int, void *, u32);
 115 };
 116
 117 static inline u16 rpmsg16_to_cpu(struct rpmsg_device *rpdev, __rpmsg16 val)
 118 {
 119         if (!rpdev)
 120                 return __rpmsg16_to_cpu(rpmsg_is_little_endian(), val);
 121         else
 122                 return __rpmsg16_to_cpu(rpdev->little_endian, val);
 123 }
 124
 125 static inline __rpmsg16 cpu_to_rpmsg16(struct rpmsg_device *rpdev, u16 val)
 126 {
 127         if (!rpdev)
 128                 return __cpu_to_rpmsg16(rpmsg_is_little_endian(), val);
 129         else
 130                 return __cpu_to_rpmsg16(rpdev->little_endian, val);
 131 }
 132
 133 static inline u32 rpmsg32_to_cpu(struct rpmsg_device *rpdev, __rpmsg32 val)
 134 {
 135         if (!rpdev)
 136                 return __rpmsg32_to_cpu(rpmsg_is_little_endian(), val);
 137         else
 138                 return __rpmsg32_to_cpu(rpdev->little_endian, val);
 139 }
 140
 141 static inline __rpmsg32 cpu_to_rpmsg32(struct rpmsg_device *rpdev, u32 val)
 142 {
 143         if (!rpdev)
 144                 return __cpu_to_rpmsg32(rpmsg_is_little_endian(), val);
 145         else
 146                 return __cpu_to_rpmsg32(rpdev->little_endian, val);
 147 }
 148
 149 static inline u64 rpmsg64_to_cpu(struct rpmsg_device *rpdev, __rpmsg64 val)
 150 {
 151         if (!rpdev)
 152                 return __rpmsg64_to_cpu(rpmsg_is_little_endian(), val);
 153         else
 154                 return __rpmsg64_to_cpu(rpdev->little_endian, val);
 155 }
 156
 157 static inline __rpmsg64 cpu_to_rpmsg64(struct rpmsg_device *rpdev, u64 val)
 158 {
 159         if (!rpdev)
 160                 return __cpu_to_rpmsg64(rpmsg_is_little_endian(), val);
 161         else
 162                 return __cpu_to_rpmsg64(rpdev->little_endian, val);
 163 }
 164
 165 #if IS_ENABLED(CONFIG_RPMSG)
 166
 167 int rpmsg_register_device(struct rpmsg_device *rpdev);
 168 int rpmsg_unregister_device(struct device *parent,
 169                             struct rpmsg_channel_info *chinfo);
 170 int __register_rpmsg_driver(struct rpmsg_driver *drv, struct module *owner);
 171 void unregister_rpmsg_driver(struct rpmsg_driver *drv);
 172 void rpmsg_destroy_ept(struct rpmsg_endpoint *);
 173 struct rpmsg_endpoint *rpmsg_create_ept(struct rpmsg_device *,
 174                                         rpmsg_rx_cb_t cb, void *priv,
 175                                         struct rpmsg_channel_info chinfo);
 176
 177 int rpmsg_send(struct rpmsg_endpoint *ept, void *data, int len);
 178 int rpmsg_sendto(struct rpmsg_endpoint *ept, void *data, int len, u32 dst);
 179 int rpmsg_send_offchannel(struct rpmsg_endpoint *ept, u32 src, u32 dst,
 180                           void *data, int len);
 181
 182 int rpmsg_trysend(struct rpmsg_endpoint *ept, void *data, int len);
 183 int rpmsg_trysendto(struct rpmsg_endpoint *ept, void *data, int len, u32 dst);
 184 int rpmsg_trysend_offchannel(struct rpmsg_endpoint *ept, u32 src, u32 dst,
 185                              void *data, int len);
 186
 187 __poll_t rpmsg_poll(struct rpmsg_endpoint *ept, struct file *filp,
 188                         poll_table *wait);
 189
 190 #else
 191
 192 static inline int rpmsg_register_device(struct rpmsg_device *rpdev)
 193 {
 194         return -ENXIO;
 195 }
 196
 197 static inline int rpmsg_unregister_device(struct device *parent,
 198                                           struct rpmsg_channel_info *chinfo)
 199 {
 200         /* This shouldn't be possible */
 201         WARN_ON(1);
 202
 203         return -ENXIO;
 204 }
 205
 206 static inline int __register_rpmsg_driver(struct rpmsg_driver *drv,
 207                                           struct module *owner)
 208 {
 209         /* This shouldn't be possible */
 210         WARN_ON(1);
 211
 212         return -ENXIO;
 213 }
 214
 215 static inline void unregister_rpmsg_driver(struct rpmsg_driver *drv)
 216 {
 217         /* This shouldn't be possible */
 218         WARN_ON(1);
 219 }
 220
 221 static inline void rpmsg_destroy_ept(struct rpmsg_endpoint *ept)
 222 {
 223         /* This shouldn't be possible */
 224         WARN_ON(1);
 225 }
 226
 227 static inline struct rpmsg_endpoint *rpmsg_create_ept(struct rpmsg_device *rpdev,
 228                                                       rpmsg_rx_cb_t cb,
 229                                                       void *priv,
 230                                                       struct rpmsg_channel_info chinfo)
 231 {
 232         /* This shouldn't be possible */
 233         WARN_ON(1);
 234
 235         return ERR_PTR(-ENXIO);
 236 }
 237
 238 static inline int rpmsg_send(struct rpmsg_endpoint *ept, void *data, int len)
 239 {
 240         /* This shouldn't be possible */
 241         WARN_ON(1);
 242
 243         return -ENXIO;
 244 }
 245
 246 static inline int rpmsg_sendto(struct rpmsg_endpoint *ept, void *data, int len,
 247                                u32 dst)
 248 {
 249         /* This shouldn't be possible */
 250         WARN_ON(1);
 251
 252         return -ENXIO;
 253
 254 }
 255
 256 static inline int rpmsg_send_offchannel(struct rpmsg_endpoint *ept, u32 src,
 257                                         u32 dst, void *data, int len)
 258 {
 259         /* This shouldn't be possible */
 260         WARN_ON(1);
 261
 262         return -ENXIO;
 263 }
 264
 265 static inline int rpmsg_trysend(struct rpmsg_endpoint *ept, void *data, int len)
 266 {
 267         /* This shouldn't be possible */
 268         WARN_ON(1);
 269
 270         return -ENXIO;
 271 }
 272
 273 static inline int rpmsg_trysendto(struct rpmsg_endpoint *ept, void *data,
 274                                   int len, u32 dst)
 275 {
 276         /* This shouldn't be possible */
 277         WARN_ON(1);
 278
 279         return -ENXIO;
 280 }
 281
 282 static inline int rpmsg_trysend_offchannel(struct rpmsg_endpoint *ept, u32 src,
 283                                            u32 dst, void *data, int len)
 284 {
 285         /* This shouldn't be possible */
 286         WARN_ON(1);
 287
 288         return -ENXIO;
 289 }
 290
 291 static inline __poll_t rpmsg_poll(struct rpmsg_endpoint *ept,
 292                                       struct file *filp, poll_table *wait)
 293 {
 294         /* This shouldn't be possible */
 295         WARN_ON(1);
 296
 297         return 0;
 298 }
 299
 300 #endif /* IS_ENABLED(CONFIG_RPMSG) */
 301
 302 /* use a macro to avoid include chaining to get THIS_MODULE */
 303 #define register_rpmsg_driver(drv) \
 304         __register_rpmsg_driver(drv, THIS_MODULE)
 305
 306 /**
 307  * module_rpmsg_driver() - Helper macro for registering an rpmsg driver
 308  * @__rpmsg_driver: rpmsg_driver struct
 309  *
 310  * Helper macro for rpmsg drivers which do not do anything special in module
 311  * init/exit. This eliminates a lot of boilerplate.  Each module may only
 312  * use this macro once, and calling it replaces module_init() and module_exit()
 313  */
 314 #define module_rpmsg_driver(__rpmsg_driver) \
 315         module_driver(__rpmsg_driver, register_rpmsg_driver, \
 316                         unregister_rpmsg_driver)
 317
 318 #endif /* _LINUX_RPMSG_H */