[mirror_ubuntu-bionic-kernel.git] / include / linux / rpmsg.h

/*
 * Remote processor messaging
 *
 * Copyright (C) 2011 Texas Instruments, Inc.
 * Copyright (C) 2011 Google, Inc.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * * Redistributions of source code must retain the above copyright
 *   notice, this list of conditions and the following disclaimer.
 * * Redistributions in binary form must reproduce the above copyright
 *   notice, this list of conditions and the following disclaimer in
 *   the documentation and/or other materials provided with the
 *   distribution.
 * * Neither the name Texas Instruments nor the names of its
 *   contributors may be used to endorse or promote products derived
 *   from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef _LINUX_RPMSG_H
#define _LINUX_RPMSG_H

#include <linux/types.h>
#include <linux/device.h>
#include <linux/err.h>
#include <linux/mod_devicetable.h>
#include <linux/kref.h>
#include <linux/mutex.h>
#include <linux/poll.h>

#define RPMSG_ADDR_ANY		0xFFFFFFFF

struct rpmsg_device;
struct rpmsg_endpoint;
struct rpmsg_device_ops;
struct rpmsg_endpoint_ops;

/**
 * struct rpmsg_channel_info - channel info representation
 * @name: name of service
 * @src: local address
 * @dst: destination address
 */
struct rpmsg_channel_info {
	char name[RPMSG_NAME_SIZE];
	u32 src;
	u32 dst;
};

/**
 * rpmsg_device - device that belong to the rpmsg bus
 * @dev: the device struct
 * @id: device id (used to match between rpmsg drivers and devices)
 * @driver_override: driver name to force a match
 * @src: local address
 * @dst: destination address
 * @ept: the rpmsg endpoint of this channel
 * @announce: if set, rpmsg will announce the creation/removal of this channel
 */
struct rpmsg_device {
	struct device dev;
	struct rpmsg_device_id id;
	char *driver_override;
	u32 src;
	u32 dst;
	struct rpmsg_endpoint *ept;
	bool announce;

	const struct rpmsg_device_ops *ops;
};

typedef int (*rpmsg_rx_cb_t)(struct rpmsg_device *, void *, int, void *, u32);

/**
 * struct rpmsg_endpoint - binds a local rpmsg address to its user
 * @rpdev: rpmsg channel device
 * @refcount: when this drops to zero, the ept is deallocated
 * @cb: rx callback handler
 * @cb_lock: must be taken before accessing/changing @cb
 * @addr: local rpmsg address
 * @priv: private data for the driver's use
 *
 * In essence, an rpmsg endpoint represents a listener on the rpmsg bus, as
 * it binds an rpmsg address with an rx callback handler.
 *
 * Simple rpmsg drivers shouldn't use this struct directly, because
 * things just work: every rpmsg driver provides an rx callback upon
 * registering to the bus, and that callback is then bound to its rpmsg
 * address when the driver is probed. When relevant inbound messages arrive
 * (i.e. messages which their dst address equals to the src address of
 * the rpmsg channel), the driver's handler is invoked to process it.
 *
 * More complicated drivers though, that do need to allocate additional rpmsg
 * addresses, and bind them to different rx callbacks, must explicitly
 * create additional endpoints by themselves (see rpmsg_create_ept()).
 */
struct rpmsg_endpoint {
	struct rpmsg_device *rpdev;
	struct kref refcount;
	rpmsg_rx_cb_t cb;
	struct mutex cb_lock;
	u32 addr;
	void *priv;

	const struct rpmsg_endpoint_ops *ops;
};

/**
 * struct rpmsg_driver - rpmsg driver struct
 * @drv: underlying device driver
 * @id_table: rpmsg ids serviced by this driver
 * @probe: invoked when a matching rpmsg channel (i.e. device) is found
 * @remove: invoked when the rpmsg channel is removed
 * @callback: invoked when an inbound message is received on the channel
 */
