#include <metal/compiler.h>
#include <metal/mutex.h>
#include <metal/list.h>
#include <metal/utilities.h>
#include <string.h>
#include <stdbool.h>
#include <stdint.h>

Data Structures
struct	rpmsg_endpoint
	Structure that binds a local RPMsg address to its user. More...

struct	rpmsg_device_ops
	RPMsg device operations. More...

struct	rpmsg_device
	Representation of a RPMsg device. More...

Macros
#define	RPMSG_NAME_SIZE (32)

#define	RPMSG_ADDR_BMP_SIZE (128)

#define	RPMSG_NS_EPT_ADDR (0x35)

#define	RPMSG_RESERVED_ADDRESSES (1024)

#define	RPMSG_ADDR_ANY 0xFFFFFFFF

#define	RPMSG_SUCCESS 0

#define	RPMSG_ERROR_BASE -2000

#define	RPMSG_ERR_NO_MEM (RPMSG_ERROR_BASE - 1)

#define	RPMSG_ERR_NO_BUFF (RPMSG_ERROR_BASE - 2)

#define	RPMSG_ERR_PARAM (RPMSG_ERROR_BASE - 3)

#define	RPMSG_ERR_DEV_STATE (RPMSG_ERROR_BASE - 4)

#define	RPMSG_ERR_BUFF_SIZE (RPMSG_ERROR_BASE - 5)

#define	RPMSG_ERR_INIT (RPMSG_ERROR_BASE - 6)

#define	RPMSG_ERR_ADDR (RPMSG_ERROR_BASE - 7)

#define	RPMSG_ERR_PERM (RPMSG_ERROR_BASE - 8)

#define	RPMSG_EOPNOTSUPP (RPMSG_ERROR_BASE - 9)

Typedefs
typedef int(*	rpmsg_ept_cb) (struct rpmsg_endpoint ept, void data, size_t len, uint32_t src, void *priv)

typedef void(*	rpmsg_ept_release_cb) (struct rpmsg_endpoint *ept)

typedef void(*	rpmsg_ns_unbind_cb) (struct rpmsg_endpoint *ept)

typedef void(*	rpmsg_ns_bind_cb) (struct rpmsg_device rdev, const char name, uint32_t dest)

Functions
int	rpmsg_send_offchannel_raw (struct rpmsg_endpoint ept, uint32_t src, uint32_t dst, const void data, int len, int wait)
	Send a message across to the remote processor, specifying source and destination address. More...

static int	rpmsg_send (struct rpmsg_endpoint ept, const void data, int len)
	Send a message across to the remote processor. More...

static int	rpmsg_sendto (struct rpmsg_endpoint ept, const void data, int len, uint32_t dst)
	Send a message across to the remote processor, specify dst. More...

static int	rpmsg_send_offchannel (struct rpmsg_endpoint ept, uint32_t src, uint32_t dst, const void data, int len)
	Send a message using explicit src/dst addresses. More...

static int	rpmsg_trysend (struct rpmsg_endpoint ept, const void data, int len)
	Send a message across to the remote processor. More...

static int	rpmsg_trysendto (struct rpmsg_endpoint ept, const void data, int len, uint32_t dst)
	Send a message across to the remote processor, specify dst. More...

static int	rpmsg_trysend_offchannel (struct rpmsg_endpoint ept, uint32_t src, uint32_t dst, const void data, int len)
	Send a message using explicit src/dst addresses. More...

void	rpmsg_hold_rx_buffer (struct rpmsg_endpoint ept, void rxbuf)
	Holds the rx buffer for usage outside the receive callback. More...

void	rpmsg_release_rx_buffer (struct rpmsg_endpoint ept, void rxbuf)
	Releases the rx buffer for future reuse in vring. More...

void *	rpmsg_get_tx_payload_buffer (struct rpmsg_endpoint ept, uint32_t len, int wait)
	Gets the tx buffer for message payload. More...

int	rpmsg_release_tx_buffer (struct rpmsg_endpoint ept, void txbuf)
	Releases unused buffer. More...

