RPMsg-Lite User's Guide: RPMsg-Lite Core Component

| RPMsg-Lite User's Guide Rev. 3.0.0 NXP Semiconductors

- Main Page
- API Reference

Classes | Macros | Typedefs | Functions
RPMsg-Lite Core Component

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_lite_endpoint
struct | rpmsg_lite_ept_static_context
struct | rpmsg_lite_instance

## Macros
#define | RL_VERSION
#define | RL_WORD_SIZE
#define | RL_WORD_ALIGN_UP(a)
#define | RL_WORD_ALIGN_DOWN(a)
#define | RL_SUCCESS
#define | RL_NULL
#define | RL_REMOTE
#define | RL_MASTER
#define | RL_TRUE
#define | RL_FALSE
#define | RL_ADDR_ANY
#define | RL_RELEASE
#define | RL_HOLD
#define | RL_DONT_BLOCK
#define | RL_BLOCK
#define | RL_ERRORS_BASE
#define | RL_ERR_NO_MEM
#define | RL_ERR_BUFF_SIZE
#define | RL_ERR_PARAM
#define | RL_ERR_DEV_ID
#define | RL_ERR_MAX_VQ
#define | RL_ERR_NO_BUFF
#define | RL_NOT_READY
#define | RL_ALREADY_DONE
#define | RL_NO_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. More...
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. More...
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. More...
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. More...
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. More...
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, uint32_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. More...
int32_t | rpmsg_lite_is_link_up (struct rpmsg_lite_instance *rpmsg_lite_dev)
| Function to get the link state. More...
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. More...
void * | rpmsg_lite_alloc_tx_buffer (struct rpmsg_lite_instance *rpmsg_lite_dev, uint32_t *size, uint32_t timeout)
| Allocates the tx buffer for message payload. More...
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() More...

## Class Documentation

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

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

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 | remaining free bytes of shared memory
uint32_t | sh_mem_total | total size of shared memory
struct virtqueue_ops const * | vq_ops | ops functions table pointer

## Macro Definition Documentation

#define RL_VERSION

Current RPMsg Lite version

## Function Documentation

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
  env_cfg | Initialization data for the environement RPMsg-Lite layer, used when the environment layer uses its own context (RL_USE_ENVIRONMENT_CONTEXT)
  static_context | RPMsg-Lite preallocated context pointer, used in case of static api (RL_USE_STATIC_API)

Returns
  New RPMsg-Lite instance pointer or RL_NULL.

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
  env_cfg | Initialization data for the environement RPMsg-Lite layer, used when the environment layer uses its own context (RL_USE_ENVIRONMENT_CONTEXT)
  static_context | RPMsg-Lite preallocated context pointer, used in case of static api (RL_USE_STATIC_API)

Returns
  New RPMsg-Lite instance pointer or RL_NULL.

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.

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
  ept_context | Endpoint preallocated context pointer, used in case of static api (RL_USE_STATIC_API)

Returns
  RL_NULL on error, new endpoint pointer on success.

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

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,
|  | uint32_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.

int32_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

Returns
  True when link up, false when down.

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.

void* rpmsg_lite_alloc_tx_buffer | ( | struct rpmsg_lite_instance * | rpmsg_lite_dev,
|  | uint32_t * | size,
|  | uint32_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

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:

1. tx buffer allocation (rpmsg_lite_alloc_tx_buffer())
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 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