This section describes the RPMsg-Lite core component that allows: More...

Overview

This section describes the RPMsg-Lite core component that allows:

Callback based reception.
Blocking send functionality.
Zero-copy send functionality.

Classes
struct	rpmsg_hdr_reserved
	Reserved field structure used in rpmsg_std_hdr. More...

struct	rpmsg_std_hdr

struct	rpmsg_std_msg

struct	rpmsg_lite_endpoint

struct	rpmsg_lite_ept_static_context

struct	rpmsg_lite_instance

Macros
#define	RL_VERSION

#define	RL_WORD_SIZE
	Word size used for alignment.

#define	RL_WORD_ALIGN_UP(a)
	Align a value up to the next multiple of the word size.

#define	RL_WORD_ALIGN_DOWN(a)
	Align a value down to a multiple of the word size.

#define	RL_SUCCESS
	Success status code.

#define	RL_NULL
	NULL pointer definition.

#define	RL_REMOTE
	Remote device identifier.

#define	RL_MASTER
	Master device identifier.

#define	RL_TRUE
	Boolean true value.

#define	RL_FALSE
	Boolean false value.

#define	RL_ADDR_ANY
	Special address indicating any address.

#define	RL_RELEASE
	Flag to release the buffer.

#define	RL_HOLD
	Flag to hold the buffer.

#define	RL_DONT_BLOCK
	Don't block and return immediately.

#define	RL_BLOCK
	Block until the operation is complete.

#define	RL_ERRORS_BASE
	Base value for all RPMsg-Lite error codes.

#define	RL_ERR_NO_MEM
	Error code: Out of memory.

#define	RL_ERR_BUFF_SIZE
	Error code: Buffer size too small.

#define	RL_ERR_PARAM
	Error code: Invalid parameter.

#define	RL_ERR_DEV_ID
	Error code: Invalid device ID.

#define	RL_ERR_MAX_VQ
	Error code: Maximum number of VirtQueues reached.

#define	RL_ERR_NO_BUFF
	Error code: No buffer available.

#define	RL_NOT_READY
	Error code: System not ready.

#define	RL_ALREADY_DONE
	Error code: Operation already completed.

#define	RL_NO_FLAGS
	No initialization flags.

Typedefs
typedef int32_t(*	rl_ept_rx_cb_t) (void payload, uint32_t payload_len, uint32_t src, void priv)
	Receive callback function type.

Functions
struct rpmsg_lite_instance *	rpmsg_lite_master_init (void *shmem_addr, size_t shmem_length, uint32_t link_id, uint32_t init_flags)
	Initializes the RPMsg-Lite communication stack. Must be called prior to any other RPMSG lite API. To be called by the master side.

struct rpmsg_lite_instance *	rpmsg_lite_remote_init (void *shmem_addr, uint32_t link_id, uint32_t init_flags)
	Initializes the RPMsg-Lite communication stack. Must be called prior to any other RPMsg-Lite API. To be called by the remote side.

int32_t	rpmsg_lite_deinit (struct rpmsg_lite_instance *rpmsg_lite_dev)
	Deinitialized the RPMsg-Lite communication stack This function always succeeds. rpmsg_lite_init() can be called again after this function has been called.

struct rpmsg_lite_endpoint *	rpmsg_lite_create_ept (struct rpmsg_lite_instance rpmsg_lite_dev, uint32_t addr, rl_ept_rx_cb_t rx_cb, void rx_cb_data)
	Create a new rpmsg endpoint, which can be used for communication.

int32_t	rpmsg_lite_destroy_ept (struct rpmsg_lite_instance rpmsg_lite_dev, struct rpmsg_lite_endpoint rl_ept)
	This function deletes rpmsg endpoint and performs cleanup.

int32_t	rpmsg_lite_send (struct rpmsg_lite_instance rpmsg_lite_dev, struct rpmsg_lite_endpoint ept, uint32_t dst, char *data, uint32_t size, uintptr_t timeout)
	Sends a message contained in data field of length size to the remote endpoint with address dst. ept->addr is used as source address in the rpmsg header of the message being sent.

uint32_t	rpmsg_lite_is_link_up (struct rpmsg_lite_instance *rpmsg_lite_dev)
	Function to get the link state.

uint32_t	rpmsg_lite_wait_for_link_up (struct rpmsg_lite_instance *rpmsg_lite_dev, uint32_t timeout)
	Function to wait until the link is up. Returns RL_TRUE once the link_state is set or RL_FALSE in case of timeout.

