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

| RPMsg-Lite User's Guide Rev. 3.0.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-2019 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.0.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
98 struct rpmsg_lite_endpoint
99 {
100 uint32_t addr;
101 rl_ept_rx_cb_t rx_cb;
102 void *rx_cb_data;
103 void *rfu;
104 /* 16 bytes aligned on 32bit architecture */
105 };
106
110 struct rpmsg_lite_ept_static_context
111 {
112 struct rpmsg_lite_endpoint ept;
113 struct llist node;
114 };
115
122 struct rpmsg_lite_instance
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)
171 struct rpmsg_lite_instance *rpmsg_lite_master_init(
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,
238 rl_ept_rx_cb_t rx_cb,
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,
244 rl_ept_rx_cb_t rx_cb,
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_ */
rpmsg_lite_instance::lock
LOCK * lock
Definition: rpmsg_lite.h:127
rpmsg_lite_instance
Definition: rpmsg_lite.h:122
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:129
rpmsg_lite_endpoint::rfu
void * rfu
Definition: rpmsg_lite.h:103
rpmsg_lite_ept_static_context
Definition: rpmsg_lite.h:110
rpmsg_lite_instance::vq_ops
struct virtqueue_ops const * vq_ops
Definition: rpmsg_lite.h:132
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:93
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:102
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:124
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:98
rpmsg_lite_instance::sh_mem_total
uint32_t sh_mem_total
Definition: rpmsg_lite.h:131
rpmsg_lite_instance::rl_endpoints
struct llist * rl_endpoints
Definition: rpmsg_lite.h:126
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:125
rpmsg_lite_endpoint::addr
uint32_t addr
Definition: rpmsg_lite.h:100
rpmsg_lite_instance::link_state
uint32_t link_state
Definition: rpmsg_lite.h:128
rpmsg_lite_endpoint::rx_cb
rl_ept_rx_cb_t rx_cb
Definition: rpmsg_lite.h:101
rpmsg_lite_instance::sh_mem_remaining
uint32_t sh_mem_remaining
Definition: rpmsg_lite.h:130