int	rpmsg_get_tx_buffer_size (struct rpmsg_endpoint *ept)
	Get RPMsg Tx buffer size. More...

int	rpmsg_get_rx_buffer_size (struct rpmsg_endpoint *ept)
	Get RPMsg Rx buffer size. More...

int	rpmsg_send_offchannel_nocopy (struct rpmsg_endpoint ept, uint32_t src, uint32_t dst, const void data, int len)
	Send a message in tx buffer reserved by rpmsg_get_tx_payload_buffer() across to the remote processor. More...

static int	rpmsg_sendto_nocopy (struct rpmsg_endpoint ept, const void data, int len, uint32_t dst)
	Sends a message in tx buffer allocated by rpmsg_get_tx_payload_buffer() across to the remote processor, specify dst. More...

static int	rpmsg_send_nocopy (struct rpmsg_endpoint ept, const void data, int len)
	Send a message in tx buffer reserved by rpmsg_get_tx_payload_buffer() across to the remote processor. More...

int	rpmsg_create_ept (struct rpmsg_endpoint ept, struct rpmsg_device rdev, const char *name, uint32_t src, uint32_t dest, rpmsg_ept_cb cb, rpmsg_ns_unbind_cb ns_unbind_cb)
	Create rpmsg endpoint and register it to rpmsg device. More...

void	rpmsg_destroy_ept (struct rpmsg_endpoint *ept)
	Destroy rpmsg endpoint and unregister it from rpmsg device. More...

static unsigned int	is_rpmsg_ept_ready (struct rpmsg_endpoint *ept)
	Check if the rpmsg endpoint ready to send. More...

Macro Definition Documentation

◆ RPMSG_ADDR_ANY

#define RPMSG_ADDR_ANY 0xFFFFFFFF

◆ RPMSG_ADDR_BMP_SIZE

#define RPMSG_ADDR_BMP_SIZE (128)

◆ RPMSG_EOPNOTSUPP

#define RPMSG_EOPNOTSUPP (RPMSG_ERROR_BASE - 9)

◆ RPMSG_ERR_ADDR

#define RPMSG_ERR_ADDR (RPMSG_ERROR_BASE - 7)

◆ RPMSG_ERR_BUFF_SIZE

#define RPMSG_ERR_BUFF_SIZE (RPMSG_ERROR_BASE - 5)

◆ RPMSG_ERR_DEV_STATE

#define RPMSG_ERR_DEV_STATE (RPMSG_ERROR_BASE - 4)

◆ RPMSG_ERR_INIT

#define RPMSG_ERR_INIT (RPMSG_ERROR_BASE - 6)

◆ RPMSG_ERR_NO_BUFF

#define RPMSG_ERR_NO_BUFF (RPMSG_ERROR_BASE - 2)

◆ RPMSG_ERR_NO_MEM

#define RPMSG_ERR_NO_MEM (RPMSG_ERROR_BASE - 1)

◆ RPMSG_ERR_PARAM

#define RPMSG_ERR_PARAM (RPMSG_ERROR_BASE - 3)

◆ RPMSG_ERR_PERM

#define RPMSG_ERR_PERM (RPMSG_ERROR_BASE - 8)

◆ RPMSG_ERROR_BASE

#define RPMSG_ERROR_BASE -2000

◆ RPMSG_NAME_SIZE

#define RPMSG_NAME_SIZE (32)

◆ RPMSG_NS_EPT_ADDR

#define RPMSG_NS_EPT_ADDR (0x35)

◆ RPMSG_RESERVED_ADDRESSES

#define RPMSG_RESERVED_ADDRESSES (1024)

◆ RPMSG_SUCCESS

#define RPMSG_SUCCESS 0

Typedef Documentation

◆ rpmsg_ept_cb

typedef int(* rpmsg_ept_cb) (struct rpmsg_endpoint *ept, void *data, size_t len, uint32_t src, void *priv)

◆ rpmsg_ept_release_cb

typedef void(* rpmsg_ept_release_cb) (struct rpmsg_endpoint *ept)

◆ rpmsg_ns_bind_cb