int32_t	rpmsg_lite_release_rx_buffer (struct rpmsg_lite_instance rpmsg_lite_dev, 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.

void *	rpmsg_lite_alloc_tx_buffer (struct rpmsg_lite_instance rpmsg_lite_dev, uint32_t size, uintptr_t timeout)
	Allocates the tx buffer for message payload.

int32_t	rpmsg_lite_send_nocopy (struct rpmsg_lite_instance rpmsg_lite_dev, struct rpmsg_lite_endpoint ept, uint32_t dst, void *data, uint32_t size)
	Sends a message in tx buffer allocated by rpmsg_lite_alloc_tx_buffer()

Variables
RL_PACKED_BEGIN struct rpmsg_std_hdr	RL_PACKED_END
	End of packed structure.

Class Documentation

◆ rpmsg_hdr_reserved

struct rpmsg_hdr_reserved

Reserved field structure used in rpmsg_std_hdr.

This structure holds the idx and totlen of a buffer that is not immediately returned to the vring in the receive callback function. This allows the no-copy API to use this field to return the buffer later.

Class Members
uint16_t	rfu
uint16_t	idx

◆ rpmsg_std_hdr

struct rpmsg_std_hdr

Common header for all rpmsg messages. Every message sent/received on the rpmsg bus begins with this header.

Class Members
uint32_t	src	source endpoint address
uint32_t	dst	destination endpoint address
struct rpmsg_hdr_reserved	reserved	reserved for future use
uint16_t	len	length of payload (in bytes)
uint16_t	flags	message flags

◆ rpmsg_std_msg

struct rpmsg_std_msg

Common message structure. Contains the header and the payload.

Class Members
struct rpmsg_std_hdr	hdr	RPMsg message header
uint8_t	data[1]	bytes of message payload data

◆ rpmsg_lite_endpoint

struct rpmsg_lite_endpoint

RPMsg Lite Endpoint structure

Class Members
uint32_t	addr	endpoint address
rl_ept_rx_cb_t	rx_cb	ISR callback function
void *	rx_cb_data	ISR callback data
void *	rfu	reserved for future usage

◆ rpmsg_lite_ept_static_context

struct rpmsg_lite_ept_static_context

RPMsg Lite Endpoint static context

Class Members
struct rpmsg_lite_endpoint	ept	memory for endpoint structure
struct llist	node	memory for linked list node structure

◆ rpmsg_lite_instance

struct rpmsg_lite_instance

Structure describing the local instance of RPMSG lite communication stack and holds all runtime variables needed internally by the stack.

Class Members
struct virtqueue *	rvq	receive virtqueue
struct virtqueue *	tvq	transmit virtqueue
struct llist *	rl_endpoints	linked list of endpoints
LOCK *	lock	local RPMsg Lite mutex lock
uint32_t	link_state	state of the link, up/down
char *	sh_mem_base	base address of the shared memory
uint32_t	sh_mem_remaining	amount of remaining unused buffers in shared memory
uint32_t	sh_mem_total	total amount of buffers in shared memory
struct virtqueue_ops const *	vq_ops	ops functions table pointer
uint32_t	link_id	linkID of this rpmsg_lite instance

Macro Definition Documentation

◆ RL_VERSION

#define RL_VERSION

Current RPMsg Lite version

Function Documentation

◆ rpmsg_lite_master_init()

struct rpmsg_lite_instance * rpmsg_lite_master_init	(	void *	shmem_addr,
		size_t	shmem_length,
		uint32_t	link_id,
		uint32_t	init_flags
	)

Initializes the RPMsg-Lite communication stack. Must be called prior to any other RPMSG lite API. To be called by the master side.

Parameters

shmem_addr	Shared memory base used for this instance of RPMsg-Lite
shmem_length	Length of memory area given by previous parameter
link_id	Link ID used to define the rpmsg-lite instance, see rpmsg_platform.h
init_flags	Initialization flags

Returns: New RPMsg-Lite instance pointer or RL_NULL.

◆ rpmsg_lite_remote_init()

struct rpmsg_lite_instance * rpmsg_lite_remote_init	(	void *	shmem_addr,
		uint32_t	link_id,
		uint32_t	init_flags
	)

Initializes the RPMsg-Lite communication stack. Must be called prior to any other RPMsg-Lite API. To be called by the remote side.

Parameters

shmem_addr	Shared memory base used for this instance of RPMsg-Lite
link_id	Link ID used to define the rpmsg-lite instance, see rpmsg_platform.h
init_flags	Initialization flags

Returns: New RPMsg-Lite instance pointer or RL_NULL.

◆ rpmsg_lite_deinit()

int32_t rpmsg_lite_deinit ( struct rpmsg_lite_instance * rpmsg_lite_dev )

Deinitialized the RPMsg-Lite communication stack This function always succeeds. rpmsg_lite_init() can be called again after this function has been called.

Parameters

rpmsg_lite_dev RPMsg-Lite instance

Returns: Status of function execution, RL_SUCCESS on success.

◆ rpmsg_lite_create_ept()

struct rpmsg_lite_endpoint * rpmsg_lite_create_ept	(	struct rpmsg_lite_instance *	rpmsg_lite_dev,
		uint32_t	addr,
		rl_ept_rx_cb_t	rx_cb,
		void *	rx_cb_data
	)

Create a new rpmsg endpoint, which can be used for communication.

Parameters

rpmsg_lite_dev	RPMsg-Lite instance
addr	Desired address, RL_ADDR_ANY for automatic selection
rx_cb	Callback function called on receive
rx_cb_data	Callback data pointer, passed to rx_cb

Returns: RL_NULL on error, new endpoint pointer on success.

◆ rpmsg_lite_destroy_ept()

int32_t rpmsg_lite_destroy_ept	(	struct rpmsg_lite_instance *	rpmsg_lite_dev,
		struct rpmsg_lite_endpoint *	rl_ept
	)

This function deletes rpmsg endpoint and performs cleanup.

Parameters

rpmsg_lite_dev	RPMsg-Lite instance
rl_ept	Pointer to endpoint to destroy

◆ rpmsg_lite_send()

int32_t rpmsg_lite_send	(	struct rpmsg_lite_instance *	rpmsg_lite_dev,
		struct rpmsg_lite_endpoint *	ept,
		uint32_t	dst,
		char *	data,
		uint32_t	size,
		uintptr_t	timeout
	)

Sends a message contained in data field of length size to the remote endpoint with address dst. ept->addr is used as source address in the rpmsg header of the message being sent.

Parameters

rpmsg_lite_dev	RPMsg-Lite instance
ept	Sender endpoint
dst	Remote endpoint address
data	Payload buffer
size	Size of payload, in bytes
timeout	Timeout in ms, 0 if nonblocking

Returns: Status of function execution, RL_SUCCESS on success.

◆ rpmsg_lite_is_link_up()

uint32_t rpmsg_lite_is_link_up ( struct rpmsg_lite_instance * rpmsg_lite_dev )

Function to get the link state.

Parameters

rpmsg_lite_dev RPMsg-Lite instance pointer

Returns: RL_TRUE when link up, RL_FALSE when down.

◆ rpmsg_lite_wait_for_link_up()

uint32_t rpmsg_lite_wait_for_link_up	(	struct rpmsg_lite_instance *	rpmsg_lite_dev,
		uint32_t	timeout
	)

Function to wait until the link is up. Returns RL_TRUE once the link_state is set or RL_FALSE in case of timeout.

Parameters

rpmsg_lite_dev	RPMsg-Lite instance pointer
timeout	Timeout in ms, 0 if nonblocking

Returns: RL_TRUE when link up, RL_FALSE when timeout.

◆ rpmsg_lite_release_rx_buffer()

int32_t rpmsg_lite_release_rx_buffer	(	struct rpmsg_lite_instance *	rpmsg_lite_dev,
		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

rpmsg_lite_dev	RPMsg-Lite instance
rxbuf	Rx buffer with message payload

Returns: Status of function execution, RL_SUCCESS on success.

◆ rpmsg_lite_alloc_tx_buffer()

void * rpmsg_lite_alloc_tx_buffer	(	struct rpmsg_lite_instance *	rpmsg_lite_dev,
		uint32_t *	size,
		uintptr_t	timeout
	)

Allocates 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_lite_send_nocopy() function to perform data no-copy-send mechanism.

Parameters

	rpmsg_lite_dev	RPMsg-Lite instance
[in]	size	Pointer to store maximum payload size available
[in]	timeout	Integer, wait upto timeout ms or not for buffer to become available

Returns: The tx buffer address on success and RL_NULL on failure.

See also: rpmsg_lite_send_nocopy

◆ rpmsg_lite_send_nocopy()

int32_t rpmsg_lite_send_nocopy	(	struct rpmsg_lite_instance *	rpmsg_lite_dev,
		struct rpmsg_lite_endpoint *	ept,
		uint32_t	dst,
		void *	data,
		uint32_t	size
	)

Sends a message in tx buffer allocated by rpmsg_lite_alloc_tx_buffer()

This function sends txbuf of length len to the remote dst address, and uses ept->addr as the source address. The application has to take the responsibility for:

tx buffer allocation (rpmsg_lite_alloc_tx_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_lite_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_lite_send_nocopy() function fails and returns an error.

Parameters

	rpmsg_lite_dev	RPMsg-Lite instance
[in]	ept	Sender endpoint pointer
[in]	dst	Destination address
[in]	data	TX buffer with message filled
[in]	size	Length of payload

Returns: 0 on success and an appropriate error value on failure.

See also: rpmsg_lite_alloc_tx_buffer

Overview

Classes

Macros

Typedefs

Functions

Variables

Class Documentation

◆ rpmsg_hdr_reserved

◆ rpmsg_std_hdr

◆ rpmsg_std_msg

◆ rpmsg_lite_endpoint

◆ rpmsg_lite_ept_static_context

◆ rpmsg_lite_instance

Macro Definition Documentation

◆ RL_VERSION

Function Documentation

◆ rpmsg_lite_master_init()

◆ rpmsg_lite_remote_init()

◆ rpmsg_lite_deinit()

◆ rpmsg_lite_create_ept()

◆ rpmsg_lite_destroy_ept()

◆ rpmsg_lite_send()

◆ rpmsg_lite_is_link_up()

◆ rpmsg_lite_wait_for_link_up()

◆ rpmsg_lite_release_rx_buffer()

◆ rpmsg_lite_alloc_tx_buffer()

◆ rpmsg_lite_send_nocopy()