RPMsg-Lite User's Guide  Rev. 2.2.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-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 "2.2.0"
56 /* Shared memory "allocator" parameters */
57 #define RL_WORD_SIZE (sizeof(unsigned long))
58 #define RL_WORD_ALIGN_UP(a) \
59  (((((unsigned long)a) & (RL_WORD_SIZE - 1)) != 0) ? ((((unsigned long)a) & (~(RL_WORD_SIZE - 1))) + 4) : \
60  ((unsigned long)a))
61 #define RL_WORD_ALIGN_DOWN(a) \
62  (((((unsigned long)a) & (RL_WORD_SIZE - 1)) != 0) ? (((unsigned long)a) & (~(RL_WORD_SIZE - 1))) : \
63  ((unsigned long)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 (1)
71 #define RL_FALSE (0)
72 #define RL_ADDR_ANY (0xFFFFFFFF)
73 #define RL_RELEASE (0)
74 #define RL_HOLD (1)
75 #define RL_DONT_BLOCK (0)
76 #define RL_BLOCK (0xFFFFFFFF)
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 int (*rl_ept_rx_cb_t)(void *payload, int payload_len, unsigned long src, void *priv);
96 
101 {
102  unsigned long addr;
104  void *rx_cb_data;
105  void *rfu;
106  /* 16 bytes aligned on 32bit architecture */
107 };
108 
113 {
114  struct rpmsg_lite_endpoint ept;
115  struct llist node;
116 };
117 
125 {
126  struct virtqueue *rvq;
127  struct virtqueue *tvq;
128  struct llist *rl_endpoints;
129  LOCK *lock;
130  unsigned int link_state;
131  char *sh_mem_base;
132  unsigned int sh_mem_remaining;
133  unsigned int sh_mem_total;
134  struct virtqueue_ops const *vq_ops;
135 #if defined(RL_USE_ENVIRONMENT_CONTEXT) && (RL_USE_ENVIRONMENT_CONTEXT == 1)
136  void *env;
137 #endif
138 
139 #if defined(RL_USE_STATIC_API) && (RL_USE_STATIC_API == 1)
140  struct vq_static_context vq_ctxt[2];
141 #endif
142 };
143 
144 /*******************************************************************************
145  * API
146  ******************************************************************************/
147 
148 /* Exported API functions */
149 
166 #if defined(RL_USE_STATIC_API) && (RL_USE_STATIC_API == 1)
167 struct rpmsg_lite_instance *rpmsg_lite_master_init(void *shmem_addr,
168  size_t shmem_length,
169  int link_id,
170  uint32_t init_flags,
171  struct rpmsg_lite_instance *static_context);
172 #elif defined(RL_USE_ENVIRONMENT_CONTEXT) && (RL_USE_ENVIRONMENT_CONTEXT == 1)
173 struct rpmsg_lite_instance *rpmsg_lite_master_init(void *shmem_addr,
174  size_t shmem_length,
175  int link_id,
176  uint32_t init_flags,
177  void *env_cfg);
178 #else
179 struct rpmsg_lite_instance *rpmsg_lite_master_init(void *shmem_addr,
180  size_t shmem_length,
181  int 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  int 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, int link_id, uint32_t init_flags, void *env_cfg);
207 #else
208 struct rpmsg_lite_instance *rpmsg_lite_remote_init(void *shmem_addr, int link_id, uint32_t init_flags);
209 #endif
210 
222 int rpmsg_lite_deinit(struct rpmsg_lite_instance *rpmsg_lite_dev);
223 
237 #if defined(RL_USE_STATIC_API) && (RL_USE_STATIC_API == 1)
238 struct rpmsg_lite_endpoint *rpmsg_lite_create_ept(struct rpmsg_lite_instance *rpmsg_lite_dev,
239  unsigned long addr,
241  void *rx_cb_data,
242  struct rpmsg_lite_ept_static_context *ept_context);
243 #else
244 struct rpmsg_lite_endpoint *rpmsg_lite_create_ept(struct rpmsg_lite_instance *rpmsg_lite_dev,
245  unsigned long addr,
247  void *rx_cb_data);
248 #endif
249 
257 int rpmsg_lite_destroy_ept(struct rpmsg_lite_instance *rpmsg_lite_dev, struct rpmsg_lite_endpoint *rl_ept);
258 
276 int rpmsg_lite_send(struct rpmsg_lite_instance *rpmsg_lite_dev,
277  struct rpmsg_lite_endpoint *ept,
278  unsigned long dst,
279  char *data,
280  unsigned long size,
281  unsigned long timeout);
282 
291 int rpmsg_lite_is_link_up(struct rpmsg_lite_instance *rpmsg_lite_dev);
292 
293 #if defined(RL_API_HAS_ZEROCOPY) && (RL_API_HAS_ZEROCOPY == 1)
294 
305 int rpmsg_lite_release_rx_buffer(struct rpmsg_lite_instance *rpmsg_lite_dev, void *rxbuf);
306 
323 void *rpmsg_lite_alloc_tx_buffer(struct rpmsg_lite_instance *rpmsg_lite_dev,
324  unsigned long *size,
325  unsigned long timeout);
326 
352 int rpmsg_lite_send_nocopy(struct rpmsg_lite_instance *rpmsg_lite_dev,
353  struct rpmsg_lite_endpoint *ept,
354  unsigned long dst,
355  void *data,
356  unsigned long size);
357 #endif /* RL_API_HAS_ZEROCOPY */
358 
360 
361 #if defined(__cplusplus)
362 }
363 #endif
364 
365 #endif /* _RPMSG_LITE_H */
LOCK * lock
Definition: rpmsg_lite.h:129
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...
Definition: rpmsg_lite.h:124
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...
char * sh_mem_base
Definition: rpmsg_lite.h:131
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...
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.
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()
void * rfu
Definition: rpmsg_lite.h:105
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.
Definition: rpmsg_lite.h:112
struct virtqueue_ops const * vq_ops
Definition: rpmsg_lite.h:134
unsigned int sh_mem_remaining
Definition: rpmsg_lite.h:132
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...
void * rx_cb_data
Definition: rpmsg_lite.h:104
unsigned int sh_mem_total
Definition: rpmsg_lite.h:133
unsigned int link_state
Definition: rpmsg_lite.h:130
int rpmsg_lite_is_link_up(struct rpmsg_lite_instance *rpmsg_lite_dev)
Function to get the link state.
struct virtqueue * rvq
Definition: rpmsg_lite.h:126
int(* rl_ept_rx_cb_t)(void *payload, int payload_len, unsigned long src, void *priv)
Receive callback function type.
Definition: rpmsg_lite.h:95
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 ...
Definition: rpmsg_lite.h:100
unsigned long addr
Definition: rpmsg_lite.h:102
struct llist * rl_endpoints
Definition: rpmsg_lite.h:128
struct virtqueue * tvq
Definition: rpmsg_lite.h:127
rl_ept_rx_cb_t rx_cb
Definition: rpmsg_lite.h:103
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.