typedef void(* rpmsg_ns_bind_cb) (struct rpmsg_device *rdev, const char *name, uint32_t dest)

◆ rpmsg_ns_unbind_cb

typedef void(* rpmsg_ns_unbind_cb) (struct rpmsg_endpoint *ept)

Function Documentation

◆ is_rpmsg_ept_ready()

static unsigned int is_rpmsg_ept_ready ( struct rpmsg_endpoint * ept )

inlinestatic

Check if the rpmsg endpoint ready to send.

Parameters

ept	Pointer to rpmsg endpoint

Returns: 1 if the rpmsg endpoint has both local addr and destination addr set, 0 otherwise

◆ rpmsg_create_ept()

int rpmsg_create_ept	(	struct rpmsg_endpoint *	ept,
		struct rpmsg_device *	rdev,
		const char *	name,
		uint32_t	src,
		uint32_t	dest,
		rpmsg_ept_cb	cb,
		rpmsg_ns_unbind_cb	ns_unbind_cb
	)

Create rpmsg endpoint and register it to rpmsg device.

Create a RPMsg endpoint, initialize it with a name, source address, remoteproc address, endpoint callback, and destroy endpoint callback, and register it to the RPMsg device.

In essence, an rpmsg endpoint represents a listener on the rpmsg bus, as it binds an rpmsg address with an rx callback handler.

Rpmsg client should create an endpoint to discuss with remote. rpmsg client provide at least a channel name, a callback for message notification and by default endpoint source address should be set to RPMSG_ADDR_ANY.

As an option Some rpmsg clients can specify an endpoint with a specific source address.

Parameters

ept	Pointer to rpmsg endpoint
rdev	RPMsg device associated with the endpoint
name	Service name associated to the endpoint (maximum size RPMSG_NAME_SIZE)
src	Local address of the endpoint
dest	Target address of the endpoint
cb	Endpoint callback
ns_unbind_cb	Endpoint service unbind callback, called when remote ept is destroyed.

Returns: 0 on success, or negative error value on failure.

◆ rpmsg_destroy_ept()

void rpmsg_destroy_ept ( struct rpmsg_endpoint * ept )

Destroy rpmsg endpoint and unregister it from rpmsg device.

It unregisters the rpmsg endpoint from the rpmsg device and calls the destroy endpoint callback if it is provided.

Parameters

ept	Pointer to the rpmsg endpoint

◆ rpmsg_get_rx_buffer_size()

int rpmsg_get_rx_buffer_size ( struct rpmsg_endpoint * ept )

Get RPMsg Rx buffer size.

Parameters

ept	The rpmsg endpoint

Returns

Next available Rx buffer size on success
RPMSG_ERR_PARAM on invalid parameter
RPMSG_ERR_PERM if service not implemented

◆ rpmsg_get_tx_buffer_size()

int rpmsg_get_tx_buffer_size ( struct rpmsg_endpoint * ept )

Get RPMsg Tx buffer size.

Parameters

ept	The rpmsg endpoint

Returns

Next available Tx buffer size on success
RPMSG_ERR_PARAM on invalid parameter
RPMSG_ERR_PERM if service not implemented

◆ rpmsg_get_tx_payload_buffer()

void* rpmsg_get_tx_payload_buffer	(	struct rpmsg_endpoint *	ept,
		uint32_t *	len,
		int	wait
	)

Gets the tx buffer for message payload.

This API can only be called at process context to get the tx buffer in vring. By this way, the application can directly put its message into the vring tx buffer without copy from an application buffer. It is the application responsibility to correctly fill the allocated tx buffer by data and passing correct parameters to the rpmsg_send_nocopy() or rpmsg_sendto_nocopy() function to perform data no-copy-send mechanism.

Parameters

ept	Pointer to rpmsg endpoint
len	Pointer to store tx buffer size
wait	Boolean, wait or not for buffer to become available

Returns: The tx buffer address on success and NULL on failure

See also: rpmsg_send_offchannel_nocopy; rpmsg_sendto_nocopy; rpmsg_send_nocopy

◆ rpmsg_hold_rx_buffer()

