RPMsg-Lite User's Guide  Rev. 3.1.0
NXP Semiconductors
rpmsg_lite.h
1 /*
2  * Copyright (c) 2014, Mentor Graphics Corporation
3  * Copyright (c) 2015 Xilinx, Inc.
4  * Copyright (c) 2016 Freescale Semiconductor, Inc.
5  * Copyright 2016-2020 NXP
6  * All rights reserved.
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions are met:
10  *
11  * 1. Redistributions of source code must retain the above copyright notice,
12  * this list of conditions and the following disclaimer.
13  * 2. Redistributions in binary form must reproduce the above copyright notice,
14  * this list of conditions and the following disclaimer in the documentation
15  * and/or other materials provided with the distribution.
16  * 3. Neither the name of the copyright holder nor the names of its
17  * contributors may be used to endorse or promote products derived from this
18  * software without specific prior written permission.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
24  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
25  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
26  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
27  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
28  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
29  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
30  * POSSIBILITY OF SUCH DAMAGE.
31  */
32 
33 #ifndef RPMSG_LITE_H_
34 #define RPMSG_LITE_H_
35 
36 #if defined(__cplusplus)
37 extern "C" {
38 #endif
39 
40 #include <stddef.h>
41 #include "virtqueue.h"
42 #include "rpmsg_env.h"
43 #include "llist.h"
44 #include "rpmsg_compiler.h"
45 #include "rpmsg_default_config.h"
46 
49 
50 /*******************************************************************************
51  * Definitions
52  ******************************************************************************/
53 
54 #define RL_VERSION "3.1.0"
56 /* Shared memory "allocator" parameters */
57 #define RL_WORD_SIZE (sizeof(uint32_t))
58 #define RL_WORD_ALIGN_UP(a) \
59  (((((uint32_t)a) & (RL_WORD_SIZE - 1U)) != 0U) ? ((((uint32_t)a) & (~(RL_WORD_SIZE - 1U))) + 4U) : ((uint32_t)a))
60 #define RL_WORD_ALIGN_DOWN(a) \
61  (((((uint32_t)a) & (RL_WORD_SIZE - 1U)) != 0U) ? (((uint32_t)a) & (~(RL_WORD_SIZE - 1U))) : ((uint32_t)a))
62 
63 /* Definitions for device types , null pointer, etc.*/
64 #define RL_SUCCESS (0)
65 #define RL_NULL ((void *)0)
66 #define RL_REMOTE (0)
67 #define RL_MASTER (1)
68 #define RL_TRUE (1U)
69 #define RL_FALSE (0U)
70 #define RL_ADDR_ANY (0xFFFFFFFFU)
71 #define RL_RELEASE (0)
72 #define RL_HOLD (1)
73 #define RL_DONT_BLOCK (0)
74 #define RL_BLOCK (0xFFFFFFFFU)
75 
76 /* Error macros. */
77 #define RL_ERRORS_BASE (-5000)
78 #define RL_ERR_NO_MEM (RL_ERRORS_BASE - 1)
79 #define RL_ERR_BUFF_SIZE (RL_ERRORS_BASE - 2)
80 #define RL_ERR_PARAM (RL_ERRORS_BASE - 3)
81 #define RL_ERR_DEV_ID (RL_ERRORS_BASE - 4)
82 #define RL_ERR_MAX_VQ (RL_ERRORS_BASE - 5)
83 #define RL_ERR_NO_BUFF (RL_ERRORS_BASE - 6)
84 #define RL_NOT_READY (RL_ERRORS_BASE - 7)
85 #define RL_ALREADY_DONE (RL_ERRORS_BASE - 8)
86 
87 /* Init flags */
88 #define RL_NO_FLAGS (0)
89 
93 typedef int32_t (*rl_ept_rx_cb_t)(void *payload, uint32_t payload_len, uint32_t src, void *priv);
94 
99 {
100  uint32_t addr;
102  void *rx_cb_data;
103  void *rfu;
104  /* 16 bytes aligned on 32bit architecture */
105 };
106 
111 {
112  struct rpmsg_lite_endpoint ept;
113  struct llist node;
114 };
115 
123 {
124  struct virtqueue *rvq;
125  struct virtqueue *tvq;
126  struct llist *rl_endpoints;
127  LOCK *lock;
128  uint32_t link_state;
129  char *sh_mem_base;
130  uint32_t sh_mem_remaining;
131  uint32_t sh_mem_total;
132  struct virtqueue_ops const *vq_ops;
133 #if defined(RL_USE_ENVIRONMENT_CONTEXT) && (RL_USE_ENVIRONMENT_CONTEXT == 1)
134  void *env;
135 #endif
136 
137 #if defined(RL_USE_STATIC_API) && (RL_USE_STATIC_API == 1)
138  struct vq_static_context vq_ctxt[2];
139 #endif
140 };
141 
142 /*******************************************************************************
143  * API
144  ******************************************************************************/
145 
146 /* Exported API functions */
147 
164 #if defined(RL_USE_STATIC_API) && (RL_USE_STATIC_API == 1)
165 struct rpmsg_lite_instance *rpmsg_lite_master_init(void *shmem_addr,
166  size_t shmem_length,
167  uint32_t link_id,
168  uint32_t init_flags,
169  struct rpmsg_lite_instance *static_context);
170 #elif defined(RL_USE_ENVIRONMENT_CONTEXT) && (RL_USE_ENVIRONMENT_CONTEXT == 1)
172  void *shmem_addr, size_t shmem_length, uint32_t link_id, uint32_t init_flags, void *env_cfg);
173 #else
174 struct rpmsg_lite_instance *rpmsg_lite_master_init(void *shmem_addr,
175  size_t shmem_length,
176  uint32_t link_id,
177  uint32_t init_flags);
178 #endif
179 
195 #if defined(RL_USE_STATIC_API) && (RL_USE_STATIC_API == 1)
196 struct rpmsg_lite_instance *rpmsg_lite_remote_init(void *shmem_addr,
197  uint32_t link_id,
198  uint32_t init_flags,
199  struct rpmsg_lite_instance *static_context);
200 #elif defined(RL_USE_ENVIRONMENT_CONTEXT) && (RL_USE_ENVIRONMENT_CONTEXT == 1)
201 struct rpmsg_lite_instance *rpmsg_lite_remote_init(void *shmem_addr,
202  uint32_t link_id,
203  uint32_t init_flags,
204  void *env_cfg);
205 #else
206 struct rpmsg_lite_instance *rpmsg_lite_remote_init(void *shmem_addr, uint32_t link_id, uint32_t init_flags);
207 #endif
208 
220 int32_t rpmsg_lite_deinit(struct rpmsg_lite_instance *rpmsg_lite_dev);
221 
235 #if defined(RL_USE_STATIC_API) && (RL_USE_STATIC_API == 1)
236 struct rpmsg_lite_endpoint *rpmsg_lite_create_ept(struct rpmsg_lite_instance *rpmsg_lite_dev,
237  uint32_t addr,
239  void *rx_cb_data,
240  struct rpmsg_lite_ept_static_context *ept_context);
241 #else
242 struct rpmsg_lite_endpoint *rpmsg_lite_create_ept(struct rpmsg_lite_instance *rpmsg_lite_dev,
243  uint32_t addr,
245  void *rx_cb_data);
246 #endif
247 
255 int32_t rpmsg_lite_destroy_ept(struct rpmsg_lite_instance *rpmsg_lite_dev, struct rpmsg_lite_endpoint *rl_ept);
256 
274 int32_t rpmsg_lite_send(struct rpmsg_lite_instance *rpmsg_lite_dev,
275  struct rpmsg_lite_endpoint *ept,
276  uint32_t dst,
277  char *data,
278  uint32_t size,
279  uint32_t timeout);
280 
289 int32_t rpmsg_lite_is_link_up(struct rpmsg_lite_instance *rpmsg_lite_dev);
290 
291 #if defined(RL_API_HAS_ZEROCOPY) && (RL_API_HAS_ZEROCOPY == 1)
292 
303 int32_t rpmsg_lite_release_rx_buffer(struct rpmsg_lite_instance *rpmsg_lite_dev, void *rxbuf);
304 
321 void *rpmsg_lite_alloc_tx_buffer(struct rpmsg_lite_instance *rpmsg_lite_dev, uint32_t *size, uint32_t timeout);
322 
348 int32_t rpmsg_lite_send_nocopy(struct rpmsg_lite_instance *rpmsg_lite_dev,
349  struct rpmsg_lite_endpoint *ept,
350  uint32_t dst,
351  void *data,
352  uint32_t size);
353 #endif /* RL_API_HAS_ZEROCOPY */
354 
356 
357 #if defined(__cplusplus)
358 }
359 #endif
360 
361 #endif /* RPMSG_LITE_H_ */
LOCK * lock
Definition: rpmsg_lite.h:127
Definition: rpmsg_lite.h:122
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...
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_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()
char * sh_mem_base
Definition: rpmsg_lite.h:129
void * rfu
Definition: rpmsg_lite.h:103
Definition: rpmsg_lite.h:110
struct virtqueue_ops const * vq_ops
Definition: rpmsg_lite.h:132
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_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 ...
int32_t(* rl_ept_rx_cb_t)(void *payload, uint32_t payload_len, uint32_t src, void *priv)
Receive callback function type.
Definition: rpmsg_lite.h:93
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...
void * rx_cb_data
Definition: rpmsg_lite.h:102
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...
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...
struct virtqueue * rvq
Definition: rpmsg_lite.h:124
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.
Definition: rpmsg_lite.h:98
uint32_t sh_mem_total
Definition: rpmsg_lite.h:131
struct llist * rl_endpoints
Definition: rpmsg_lite.h:126
int32_t rpmsg_lite_is_link_up(struct rpmsg_lite_instance *rpmsg_lite_dev)
Function to get the link state.
struct virtqueue * tvq
Definition: rpmsg_lite.h:125
uint32_t addr
Definition: rpmsg_lite.h:100
uint32_t link_state
Definition: rpmsg_lite.h:128
rl_ept_rx_cb_t rx_cb
Definition: rpmsg_lite.h:101
uint32_t sh_mem_remaining
Definition: rpmsg_lite.h:130