| RPMsg-Lite User's Guide Rev. 2.0.2 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 int(* | rl_ept_rx_cb_t) (void *payload, int payload_len, unsigned long src, void *priv)
| Receive callback function type.

## Functions
struct rpmsg_lite_instance * | rpmsg_lite_master_init (void *shmem_addr, size_t shmem_length, int 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, int 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...
int | 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, unsigned long addr, rl_ept_rx_cb_t rx_cb, void *rx_cb_data)
| Create a new rpmsg endpoint, which can be used for communication. More...
int | 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...
int | rpmsg_lite_send (struct rpmsg_lite_instance *rpmsg_lite_dev, struct rpmsg_lite_endpoint *ept, unsigned long dst, char *data, unsigned long size, unsigned long 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...
int | rpmsg_lite_is_link_up (struct rpmsg_lite_instance *rpmsg_lite_dev)
| Function to get the link state. More...
int | 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, unsigned long *size, unsigned long timeout)
| Allocates the tx buffer for message payload. More...
int | rpmsg_lite_send_nocopy (struct rpmsg_lite_instance *rpmsg_lite_dev, struct rpmsg_lite_endpoint *ept, unsigned long dst, void *data, unsigned long 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
unsigned long | 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
unsigned int | link_state | state of the link, up/down
char * | sh_mem_base | base address of the shared memory
unsigned int | sh_mem_remaining | remaining free bytes of shared memory
unsigned int | 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,
|  | int | 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
  static_context | RPMsg-Lite preallocated context pointer, used in case of static api (RL_USE_STATIC_API)

Returns
  New RPMsg-Lite instance pointer or NULL.

struct rpmsg_lite_instance* rpmsg_lite_remote_init | ( | void * | shmem_addr,
|  | int | 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 NULL.

int 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,
|  | unsigned long | 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.

int 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

int rpmsg_lite_send | ( | struct rpmsg_lite_instance * | rpmsg_lite_dev,
|  | struct rpmsg_lite_endpoint * | ept,
|  | unsigned long | dst,
|  | char * | data,
|  | unsigned long | size,
|  | unsigned long | 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.

int 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.

int 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,
|  | unsigned long * | size,
|  | unsigned long | 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 NULL on failure.

See also
  rpmsg_lite_send_nocopy

int rpmsg_lite_send_nocopy | ( | struct rpmsg_lite_instance * | rpmsg_lite_dev,
|  | struct rpmsg_lite_endpoint * | ept,
|  | unsigned long | dst,
|  | void * | data,
|  | unsigned long | 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