void rpmsg_hold_rx_buffer	(	struct rpmsg_endpoint *	ept,
		void *	rxbuf
	)

Holds the rx buffer for usage outside the receive callback.

Calling this function prevents the RPMsg receive buffer from being released back to the pool of shmem buffers. This API can only be called at rx callback context (rpmsg_rx_cb_t). With this API, the application doesn't need to copy the message in rx callback. Instead, the rx buffer base address is saved in application context and further processed in application process. After the message is processed, the application can release the rx buffer for future reuse in vring by calling the rpmsg_release_rx_buffer() function.

Parameters

ept	The rpmsg endpoint
rxbuf	RX buffer with message payload

See also: rpmsg_release_rx_buffer

◆ rpmsg_release_rx_buffer()

void rpmsg_release_rx_buffer	(	struct rpmsg_endpoint *	ept,
		void *	rxbuf
	)

Releases the rx buffer for future reuse in vring.

This API can be called at process context when the message in rx buffer is processed.

Parameters

ept	The rpmsg endpoint
rxbuf	rx buffer with message payload

See also: rpmsg_hold_rx_buffer

◆ rpmsg_release_tx_buffer()

int rpmsg_release_tx_buffer	(	struct rpmsg_endpoint *	ept,
		void *	txbuf
	)

Releases unused buffer.

This API can be called when the Tx buffer reserved by rpmsg_get_tx_payload_buffer needs to be released without having been sent to the remote side.

Note that the rpmsg virtio is not able to detect if a buffer has already been released. The user must prevent a double release (e.g. by resetting its buffer pointer to zero after the release).

Parameters

ept	The rpmsg endpoint
txbuf	tx buffer with message payload

Returns

RPMSG_SUCCESS on success
RPMSG_ERR_PARAM on invalid parameter
RPMSG_ERR_PERM if service not implemented

See also: rpmsg_get_tx_payload_buffer

◆ rpmsg_send()

static int rpmsg_send	(	struct rpmsg_endpoint *	ept,
		const void *	data,
		int	len
	)

inlinestatic

Send a message across to the remote processor.

This function sends data of length len based on the ept. The message will be sent to the remote processor which the channel belongs to, using ept's source and destination addresses. In case there are no TX buffers available, the function will block until one becomes available, or a timeout of 15 seconds elapses. When the latter happens, -ERESTARTSYS is returned.

Parameters

ept	The rpmsg endpoint
data	Payload of the message
len	Length of the payload

Returns: Number of bytes it has sent or negative error value on failure.

◆ rpmsg_send_nocopy()

static int rpmsg_send_nocopy	(	struct rpmsg_endpoint *	ept,
		const void *	data,
		int	len
	)

inlinestatic

Send a message in tx buffer reserved by rpmsg_get_tx_payload_buffer() across to the remote processor.

This function sends buf of length len on the ept endpoint. The message will be sent to the remote processor which the ept endpoint belongs to, using ept's source and destination addresses. The application has to take the responsibility for:

tx buffer reserved (rpmsg_get_tx_payload_buffer() )
filling the data to be sent into the pre-allocated tx buffer
not exceeding the buffer size when filling the data
data cache coherency

After the rpmsg_send_nocopy() function is issued the tx buffer is no more owned by the sending task and must not be touched anymore unless the rpmsg_send_nocopy() function fails and returns an error. In that case the application should try to re-issue the rpmsg_send_nocopy() again.

Parameters

ept	The rpmsg endpoint
data	TX buffer with message filled
len	Length of payload

Returns: Number of bytes it has sent or negative error value on failure.

See also: rpmsg_get_tx_payload_buffer; rpmsg_send_offchannel_nocopy; rpmsg_sendto_nocopy

◆ rpmsg_send_offchannel()

static int rpmsg_send_offchannel	(	struct rpmsg_endpoint *	ept,
		uint32_t	src,
		uint32_t	dst,
		const void *	data,
		int	len
	)

inlinestatic

Send a message using explicit src/dst addresses.

