RPMSG_Adapter

Overview

Data Structures
struct	hal_rpmsg_config_t
	The configure structure of RPMSG adapter. More...

Macros
#define	HAL_RPMSG_SELECT_ROLE   (1U)
	RPMSG Msaster/Remote role definition (0 - Master, 1 - Remote)
#define	HAL_RPMSG_HANDLE_SIZE   (52U)
	RPMSG handle size definition.
#define	RPMSG_HANDLE_DEFINE(name)   uint32_t name[((HAL_RPMSG_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))]
	Defines the rpmsg handle. More...

Typedefs
typedef void *	hal_rpmsg_handle_t
	The handle of RPMSG adapter.
typedef hal_rpmsg_return_status_t(*	rpmsg_rx_callback_t )(void *param, uint8_t *data, uint32_t len)
	The callback function of RPMSG adapter. More...

Enumerations
enum	hal_rpmsg_status_t
	RPMSG status.
enum	hal_rpmsg_return_status_t
	RPMSG return status.

Functions
hal_rpmsg_status_t	HAL_RpmsgMcmgrInit (void)
	Initializes the RPMSG adapter module for dual core communication. More...
hal_rpmsg_status_t	HAL_RpmsgInit (hal_rpmsg_handle_t handle, hal_rpmsg_config_t *config)
	Initializes the RPMSG adapter for RPMSG channel configure. More...
hal_rpmsg_status_t	HAL_RpmsgDeinit (hal_rpmsg_handle_t handle)
	DeInitilizate the RPMSG adapter module. More...
hal_rpmsg_status_t	HAL_RpmsgSend (hal_rpmsg_handle_t handle, uint8_t *data, uint32_t length)
	Send data to another RPMSG module. More...
void *	HAL_RpmsgAllocTxBuffer (hal_rpmsg_handle_t handle, uint32_t size)
	Allocates the tx buffer for message payload. More...
hal_rpmsg_status_t	HAL_RpmsgNoCopySend (hal_rpmsg_handle_t handle, uint8_t *data, uint32_t length)
	Send data with NoCopy to another RPMSG module. More...
hal_rpmsg_status_t	HAL_RpmsgFreeRxBuffer (hal_rpmsg_handle_t handle, uint8_t *data)
	Releases the rx buffer for future reuse in vring. More...
hal_rpmsg_status_t	HAL_RpmsgInstallRxCallback (hal_rpmsg_handle_t handle, rpmsg_rx_callback_t callback, void *param)
	Install RPMSG rx callback. More...
hal_rpmsg_status_t	HAL_RpmsgEnterLowpower (hal_rpmsg_handle_t handle)
	Prepares to enter low power consumption. More...
hal_rpmsg_status_t	HAL_RpmsgExitLowpower (hal_rpmsg_handle_t handle)
	Prepares to exit low power consumption. More...

---

Data Structure Documentation

struct hal_rpmsg_config_t

Macro Definition Documentation

#define RPMSG_HANDLE_DEFINE

(

name

)

uint32_t name[((HAL_RPMSG_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))]

This macro is used to define a 4 byte aligned rpmsg handle. Then use "(hal_rpmsg_handle_t)name" to get the rpmsg handle.

The macro should be global and could be optional. You could also define rpmsg handle by yourself.

This is an example,

* RPMSG_HANDLE_DEFINE(rpmsgHandle);
* 

Parameters

name	The name string of the rpmsg handle.

Typedef Documentation

typedef hal_rpmsg_return_status_t(* rpmsg_rx_callback_t)(void *param, uint8_t *data, uint32_t len)

Note

If Rpmsg RX callback function return kStatus_HAL_RL_RELEASE mode, no need to call HAL_RpmsgFreeRxBuffer.

If Rpmsg RX callback function return kStatus_HAL_RL_HOLD mode,then need to call HAL_RpmsgFreeRxBuffer.

Function Documentation

hal_rpmsg_status_t HAL_RpmsgMcmgrInit

(

void

)

Note

This API should be called at the beginning of the application using the RPMSG adapter driver.

Return values

kStatus_HAL_RpmsgSuccess

RPMSG module initialize succeed.

hal_rpmsg_status_t HAL_RpmsgInit	(	hal_rpmsg_handle_t	handle,
		hal_rpmsg_config_t *	config
	)