struct rpmsg_driver {
	struct device_driver drv;
	const struct rpmsg_device_id *id_table;
	int (*probe)(struct rpmsg_device *dev);
	void (*remove)(struct rpmsg_device *dev);
	int (*callback)(struct rpmsg_device *, void *, int, void *, u32);
};

#if IS_ENABLED(CONFIG_RPMSG)

int register_rpmsg_device(struct rpmsg_device *dev);
void unregister_rpmsg_device(struct rpmsg_device *dev);
int __register_rpmsg_driver(struct rpmsg_driver *drv, struct module *owner);
void unregister_rpmsg_driver(struct rpmsg_driver *drv);
void rpmsg_destroy_ept(struct rpmsg_endpoint *);
struct rpmsg_endpoint *rpmsg_create_ept(struct rpmsg_device *,
					rpmsg_rx_cb_t cb, void *priv,
					struct rpmsg_channel_info chinfo);

int rpmsg_send(struct rpmsg_endpoint *ept, void *data, int len);
int rpmsg_sendto(struct rpmsg_endpoint *ept, void *data, int len, u32 dst);
int rpmsg_send_offchannel(struct rpmsg_endpoint *ept, u32 src, u32 dst,
			  void *data, int len);

int rpmsg_trysend(struct rpmsg_endpoint *ept, void *data, int len);
int rpmsg_trysendto(struct rpmsg_endpoint *ept, void *data, int len, u32 dst);
int rpmsg_trysend_offchannel(struct rpmsg_endpoint *ept, u32 src, u32 dst,
			     void *data, int len);

unsigned int rpmsg_poll(struct rpmsg_endpoint *ept, struct file *filp,
			poll_table *wait);

#else

static inline int register_rpmsg_device(struct rpmsg_device *dev)
{
	return -ENXIO;
}

static inline void unregister_rpmsg_device(struct rpmsg_device *dev)
{
	/* This shouldn't be possible */
	WARN_ON(1);
}

static inline int __register_rpmsg_driver(struct rpmsg_driver *drv,
					  struct module *owner)
{
	/* This shouldn't be possible */
	WARN_ON(1);

	return -ENXIO;
}

static inline void unregister_rpmsg_driver(struct rpmsg_driver *drv)
{
	/* This shouldn't be possible */
	WARN_ON(1);
}

static inline void rpmsg_destroy_ept(struct rpmsg_endpoint *ept)
{
	/* This shouldn't be possible */
	WARN_ON(1);
}

static inline struct rpmsg_endpoint *rpmsg_create_ept(struct rpmsg_device *rpdev,
						      rpmsg_rx_cb_t cb,
						      void *priv,
						      struct rpmsg_channel_info chinfo)
{
	/* This shouldn't be possible */
	WARN_ON(1);

	return ERR_PTR(-ENXIO);
}

static inline int rpmsg_send(struct rpmsg_endpoint *ept, void *data, int len)
{
	/* This shouldn't be possible */
	WARN_ON(1);

	return -ENXIO;
}

static inline int rpmsg_sendto(struct rpmsg_endpoint *ept, void *data, int len,
			       u32 dst)
{
	/* This shouldn't be possible */
	WARN_ON(1);

	return -ENXIO;

}

static inline int rpmsg_send_offchannel(struct rpmsg_endpoint *ept, u32 src,
					u32 dst, void *data, int len)
{
	/* This shouldn't be possible */
	WARN_ON(1);

	return -ENXIO;
}

static inline int rpmsg_trysend(struct rpmsg_endpoint *ept, void *data, int len)
{
	/* This shouldn't be possible */
	WARN_ON(1);

	return -ENXIO;
}

static inline int rpmsg_trysendto(struct rpmsg_endpoint *ept, void *data,
				  int len, u32 dst)
{
	/* This shouldn't be possible */
	WARN_ON(1);

	return -ENXIO;
}

static inline int rpmsg_trysend_offchannel(struct rpmsg_endpoint *ept, u32 src,
					   u32 dst, void *data, int len)
{
	/* This shouldn't be possible */
	WARN_ON(1);

	return -ENXIO;
}

