RPMsg-Lite User's Guide: RPMsg Queue Component

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

- Main Page
- API Reference

Typedefs | Functions
RPMsg Queue Component

This section describes the RPMsg Queue component that allows: More...

## Overview

This section describes the RPMsg Queue component that allows:

- Blocking reception.
- Zero-copy blocking reception.

## Typedefs
typedef void * | rpmsg_queue_handle
| Rpmsg queue handle type.

## Functions
int32_t | rpmsg_queue_rx_cb (void *payload, uint32_t payload_len, uint32_t src, void *priv)
| This callback needs to be registered with an endpoint. More...
rpmsg_queue_handle | rpmsg_queue_create (struct rpmsg_lite_instance *rpmsg_lite_dev)
| Create a RPMsg queue which can be used for blocking reception. More...
int32_t | rpmsg_queue_destroy (struct rpmsg_lite_instance *rpmsg_lite_dev, rpmsg_queue_handle q)
| Destroy a queue and clean up. Do not destroy a queue which is registered with an active endpoint! More...
int32_t | rpmsg_queue_recv (struct rpmsg_lite_instance *rpmsg_lite_dev, rpmsg_queue_handle q, uint32_t *src, char *data, uint32_t maxlen, uint32_t *len, uint32_t timeout)
| blocking receive function - blocking version of the received function that can be called from an RTOS task. The data is copied from the receive buffer into the user supplied buffer. More...
int32_t | rpmsg_queue_recv_nocopy (struct rpmsg_lite_instance *rpmsg_lite_dev, rpmsg_queue_handle q, uint32_t *src, char **data, uint32_t *len, uint32_t timeout)
| blocking receive function - blocking version of the received function that can be called from an RTOS task. The data is NOT copied into the user-app. buffer. More...
int32_t | rpmsg_queue_nocopy_free (struct rpmsg_lite_instance *rpmsg_lite_dev, void *data)
| This function frees a buffer previously returned by rpmsg_queue_recv_nocopy(). More...
int32_t | rpmsg_queue_get_current_size (rpmsg_queue_handle q)
| This function returns the number of pending messages in the queue. More...

## Function Documentation

int32_t rpmsg_queue_rx_cb | ( | void * | payload,
|  | uint32_t | payload_len,
|  | uint32_t | src,
|  | void * | priv
| ) |  |

This callback needs to be registered with an endpoint.

Parameters

  payload | Pointer to the buffer containing received data
  payload_len | Size of data received, in bytes
  src | Pointer to address of the endpoint from which data is received
  priv | Private data provided during endpoint creation

Returns
  RL_HOLD or RL_RELEASE to release or hold the buffer in payload

rpmsg_queue_handle rpmsg_queue_create | ( | struct rpmsg_lite_instance * | rpmsg_lite_dev | ) |

Create a RPMsg queue which can be used for blocking reception.

Parameters

  rpmsg_lite_dev | RPMsg Lite instance
  queue_storage | RPMsg Lite queue static storage pointer
  queue_ctxt | RPMsg Lite queue static context holder

Returns
  RPMsg queue handle or RL_NULL

int32_t rpmsg_queue_destroy | ( | struct rpmsg_lite_instance * | rpmsg_lite_dev,
|  | rpmsg_queue_handle | q
| ) |  |

Destroy a queue and clean up. Do not destroy a queue which is registered with an active endpoint!

Parameters

  | rpmsg_lite_dev | RPMsg-Lite instance
  [in] | q | RPMsg queue handle to destroy

Returns
  Status of function execution

int32_t rpmsg_queue_recv | ( | struct rpmsg_lite_instance * | rpmsg_lite_dev,
|  | rpmsg_queue_handle | q,
|  | uint32_t * | src,
|  | char * | data,
|  | uint32_t | maxlen,
|  | uint32_t * | len,
|  | uint32_t | timeout
| ) |  |

blocking receive function - blocking version of the received function that can be called from an RTOS task. The data is copied from the receive buffer into the user supplied buffer.

This is the "receive with copy" version of the RPMsg receive function. This version is simple to use but it requires copying data from shared memory into the user space buffer. The user has no obligation or burden to manage the shared memory buffers.

Parameters

  | rpmsg_lite_dev | RPMsg-Lite instance
  [in] | q | RPMsg queue handle to listen on
  [in] | data | Pointer to the user buffer the received data are copied to
  [out] | len | Pointer to an int variable that will contain the number of bytes actually copied into the buffer
  [in] | maxlen | Maximum number of bytes to copy (received buffer size)
  [out] | src | Pointer to address of the endpoint from which data is received
  [in] | timeout | Timeout, in milliseconds, to wait for a message. A value of 0 means don't wait (non-blocking call). A value of 0xffffffff means wait forever (blocking call).

Returns
  Status of function execution

See also
  rpmsg_queue_recv_nocopy

int32_t rpmsg_queue_recv_nocopy | ( | struct rpmsg_lite_instance * | rpmsg_lite_dev,
|  | rpmsg_queue_handle | q,
|  | uint32_t * | src,
|  | char ** | data,
|  | uint32_t * | len,
|  | uint32_t | timeout
| ) |  |

blocking receive function - blocking version of the received function that can be called from an RTOS task. The data is NOT copied into the user-app. buffer.

This is the "zero-copy receive" version of the RPMsg receive function. No data is copied. Only the pointer to the data is returned. This version is fast, but it requires the user to manage buffer allocation. Specifically, the user must decide when a buffer is no longer in use and make the appropriate API call to free it, see rpmsg_queue_nocopy_free().

Parameters

  | rpmsg_lite_dev | RPMsg Lite instance
  [in] | q | RPMsg queue handle to listen on
  [out] | data | Pointer to the RPMsg buffer of the shared memory where the received data is stored
  [out] | len | Pointer to an int variable that that will contain the number of valid bytes in the RPMsg buffer
  [out] | src | Pointer to address of the endpoint from which data is received
  [in] | timeout | Timeout, in milliseconds, to wait for a message. A value of 0 means don't wait (non-blocking call). A value of 0xffffffff means wait forever (blocking call).

Returns
  Status of function execution.

See also
  rpmsg_queue_nocopy_free
  rpmsg_queue_recv

int32_t rpmsg_queue_nocopy_free | ( | struct rpmsg_lite_instance * | rpmsg_lite_dev,
|  | void * | data
| ) |  |

This function frees a buffer previously returned by rpmsg_queue_recv_nocopy().

Once the zero-copy mechanism of receiving data is used, this function has to be called to free a buffer and to make it available for the next data transfer.

Parameters

  | rpmsg_lite_dev | RPMsg-Lite instance
  [in] | data | Pointer to the RPMsg buffer of the shared memory that has to be freed

Returns
  Status of function execution.

See also
  rpmsg_queue_recv_nocopy

int32_t rpmsg_queue_get_current_size | ( | rpmsg_queue_handle | q | ) |

This function returns the number of pending messages in the queue.

Parameters

  [in] | q | RPMsg queue handle

Returns
  Number of pending messages in the queue.