This function sends data of length len to the remote dst address, and uses src as the source address. The message will be sent to the remote processor which the ept channel belongs to. In case there are no TX buffers available, the function will block until one becomes available, or a timeout of 15 seconds elapses. When the latter happens, -ERESTARTSYS is returned.

Parameters

ept	The rpmsg endpoint
src	Source address
dst	Destination address
data	Payload of message
len	Length of payload

Returns: Number of bytes it has sent or negative error value on failure.

◆ rpmsg_send_offchannel_nocopy()

int rpmsg_send_offchannel_nocopy	(	struct rpmsg_endpoint *	ept,
		uint32_t	src,
		uint32_t	dst,
		const void *	data,
		int	len
	)

Send a message in tx buffer reserved by rpmsg_get_tx_payload_buffer() across to the remote processor.

This function sends buf of length len to the remote dst address, and uses src as the source address. The message will be sent to the remote processor which the ept endpoint belongs to. The application has to take the responsibility for:

tx buffer reserved (rpmsg_get_tx_payload_buffer() )
filling the data to be sent into the pre-allocated tx buffer
not exceeding the buffer size when filling the data
data cache coherency

After the rpmsg_send_offchannel_nocopy() function is issued the tx buffer is no more owned by the sending task and must not be touched anymore unless the rpmsg_send_offchannel_nocopy() function fails and returns an error. In that case application should try to re-issue the rpmsg_send_offchannel_nocopy() again.

Parameters

ept	The rpmsg endpoint
src	The rpmsg endpoint local address
dst	The rpmsg endpoint remote address
data	TX buffer with message filled
len	Length of payload

Returns: Number of bytes it has sent or negative error value on failure.

See also: rpmsg_get_tx_payload_buffer; rpmsg_sendto_nocopy; rpmsg_send_nocopy

◆ rpmsg_send_offchannel_raw()

int rpmsg_send_offchannel_raw	(	struct rpmsg_endpoint *	ept,
		uint32_t	src,
		uint32_t	dst,
		const void *	data,
		int	len,
		int	wait
	)

Send a message across to the remote processor, specifying source and destination address.

This function sends data of length len to the remote dst address from the source src address. The message will be sent to the remote processor which the channel belongs to.

Parameters

ept	The rpmsg endpoint
src	Source endpoint address of the message
dst	Destination endpoint address of the message
data	Payload of the message
len	Length of the payload
wait	Boolean value indicating whether to wait on buffers

Returns: Number of bytes it has sent or negative error value on failure.

◆ rpmsg_sendto()

static int rpmsg_sendto	(	struct rpmsg_endpoint *	ept,
		const void *	data,
		int	len,
		uint32_t	dst
	)

inlinestatic

Send a message across to the remote processor, specify dst.

This function sends data of length len to the remote dst address. The message will be sent to the remote processor which the ept channel belongs to, using ept's source address. In case there are no TX buffers available, the function will block until one becomes available, or a timeout of 15 seconds elapses. When the latter happens, -ERESTARTSYS is returned.

Parameters

ept	The rpmsg endpoint
data	Payload of message
len	Length of payload
dst	Destination address

Returns: Number of bytes it has sent or negative error value on failure.

◆ rpmsg_sendto_nocopy()

static int rpmsg_sendto_nocopy	(	struct rpmsg_endpoint *	ept,
		const void *	data,
		int	len,
		uint32_t	dst
	)

inlinestatic

Sends a message in tx buffer allocated by rpmsg_get_tx_payload_buffer() across to the remote processor, specify dst.

This function sends buf of length len to the remote dst address. The message will be sent to the remote processor which the ept endpoint belongs to, using ept's source address. The application has to take the responsibility for:

tx buffer allocation (rpmsg_get_tx_payload_buffer() )
filling the data to be sent into the pre-allocated tx buffer
not exceeding the buffer size when filling the data
data cache coherency

After the rpmsg_sendto_nocopy() function is issued the tx buffer is no more owned by the sending task and must not be touched anymore unless the rpmsg_sendto_nocopy() function fails and returns an error. In that case the application should try to re-issue the rpmsg_sendto_nocopy() again.

Parameters