static inline unsigned int rpmsg_poll(struct rpmsg_endpoint *ept,
				      struct file *filp, poll_table *wait)
{
	/* This shouldn't be possible */
	WARN_ON(1);

	return 0;
}

#endif /* IS_ENABLED(CONFIG_RPMSG) */

/* use a macro to avoid include chaining to get THIS_MODULE */
#define register_rpmsg_driver(drv) \
	__register_rpmsg_driver(drv, THIS_MODULE)

/**
 * module_rpmsg_driver() - Helper macro for registering an rpmsg driver
 * @__rpmsg_driver: rpmsg_driver struct
 *
 * Helper macro for rpmsg drivers which do not do anything special in module
 * init/exit. This eliminates a lot of boilerplate.  Each module may only
 * use this macro once, and calling it replaces module_init() and module_exit()
 */
#define module_rpmsg_driver(__rpmsg_driver) \
	module_driver(__rpmsg_driver, register_rpmsg_driver, \
			unregister_rpmsg_driver)

#endif /* _LINUX_RPMSG_H */
Commit	Line	Data
bcabbcca OBC	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>
2c8a5708	40	#include <linux/err.h>
bcabbcca	41	#include <linux/mod_devicetable.h>
5a081caa	42	#include <linux/kref.h>
15fd943a	43	#include <linux/mutex.h>
84d58132	44	#include <linux/poll.h>
bcabbcca	45
bcabbcca OBC	46	#define RPMSG_ADDR_ANY 0xFFFFFFFF
bcabbcca OBC	47
8a228ecf	48	struct rpmsg_device;
36b72c7d BA	49	struct rpmsg_endpoint;
36b72c7d BA	50	struct rpmsg_device_ops;
8a228ecf	51	struct rpmsg_endpoint_ops;
bcabbcca	52
2b263d24 BA	53	/**
	54	* struct rpmsg_channel_info - channel info representation
	55	* @name: name of service
	56	* @src: local address
	57	* @dst: destination address
	58	*/
	59	struct rpmsg_channel_info {
	60	char name[RPMSG_NAME_SIZE];
	61	u32 src;
	62	u32 dst;
	63	};
	64
bcabbcca	65	/**
92e1de51	66	* rpmsg_device - device that belong to the rpmsg bus
bcabbcca OBC	67	* @dev: the device struct
bcabbcca OBC	68	* @id: device id (used to match between rpmsg drivers and devices)
e9506047	69	* @driver_override: driver name to force a match
bcabbcca OBC	70	* @src: local address
	71	* @dst: destination address
	72	* @ept: the rpmsg endpoint of this channel
	73	* @announce: if set, rpmsg will announce the creation/removal of this channel
	74	*/
92e1de51	75	struct rpmsg_device {
bcabbcca OBC	76	struct device dev;
bcabbcca OBC	77	struct rpmsg_device_id id;
e9506047	78	char *driver_override;
bcabbcca OBC	79	u32 src;
	80	u32 dst;
	81	struct rpmsg_endpoint *ept;
	82	bool announce;
36b72c7d BA	83
36b72c7d BA	84	const struct rpmsg_device_ops *ops;
bcabbcca OBC	85	};
bcabbcca OBC	86
4b83c52a	87	typedef int (rpmsg_rx_cb_t)(struct rpmsg_device , void , int, void , u32);
bcabbcca OBC	88
	89	/**
	90	* struct rpmsg_endpoint - binds a local rpmsg address to its user
	91	* @rpdev: rpmsg channel device
5a081caa	92	* @refcount: when this drops to zero, the ept is deallocated
bcabbcca	93	* @cb: rx callback handler
15fd943a	94	* @cb_lock: must be taken before accessing/changing @cb
bcabbcca OBC	95	* @addr: local rpmsg address
	96	* @priv: private data for the driver's use
	97	*
	98	* In essence, an rpmsg endpoint represents a listener on the rpmsg bus, as
	99	* it binds an rpmsg address with an rx callback handler.
	100	*
	101	* Simple rpmsg drivers shouldn't use this struct directly, because
	102	* things just work: every rpmsg driver provides an rx callback upon
	103	* registering to the bus, and that callback is then bound to its rpmsg
	104	* address when the driver is probed. When relevant inbound messages arrive
	105	* (i.e. messages which their dst address equals to the src address of
	106	* the rpmsg channel), the driver's handler is invoked to process it.
	107	*
	108	* More complicated drivers though, that do need to allocate additional rpmsg
	109	* addresses, and bind them to different rx callbacks, must explicitly
	110	* create additional endpoints by themselves (see rpmsg_create_ept()).
	111	*/
	112	struct rpmsg_endpoint {
92e1de51	113	struct rpmsg_device *rpdev;
5a081caa	114	struct kref refcount;
bcabbcca	115	rpmsg_rx_cb_t cb;
15fd943a	116	struct mutex cb_lock;
bcabbcca OBC	117	u32 addr;
bcabbcca OBC	118	void *priv;
8a228ecf BA	119
	120	const struct rpmsg_endpoint_ops *ops;
	121	};
	122
