RPMsg-Lite User's Guide: rpmsg_lite.h Source File

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

- Main Page
- API Reference

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-2021 NXP
6 * Copyright 2021 ACRIOS Systems s.r.o.
7 * All rights reserved.
8 *
9 * Redistribution and use in source and binary forms, with or without
10 * modification, are permitted provided that the following conditions are met:
11 *
12 * 1. Redistributions of source code must retain the above copyright notice,
13 * this list of conditions and the following disclaimer.
14 * 2. Redistributions in binary form must reproduce the above copyright notice,
15 * this list of conditions and the following disclaimer in the documentation
16 * and/or other materials provided with the distribution.
17 * 3. Neither the name of the copyright holder nor the names of its
18 * contributors may be used to endorse or promote products derived from this
19 * software without specific prior written permission.
20 *
21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
22 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
25 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
26 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
27 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
28 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
29 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
30 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
31 * POSSIBILITY OF SUCH DAMAGE.
32 */
33
34 #ifndef RPMSG_LITE_H_
35 #define RPMSG_LITE_H_
36
37 #if defined(__cplusplus)
38 extern "C" {
39 #endif
40
41 #include <stddef.h>
42 #include "virtqueue.h"
43 #include "rpmsg_env.h"
44 #include "llist.h"
45 #include "rpmsg_compiler.h"
46 #include "rpmsg_default_config.h"
47
50
51 /*******************************************************************************
52 * Definitions
53 ******************************************************************************/
54
55 #define RL_VERSION "3.2.0"
57 /* Shared memory "allocator" parameters */
58 #define RL_WORD_SIZE (sizeof(uint32_t))
59 #define RL_WORD_ALIGN_UP(a) \
60 (((((uint32_t)(a)) & (RL_WORD_SIZE - 1U)) != 0U) ? ((((uint32_t)(a)) & (~(RL_WORD_SIZE - 1U))) + 4U) : \
61 ((uint32_t)(a)))
62 #define RL_WORD_ALIGN_DOWN(a) \
63 (((((uint32_t)(a)) & (RL_WORD_SIZE - 1U)) != 0U) ? (((uint32_t)(a)) & (~(RL_WORD_SIZE - 1U))) : ((uint32_t)(a)))
64
65 /* Definitions for device types , null pointer, etc.*/
66 #define RL_SUCCESS (0)
67 #define RL_NULL ((void *)0)
68 #define RL_REMOTE (0)
69 #define RL_MASTER (1)
70 #define RL_TRUE (1U)
71 #define RL_FALSE (0U)
72 #define RL_ADDR_ANY (0xFFFFFFFFU)
73 #define RL_RELEASE (0)
74 #define RL_HOLD (1)
75 #define RL_DONT_BLOCK (0)
76 #define RL_BLOCK (0xFFFFFFFFU)
77
78 /* Error macros. */
79 #define RL_ERRORS_BASE (-5000)
80 #define RL_ERR_NO_MEM (RL_ERRORS_BASE - 1)
81 #define RL_ERR_BUFF_SIZE (RL_ERRORS_BASE - 2)
82 #define RL_ERR_PARAM (RL_ERRORS_BASE - 3)
83 #define RL_ERR_DEV_ID (RL_ERRORS_BASE - 4)
84 #define RL_ERR_MAX_VQ (RL_ERRORS_BASE - 5)
85 #define RL_ERR_NO_BUFF (RL_ERRORS_BASE - 6)
86 #define RL_NOT_READY (RL_ERRORS_BASE - 7)
87 #define RL_ALREADY_DONE (RL_ERRORS_BASE - 8)
88
89 /* Init flags */
90 #define RL_NO_FLAGS (0)
91
95 typedef int32_t (*rl_ept_rx_cb_t)(void *payload, uint32_t payload_len, uint32_t src, void *priv);
96
100 struct rpmsg_lite_endpoint
101 {
102 uint32_t addr;
103 rl_ept_rx_cb_t rx_cb;
104 void *rx_cb_data;
105 void *rfu;
106 /* 16 bytes aligned on 32bit architecture */
107 };
108
112 struct rpmsg_lite_ept_static_context
113 {
114 struct rpmsg_lite_endpoint ept;
115 struct llist node;
116 };
117
124 struct rpmsg_lite_instance
125 {
126 struct virtqueue *rvq;
127 struct virtqueue *tvq;
128 struct llist *rl_endpoints;
129 LOCK *lock;
130 #if defined(RL_USE_STATIC_API) && (RL_USE_STATIC_API == 1)
131 LOCK_STATIC_CONTEXT lock_static_ctxt;
132 #endif
133 uint32_t link_state;
134 char *sh_mem_base;
135 uint32_t sh_mem_remaining;
136 uint32_t sh_mem_total;
137 struct virtqueue_ops const *vq_ops;
138 #if defined(RL_USE_ENVIRONMENT_CONTEXT) && (RL_USE_ENVIRONMENT_CONTEXT == 1)
139 void *env;
140 #endif
141
142 #if defined(RL_USE_STATIC_API) && (RL_USE_STATIC_API == 1)
143 struct vq_static_context vq_ctxt[2];
144 #endif
145 };
146
147 /*******************************************************************************
148 * API
149 ******************************************************************************/
150
151 /* Exported API functions */
152
169 #if defined(RL_USE_STATIC_API) && (RL_USE_STATIC_API == 1)
170 struct rpmsg_lite_instance *rpmsg_lite_master_init(void *shmem_addr,
171 size_t shmem_length,
172 uint32_t link_id,
173 uint32_t init_flags,
174 struct rpmsg_lite_instance *static_context);
175 #elif defined(RL_USE_ENVIRONMENT_CONTEXT) && (RL_USE_ENVIRONMENT_CONTEXT == 1)
176 struct rpmsg_lite_instance *rpmsg_lite_master_init(
177 void *shmem_addr, size_t shmem_length, uint32_t link_id, uint32_t init_flags, void *env_cfg);
178 #else
179 struct rpmsg_lite_instance *rpmsg_lite_master_init(void *shmem_addr,
180 size_t shmem_length,
181 uint32_t link_id,
182 uint32_t init_flags);
183 #endif
184
200 #if defined(RL_USE_STATIC_API) && (RL_USE_STATIC_API == 1)
201 struct rpmsg_lite_instance *rpmsg_lite_remote_init(void *shmem_addr,
202 uint32_t link_id,
203 uint32_t init_flags,
204 struct rpmsg_lite_instance *static_context);
205 #elif defined(RL_USE_ENVIRONMENT_CONTEXT) && (RL_USE_ENVIRONMENT_CONTEXT == 1)
206 struct rpmsg_lite_instance *rpmsg_lite_remote_init(void *shmem_addr,
207 uint32_t link_id,
208 uint32_t init_flags,
209 void *env_cfg);
210 #else
211 struct rpmsg_lite_instance *rpmsg_lite_remote_init(void *shmem_addr, uint32_t link_id, uint32_t init_flags);
212 #endif
213
225 int32_t rpmsg_lite_deinit(struct rpmsg_lite_instance *rpmsg_lite_dev);
226
240 #if defined(RL_USE_STATIC_API) && (RL_USE_STATIC_API == 1)
241 struct rpmsg_lite_endpoint *rpmsg_lite_create_ept(struct rpmsg_lite_instance *rpmsg_lite_dev,
242 uint32_t addr,
243 rl_ept_rx_cb_t rx_cb,
244 void *rx_cb_data,
245 struct rpmsg_lite_ept_static_context *ept_context);
246 #else
247 struct rpmsg_lite_endpoint *rpmsg_lite_create_ept(struct rpmsg_lite_instance *rpmsg_lite_dev,
248 uint32_t addr,
249 rl_ept_rx_cb_t rx_cb,
250 void *rx_cb_data);
251 #endif
252
260 int32_t rpmsg_lite_destroy_ept(struct rpmsg_lite_instance *rpmsg_lite_dev, struct rpmsg_lite_endpoint *rl_ept);
261
279 int32_t rpmsg_lite_send(struct rpmsg_lite_instance *rpmsg_lite_dev,
280 struct rpmsg_lite_endpoint *ept,
281 uint32_t dst,
282 char *data,
283 uint32_t size,
284 uint32_t timeout);
285
294 int32_t rpmsg_lite_is_link_up(struct rpmsg_lite_instance *rpmsg_lite_dev);
295
296 #if defined(RL_API_HAS_ZEROCOPY) && (RL_API_HAS_ZEROCOPY == 1)
297
308 int32_t rpmsg_lite_release_rx_buffer(struct rpmsg_lite_instance *rpmsg_lite_dev, void *rxbuf);
309
326 void *rpmsg_lite_alloc_tx_buffer(struct rpmsg_lite_instance *rpmsg_lite_dev, uint32_t *size, uint32_t timeout);
327
353 int32_t rpmsg_lite_send_nocopy(struct rpmsg_lite_instance *rpmsg_lite_dev,
354 struct rpmsg_lite_endpoint *ept,
355 uint32_t dst,
356 void *data,
357 uint32_t size);
358 #endif /* RL_API_HAS_ZEROCOPY */
359
361
362 #if defined(__cplusplus)
363 }
364 #endif
365
366 #endif /* RPMSG_LITE_H_ */
rpmsg_lite_instance::lock
LOCK * lock
Definition: rpmsg_lite.h:129
rpmsg_lite_instance
Definition: rpmsg_lite.h:124
rpmsg_lite_send
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...
rpmsg_lite_destroy_ept
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.
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()
rpmsg_lite_instance::sh_mem_base
char * sh_mem_base
Definition: rpmsg_lite.h:134
rpmsg_lite_endpoint::rfu
void * rfu
Definition: rpmsg_lite.h:105
rpmsg_lite_ept_static_context
Definition: rpmsg_lite.h:112
rpmsg_lite_instance::vq_ops
struct virtqueue_ops const * vq_ops
Definition: rpmsg_lite.h:137
rpmsg_lite_create_ept
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.
rpmsg_lite_release_rx_buffer
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 ...
rl_ept_rx_cb_t
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:95
rpmsg_lite_deinit
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...
rpmsg_lite_endpoint::rx_cb_data
void * rx_cb_data
Definition: rpmsg_lite.h:104
rpmsg_default_config.h
rpmsg_lite_master_init
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...
rpmsg_lite_remote_init
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...
rpmsg_lite_instance::rvq
struct virtqueue * rvq
Definition: rpmsg_lite.h:126
rpmsg_lite_alloc_tx_buffer
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.
rpmsg_lite_endpoint
Definition: rpmsg_lite.h:100
rpmsg_lite_instance::sh_mem_total
uint32_t sh_mem_total
Definition: rpmsg_lite.h:136
rpmsg_lite_instance::rl_endpoints
struct llist * rl_endpoints
Definition: rpmsg_lite.h:128
rpmsg_lite_is_link_up
int32_t rpmsg_lite_is_link_up(struct rpmsg_lite_instance *rpmsg_lite_dev)
Function to get the link state.
rpmsg_lite_instance::tvq
struct virtqueue * tvq
Definition: rpmsg_lite.h:127
rpmsg_lite_endpoint::addr
uint32_t addr
Definition: rpmsg_lite.h:102
rpmsg_lite_instance::link_state
uint32_t link_state
Definition: rpmsg_lite.h:133
rpmsg_lite_endpoint::rx_cb
rl_ept_rx_cb_t rx_cb
Definition: rpmsg_lite.h:103
rpmsg_lite_instance::sh_mem_remaining
uint32_t sh_mem_remaining
Definition: rpmsg_lite.h:135