1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
|
/*
* Copyright (c) 2015 Freescale Semiconductor, Inc. All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* 1. Redistributions of source code must retain the above copyright notice,
* this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright notice,
* this list of conditions and the following disclaimer in the documentation
* and/or other materials provided with the distribution.
* 3. Neither the name of Freescale Semiconductor nor the names of its
* contributors may be used to endorse or promote products derived from this
* software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGE.
*/
/**************************************************************************
* FILE NAME
*
* rpmsg_rtos.h
*
* COMPONENT
*
* OpenAMP stack.
*
* DESCRIPTION
*
* This file provides RTOS adaptation layer that allows:
* - handling of received messages outside the interrupt context
* - the implementation of blocking API for the RPMsg receive side
* - provides zero-copy receive functionality
* - provides zero-copy send functionality
*
* DATA STRUCTURES
*
* none
*
* FUNCTIONS
*
* rpmsg_rtos_init
* rpmsg_rtos_deinit
* rpmsg_rtos_create_ept
* rpmsg_rtos_destroy_ept
* rpmsg_rtos_recv
* rpmsg_rtos_recv_nocopy
* rpmsg_rtos_recv_nocopy_free
* rpmsg_rtos_alloc_tx_buffer
* rpmsg_rtos_send
* rpmsg_rtos_send_nocopy
*
**************************************************************************/
#ifndef __RPMSG_RTOS_H
#define __RPMSG_RTOS_H
#include "../rpmsg/rpmsg.h"
//! @addtogroup rpmsg_rtos
//! @{
/*!
* @brief
* This function allocates and initializes the rpmsg driver resources for
* given device ID (cpu id). The successful return from this function leaves
* fully enabled IPC link. RTOS aware version.
*
* @param[in] dev_id Remote device for which driver is to be initialized
* @param[out] rdev Pointer to newly created remote device
* @param[in] role Role of the other device, Master or Remote
* @param[out] def_chnl Pointer to rpmsg channel
*
* @return Status of function execution
*
* @see rpmsg_rtos_deinit
*/
int rpmsg_rtos_init(int dev_id, struct remote_device **rdev, int role, struct rpmsg_channel **def_chnl);
/*!
* @brief
* This function frees rpmsg driver resources for given remote device. RTOS aware version.
*
* @param[in] rdev Pointer to device to de-init
*
* @see rpmsg_rtos_init
*/
void rpmsg_rtos_deinit(struct remote_device *rdev);
/*!
* @brief
* This function creates rpmsg endpoint for the rpmsg channel. RTOS aware version.
*
* @param[in] rp_chnl Pointer to rpmsg channel
* @param[in] addr Endpoint src address
*
* @return Pointer to endpoint control block
*
* @see rpmsg_rtos_destroy_ept
*/
struct rpmsg_endpoint * rpmsg_rtos_create_ept(struct rpmsg_channel *rp_chnl, unsigned long addr);
/*!
* @brief
* This function deletes rpmsg endpoint and performs cleanup. RTOS aware version.
*
* @param[in] rp_ept Pointer to endpoint to destroy
*
* @see rpmsg_rtos_create_ept
*/
void rpmsg_rtos_destroy_ept(struct rpmsg_endpoint *rp_ept);
/*!
* @brief
* RTOS 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.
*
* @param[in] ept Pointer to the RPMsg endpoint on which data is received
* @param[in] data Pointer to the user buffer the received data are copied to
* @param[out] len Pointer to an int variable that will contain the number of bytes actually copied into the buffer
* @param[in] maxlen Maximum number of bytes to copy (received buffer size)
* @param[out] src Pointer to address of the endpoint from which data is received
* @param[in] timeout_ms 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).
*
* @return Status of function execution
*
* @see rpmsg_rtos_recv_nocopy
*/
int rpmsg_rtos_recv(struct rpmsg_endpoint *ept, void *data, int* len, int maxlen, unsigned long* src, int timeout_ms);
/*!
* @brief
* RTOS 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_rtos_recv_nocopy_free().
*
* @param[in] ept Pointer to the RPMsg endpoint on which data is received
* @param[out] data Pointer to the RPMsg buffer of the shared memory where the received data is stored
* @param[out] len Pointer to an int variable that that will contain the number of valid bytes in the RPMsg buffer
* @param[out] src Pointer to address of the endpoint from which data is received
* @param[in] timeout_ms 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).
*
* @return Status of function execution
*
* @see rpmsg_rtos_recv_nocopy_free
* @see rpmsg_rtos_recv
*/
int rpmsg_rtos_recv_nocopy(struct rpmsg_endpoint *ept, void **data, int* len, unsigned long* src, int timeout_ms);
/*!
* @brief This function frees a buffer previously returned by rpmsg_rtos_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.
*
* @param[in] ept Pointer to the RPMsg endpoint that has consumed received data
* @param[in] data Pointer to the RPMsg buffer of the shared memory that has to be freed
*
* @return Status of function execution
*
* @see rpmsg_rtos_recv_nocopy
*/
int rpmsg_rtos_recv_nocopy_free(struct rpmsg_endpoint *ept, void* data);
/*!
* @brief Allocates the tx buffer for message payload.
*
* This API can only be called at process context to get the tx buffer in vring. By this way, the
* application can directly put its message into the vring tx buffer without copy from an application buffer.
* It is the application responsibility to correctly fill the allocated tx buffer by data and passing correct
* parameters to the rpmsg_rtos_send_nocopy() function to perform data no-copy-send mechanism.
*
* @param[in] ept Pointer to the RPMsg endpoint that requests tx buffer allocation
* @param[out] size Pointer to store tx buffer size
*
* @return The tx buffer address on success and NULL on failure
*
* @see rpmsg_rtos_send_nocopy
*/
void *rpmsg_rtos_alloc_tx_buffer(struct rpmsg_endpoint *ept, unsigned long *size);
/*!
* @brief Sends a message across to the remote processor.
*
* This function sends data of length len to the remote dst address.
* In case there are no TX buffers available, the function will block until
* one becomes available, or a timeout of 15 seconds elapses. When the latter
* happens, -ERESTARTSYS is returned.
*
* @param[in] ept Pointer to the RPMsg endpoint
* @param[in] data Pointer to the application buffer containing data to be sent
* @param[in] len Size of the data, in bytes, to transmit
* @param[in] dst Destination address of the message
*
* @return 0 on success and an appropriate error value on failure
*
* @see rpmsg_rtos_send_nocopy
*/
int rpmsg_rtos_send(struct rpmsg_endpoint *ept, void *data, int len, unsigned long dst);
/*!
* @brief Sends a message in tx buffer allocated by rpmsg_rtos_alloc_tx_buffer()
* to the remote processor.
*
* This function sends txbuf of length len to the remote dst address.
* The application has to take the responsibility for:
* 1. tx buffer allocation (rpmsg_rtos_alloc_tx_buffer() )
* 2. filling the data to be sent into the pre-allocated tx buffer
* 3. not exceeding the buffer size when filling the data
* 4. data cache coherency
*
* After the rpmsg_rtos_send_nocopy() function is issued the tx buffer is no more owned
* by the sending task and must not be touched anymore unless the rpmsg_rtos_send_nocopy()
* function fails and returns an error. In that case the application should try
* to re-issue the rpmsg_rtos_send_nocopy() again and if it is still not possible to send
* the message and the application wants to give it up from whatever reasons
* the rpmsg_rtos_recv_nocopy_free function could be called,
* passing the pointer to the tx buffer to be released as a parameter.
*
* @param[in] ept Pointer to the RPMsg endpoint
* @param[in] txbuf Tx buffer with message filled
* @param[in] len Size of the data, in bytes, to transmit
* @param[in] dst Destination address of the message
*
* @return 0 on success and an appropriate error value on failure
*
* @see rpmsg_rtos_alloc_tx_buffer
* @see rpmsg_rtos_send
*/
int rpmsg_rtos_send_nocopy(struct rpmsg_endpoint *ept, void *txbuf, int len, unsigned long dst);
//! @}
#endif /* __RPMSG_RTOS_H */
|