bcabbcca OBC	123	/**
	124	* struct rpmsg_driver - rpmsg driver struct
	125	* @drv: underlying device driver
	126	* @id_table: rpmsg ids serviced by this driver
	127	* @probe: invoked when a matching rpmsg channel (i.e. device) is found
	128	* @remove: invoked when the rpmsg channel is removed
	129	* @callback: invoked when an inbound message is received on the channel
	130	*/
	131	struct rpmsg_driver {
	132	struct device_driver drv;
	133	const struct rpmsg_device_id *id_table;
92e1de51 BA	134	int (probe)(struct rpmsg_device dev);
92e1de51 BA	135	void (remove)(struct rpmsg_device dev);
4b83c52a	136	int (callback)(struct rpmsg_device , void , int, void , u32);
bcabbcca OBC	137	};
bcabbcca OBC	138
2c8a5708 BA	139	#if IS_ENABLED(CONFIG_RPMSG)
2c8a5708 BA	140
92e1de51 BA	141	int register_rpmsg_device(struct rpmsg_device *dev);
92e1de51 BA	142	void unregister_rpmsg_device(struct rpmsg_device *dev);
bc3c57c1	143	int __register_rpmsg_driver(struct rpmsg_driver drv, struct module owner);
bcabbcca OBC	144	void unregister_rpmsg_driver(struct rpmsg_driver *drv);
bcabbcca OBC	145	void rpmsg_destroy_ept(struct rpmsg_endpoint *);
92e1de51	146	struct rpmsg_endpoint rpmsg_create_ept(struct rpmsg_device ,
2b263d24 BA	147	rpmsg_rx_cb_t cb, void *priv,
2b263d24 BA	148	struct rpmsg_channel_info chinfo);
bcabbcca	149
2c8a5708 BA	150	int rpmsg_send(struct rpmsg_endpoint ept, void data, int len);
	151	int rpmsg_sendto(struct rpmsg_endpoint ept, void data, int len, u32 dst);
	152	int rpmsg_send_offchannel(struct rpmsg_endpoint *ept, u32 src, u32 dst,
	153	void *data, int len);
	154
	155	int rpmsg_trysend(struct rpmsg_endpoint ept, void data, int len);
	156	int rpmsg_trysendto(struct rpmsg_endpoint ept, void data, int len, u32 dst);
	157	int rpmsg_trysend_offchannel(struct rpmsg_endpoint *ept, u32 src, u32 dst,
	158	void *data, int len);
	159
84d58132 BA	160	unsigned int rpmsg_poll(struct rpmsg_endpoint ept, struct file filp,
	161	poll_table *wait);
	162