ept	The rpmsg endpoint
data	TX buffer with message filled
len	Length of payload
dst	Destination address

Returns: Number of bytes it has sent or negative error value on failure.

See also: rpmsg_get_tx_payload_buffer; rpmsg_send_offchannel_nocopy; rpmsg_send_nocopy

◆ rpmsg_trysend()

static int rpmsg_trysend	(	struct rpmsg_endpoint *	ept,
		const void *	data,
		int	len
	)

inlinestatic

Send a message across to the remote processor.

This function sends data of length len on the ept channel. The message will be sent to the remote processor which the ept channel belongs to, using ept's source and destination addresses. In case there are no TX buffers available, the function will immediately return -ENOMEM without waiting until one becomes available.

Parameters

ept	The rpmsg endpoint
data	Payload of message
len	Length of payload

Returns: Number of bytes it has sent or negative error value on failure.

◆ rpmsg_trysend_offchannel()

static int rpmsg_trysend_offchannel	(	struct rpmsg_endpoint *	ept,
		uint32_t	src,
		uint32_t	dst,
		const void *	data,
		int	len
	)

inlinestatic

Send a message using explicit src/dst addresses.

This function sends data of length len to the remote dst address, and uses src as the source address. The message will be sent to the remote processor which the ept channel belongs to. In case there are no TX buffers available, the function will immediately return -ENOMEM without waiting until one becomes available.

Parameters

ept	The rpmsg endpoint
src	Source address
dst	Destination address
data	Payload of message
len	Length of payload

Returns: Number of bytes it has sent or negative error value on failure.

◆ rpmsg_trysendto()

static int rpmsg_trysendto	(	struct rpmsg_endpoint *	ept,
		const void *	data,
		int	len,
		uint32_t	dst
	)

inlinestatic

Send a message across to the remote processor, specify dst.

This function sends data of length len to the remote dst address. The message will be sent to the remote processor which the ept channel belongs to, using ept's source address. In case there are no TX buffers available, the function will immediately return -ENOMEM without waiting until one becomes available.

Parameters

ept	The rpmsg endpoint
data	Payload of message
len	Length of payload
dst	Destination address

Returns: Number of bytes it has sent or negative error value on failure.

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

◆ RPMSG_ADDR_ANY

◆ RPMSG_ADDR_BMP_SIZE

◆ RPMSG_EOPNOTSUPP

◆ RPMSG_ERR_ADDR

◆ RPMSG_ERR_BUFF_SIZE

◆ RPMSG_ERR_DEV_STATE

◆ RPMSG_ERR_INIT

◆ RPMSG_ERR_NO_BUFF

◆ RPMSG_ERR_NO_MEM

◆ RPMSG_ERR_PARAM

◆ RPMSG_ERR_PERM

◆ RPMSG_ERROR_BASE

◆ RPMSG_NAME_SIZE

◆ RPMSG_NS_EPT_ADDR

◆ RPMSG_RESERVED_ADDRESSES

◆ RPMSG_SUCCESS

Typedef Documentation

◆ rpmsg_ept_cb

◆ rpmsg_ept_release_cb

◆ rpmsg_ns_bind_cb

◆ rpmsg_ns_unbind_cb

Function Documentation

◆ is_rpmsg_ept_ready()

◆ rpmsg_create_ept()

◆ rpmsg_destroy_ept()

◆ rpmsg_get_rx_buffer_size()

◆ rpmsg_get_tx_buffer_size()

◆ rpmsg_get_tx_payload_buffer()

◆ rpmsg_hold_rx_buffer()

◆ rpmsg_release_rx_buffer()

◆ rpmsg_release_tx_buffer()

◆ rpmsg_send()

◆ rpmsg_send_nocopy()

◆ rpmsg_send_offchannel()

◆ rpmsg_send_offchannel_nocopy()

◆ rpmsg_send_offchannel_raw()

◆ rpmsg_sendto()

◆ rpmsg_sendto_nocopy()

◆ rpmsg_trysend()

◆ rpmsg_trysend_offchannel()

◆ rpmsg_trysendto()