Note

This API should be called to software RPMSG communication configure, and it be called whenever application need it.

Parameters

handle	Pointer to point to a memory space of size HAL_RPMSG_HANDLE_SIZE allocated by the caller. The handle should be 4 byte aligned, because unaligned access doesn't be supported on some devices. You can define the handle in the following two ways: RPMSG_HANDLE_DEFINE(handle); or uint32_t handle[((HAL_RPMSG_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))];
config	Used for config local/remote endpoint addr.

Return values

kStatus_HAL_RpmsgSuccess

RPMSG module initialize succeed.

hal_rpmsg_status_t HAL_RpmsgDeinit

(

hal_rpmsg_handle_t

handle

)

Note

This API should be called when not using the RPMSG adapter driver anymore.

Parameters

handle

RPMSG handle pointer.

Return values

kStatus_HAL_RpmsgSuccess

RPMSG module deinitialize succeed.

hal_rpmsg_status_t HAL_RpmsgSend	(	hal_rpmsg_handle_t	handle,
		uint8_t *	data,
		uint32_t	length
	)

This function will send a specified length of data to another core by RPMSG.

Note

This API should be called to send data.

Parameters

handle	RPMSG handle pointer.
data	Pointer to where the send data from.
length	The send data length.

Return values

kStatus_HAL_RpmsgSuccess

RPMSG send data succeed.

void* HAL_RpmsgAllocTxBuffer	(	hal_rpmsg_handle_t	handle,
		uint32_t	size
	)

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

handle	RPMSG handle pointer.
size	The send data length.

Return values

The	tx buffer address on success and RL_NULL on failure.

hal_rpmsg_status_t HAL_RpmsgNoCopySend	(	hal_rpmsg_handle_t	handle,
		uint8_t *	data,
		uint32_t	length
	)

This function will send a specified length of data to another core by RPMSG. 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:

1. tx buffer allocation (HAL_RpmsgAllocTxBuffer())
2. filling the data to be sent into the pre-allocated tx buffer
3. not exceeding the buffer size when filling the data
4. data cache coherency

After the HAL_RpmsgNoCopySend() function is issued the tx buffer is no more owned by the sending task and must not be touched anymore unless the HAL_RpmsgNoCopySend() function fails and returns an error.

Note

This API should be called to send data.

Parameters

handle	RPMSG handle pointer.
data	Pointer to where the send data from.
length	The send data length.

Return values

kStatus_HAL_RpmsgSuccess

RPMSG send data succeed.

hal_rpmsg_status_t HAL_RpmsgFreeRxBuffer	(	hal_rpmsg_handle_t	handle,
		uint8_t *	data
	)

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

Note

The HAL_RpmsgFreeRxBuffer need be called only if Rpmsg RX callback function return kStatus_HAL_RL_HOLD mode.

Parameters

handle	RPMSG handle pointer.
data	Pointer to where the received data from perr.

Returns

Status of function execution, RL_SUCCESS on success.

hal_rpmsg_status_t HAL_RpmsgInstallRxCallback	(	hal_rpmsg_handle_t	handle,
		rpmsg_rx_callback_t	callback,
		void *	param
	)

Note

The function must be called because rpmsg adapter just support asynchronous receive mode should make sure the callback function is installed before the data received from peer soc, and the rx callback function will be called when the rx process complete.

Parameters

handle

RPMSG handle pointer.

Return values

kStatus_HAL_RpmsgSuccess

RPMSG install rx callback succeed.

hal_rpmsg_status_t HAL_RpmsgEnterLowpower

(

hal_rpmsg_handle_t

handle

)

This function is used to prepare to enter low power consumption.

Parameters

handle

RPMSG handle pointer.

Return values

kStatus_HAL_RpmsgSuccess	Successful operation.
kStatus_HAL_RpmsgError	An error occurred.

hal_rpmsg_status_t HAL_RpmsgExitLowpower

(

hal_rpmsg_handle_t

handle

)

This function is used to restore from low power consumption.

Parameters

handle

RPMSG handle pointer.

Return values

kStatus_HAL_RpmsgSuccess	Successful operation.
kStatus_HAL_RpmsgError	An error occurred.