2c8a5708 BA	163	#else
	164
	165	static inline int register_rpmsg_device(struct rpmsg_device *dev)
	166	{
	167	return -ENXIO;
	168	}
	169
	170	static inline void unregister_rpmsg_device(struct rpmsg_device *dev)
	171	{
	172	/* This shouldn't be possible */
	173	WARN_ON(1);
	174	}
	175
	176	static inline int __register_rpmsg_driver(struct rpmsg_driver *drv,
	177	struct module *owner)
	178	{
	179	/* This shouldn't be possible */
	180	WARN_ON(1);
	181
	182	return -ENXIO;
	183	}
	184
	185	static inline void unregister_rpmsg_driver(struct rpmsg_driver *drv)
	186	{
	187	/* This shouldn't be possible */
	188	WARN_ON(1);
	189	}
	190
	191	static inline void rpmsg_destroy_ept(struct rpmsg_endpoint *ept)
	192	{
	193	/* This shouldn't be possible */
	194	WARN_ON(1);
	195	}
	196
	197	static inline struct rpmsg_endpoint rpmsg_create_ept(struct rpmsg_device rpdev,
	198	rpmsg_rx_cb_t cb,
	199	void *priv,
	200	struct rpmsg_channel_info chinfo)
	201	{
	202	/* This shouldn't be possible */
	203	WARN_ON(1);
	204
	205	return ERR_PTR(-ENXIO);
	206	}
	207
	208	static inline int rpmsg_send(struct rpmsg_endpoint ept, void data, int len)
	209	{
	210	/* This shouldn't be possible */
	211	WARN_ON(1);
	212
	213	return -ENXIO;
	214	}
	215
	216	static inline int rpmsg_sendto(struct rpmsg_endpoint ept, void data, int len,
	217	u32 dst)
	218	{
	219	/* This shouldn't be possible */
	220	WARN_ON(1);
	221
	222	return -ENXIO;
	223
	224	}
	225
	226	static inline int rpmsg_send_offchannel(struct rpmsg_endpoint *ept, u32 src,
227	u32 dst, void *data, int len)
228	{
229	/* This shouldn't be possible */
230	WARN_ON(1);
231
232	return -ENXIO;
233	}
234
235	static inline int rpmsg_trysend(struct rpmsg_endpoint ept, void data, int len)
236	{
237	/* This shouldn't be possible */
238	WARN_ON(1);
239
240	return -ENXIO;
241	}
242
243	static inline int rpmsg_trysendto(struct rpmsg_endpoint ept, void data,
244	int len, u32 dst)
245	{
246	/* This shouldn't be possible */
247	WARN_ON(1);
248
249	return -ENXIO;
250	}
251
252	static inline int rpmsg_trysend_offchannel(struct rpmsg_endpoint *ept, u32 src,
253	u32 dst, void *data, int len)
254	{
255	/* This shouldn't be possible */
256	WARN_ON(1);
257
258	return -ENXIO;
259	}
260
84d58132 BA	261	static inline unsigned int rpmsg_poll(struct rpmsg_endpoint *ept,
	262	struct file filp, poll_table wait)
	263	{
	264	/* This shouldn't be possible */
	265	WARN_ON(1);
	266
	267	return 0;
	268	}
	269
2c8a5708 BA	270	#endif /* IS_ENABLED(CONFIG_RPMSG) */
2c8a5708 BA	271
bc3c57c1 AD	272	/* use a macro to avoid include chaining to get THIS_MODULE */
	273	#define register_rpmsg_driver(drv) \
	274	__register_rpmsg_driver(drv, THIS_MODULE)
	275
f3d9f1ce AD	276	/**
	277	* module_rpmsg_driver() - Helper macro for registering an rpmsg driver
	278	* @__rpmsg_driver: rpmsg_driver struct
	279	*
	280	* Helper macro for rpmsg drivers which do not do anything special in module
	281	* init/exit. This eliminates a lot of boilerplate. Each module may only
	282	* use this macro once, and calling it replaces module_init() and module_exit()
	283	*/
	284	#define module_rpmsg_driver(__rpmsg_driver) \
	285	module_driver(__rpmsg_driver, register_rpmsg_driver, \
	286	unregister_rpmsg_driver)
	287
bcabbcca	288	#endif /* _LINUX_RPMSG_H */