bd766d873eb5f6f3649a6f74b3c0844346adfef2
1 /*
2 * Copyright (c) 2012-2013, Texas Instruments Incorporated
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * * Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * * Neither the name of Texas Instruments Incorporated nor the names of
17 * its contributors may be used to endorse or promote products derived
18 * from this 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,
22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 */
33 /**
34 * @file ti/ipc/mm/MmRpc.h
35 *
36 * @brief Multi-Media derived Remote Procedure Call
37 *
38 * @note MmRpc is currently only available for Linux and QNX.
39 *
40 *
41 */
43 #ifndef ti_ipc_mm_MmRpc__include
44 #define ti_ipc_mm_MmRpc__include
46 /* add includes here */
47 #include <stddef.h>
48 #include <stdint.h>
50 #if defined(__cplusplus)
51 extern "C" {
52 #endif
54 /*!
55 * @brief Operation is successful
56 */
57 #define MmRpc_S_SUCCESS (0)
59 /*!
60 * @brief Operation failed
61 */
62 #define MmRpc_E_FAIL (-1)
64 /*!
65 * @brief Invalid parameter type
66 */
67 #define MmRpc_E_INVALIDPARAM (-2)
69 /*!
70 * @brief Memory allocation failed
71 */
72 #define MmRpc_E_NOMEM (-3)
74 /*!
75 * @brief A system call failed
76 */
77 #define MmRpc_E_SYS (-4)
79 /*!
80 * @brief Size of parameter array in function context structure
81 */
82 #define MmRpc_MAX_PARAMS (10)
84 /*!
85 * @brief Maximum size of translation array in function context structure
86 */
87 #define MmRpc_MAX_TRANSLATIONS (1024)
89 /*!
90 * @brief Macro for computing offset to a field of a structure.
91 *
92 * @code
93 * struct foobar {
94 * int a;
95 * int *p;
96 * };
97 *
98 * struct foobar *sp = ...;
99 * offset = MmRpc_OFFSET(sp, &sp->p);
100 * struct foobar st = ...;
101 * offset = MmRpc_OFFSET(&st, &st.p);
102 * @endcode
103 */
104 #define MmRpc_OFFSET(base, field) ((unsigned int)(field)-(unsigned int)(base))
106 /*!
107 * @brief MmRpc_Handle type
108 */
109 typedef struct MmRpc_Object *MmRpc_Handle;
111 /*!
112 * @brief MmRpc_ParamType enum
113 */
114 typedef enum {
115 MmRpc_ParamType_Scalar = 1, /*!< pass by value */
116 MmRpc_ParamType_Ptr, /*!< data pointer */
117 MmRpc_ParamType_OffPtr, /*!< buffer at offset in memory block */
118 MmRpc_ParamType_Elem /*!< array element */
119 } MmRpc_ParamType;
121 /*!
122 * @brief MmRpc_Param type
123 */
124 typedef struct {
125 MmRpc_ParamType type; /*!< parameter type */
127 union {
128 struct {
129 size_t size; /*!< size of the data */
130 size_t data; /*!< data (pass by value)*/
131 } scalar;
133 struct {
134 size_t size; /*!< size of the data referenced */
135 size_t addr; /*!< pointer value */
136 size_t handle; /*!< memory allocator handle */
137 } ptr;
139 struct {
140 size_t size; /*!< size (bytes) of param structure */
141 size_t base; /*!< param address */
142 size_t offset; /*!< offset within param */
143 size_t handle; /*!< memory allocator handle */
144 } offPtr;
146 } param;
147 } MmRpc_Param;
149 typedef struct {
150 uint32_t index; /*!< parameter index to base pointer */
151 ptrdiff_t offset; /*!< offset to embedded pointer
152 *
153 * If param type is MmRpc_ParamType_Ptr, offset
154 * to embedded pointer from addr. If param type
155 * is MmRpc_ParamType_OffPtr, offset to embedded
156 * pointer from base+offset.
157 */
158 size_t base; /*!< addr or file descriptor [+ data offset]
159 *
160 * If param type is MmRpc_ParamType_Ptr, the
161 * value of the embedded pointer. If param type
162 * is MmRpc_ParamType_OffPtr, the file descriptor
163 * of the block referenced by the embedded pointer
164 * plus an optional data offset.
165 */
166 size_t handle; /*!< memory allocator handle */
167 } MmRpc_Xlt;
169 /*!
170 * @brief Function call context structure
171 */
172 typedef struct {
173 uint32_t fxn_id; /*!< function id to call */
174 uint32_t num_params; /*!< number of parameters in params array */
175 MmRpc_Param params[MmRpc_MAX_PARAMS];
176 /*!< the array of parameters */
177 uint32_t num_xlts; /*!< number of translations in xltAry */
178 MmRpc_Xlt * xltAry; /*!< array of translations */
179 } MmRpc_FxnCtx;
181 /*!
182 * @brief Memory buffer types
183 *
184 * @remark Not all operating systems support all buffer types.
185 */
186 typedef enum {
187 MmRpc_BufType_Handle, /*!< memory allocator handle */
188 MmRpc_BufType_Ptr /*!< buffer address */
189 } MmRpc_BufType;
191 /*!
192 * @brief Memory buffer descriptor
193 */
194 typedef union {
195 size_t handle; /*!< file descriptor or handle */
197 struct {
198 size_t addr; /*!< address of memory buffer */
199 size_t size; /*!< size (bytes) of memory buffer */
200 } ptr;
202 } MmRpc_BufDesc;
204 /*!
205 * @brief Instance create parameters
206 */
207 typedef struct {
208 int reserved;
209 } MmRpc_Params;
211 /*!
212 * @brief Invoke a remote procedure call
213 *
214 * @param[in] handle MmRpc handle, obtained from MmRpc_create()
215 * @param[in] ctx Context with which to invoke the remote service
216 * @param[in, out] ret Return value from the remotely invoked service
217 *
218 * @sa MmRpc_create()
219 * @sa MmRpc_delete()
220 */
221 int MmRpc_call(MmRpc_Handle handle, MmRpc_FxnCtx *ctx, int32_t *ret);
223 /*!
224 * @brief Create an MmRpc instance
225 *
226 * @param[in] service Name of the service to create
227 * @param[in] params Initialized MmRpc parameters
228 * @param[in,out] handlePtr Space to hold the MmRpc handle
229 *
230 * @retval MmRpc_S_SUCCESS @copydoc MmRpc_S_SUCCESS
231 * @retval MmRpc_E_FAIL @copydoc MmRpc_E_FAIL
232 *
233 * @remark This instantiates an instance of the service on a remote
234 * core. Each remote instance consists of a unique thread
235 * listening for requests made via a call to MmRpc_call().
236 */
237 int MmRpc_create(const char *service, const MmRpc_Params *params,
238 MmRpc_Handle *handlePtr);
240 /*!
241 * @brief Delete an MmRpc instance
242 *
243 * @param[in] handlePtr MmRpc handle, obtained from MmRpc_create()
244 *
245 * @sa MmRpc_create()
246 */
247 int MmRpc_delete(MmRpc_Handle *handlePtr);
249 /*!
250 * @brief Release buffers which were declared in use
251 *
252 * @param[in] handle Service handle returned by MmRpc_create()
253 * @param[in] type Buffer descriptor type
254 * @param[in] num Number of elements in @c desc array
255 * @param[in] desc Pointer to array of buffer descriptors
256 *
257 * @remark When the remote processor no longer needs a reference
258 * to a buffer, calling MmRpc_release() will release the
259 * buffer and any associated resources.
260 *
261 * @retval MmRpc_S_SUCCESS @copydoc MmRpc_S_SUCCESS
262 * @retval MmRpc_E_INVALIDPARAM @copydoc MmRpc_E_INVALIDPARAM
263 * @retval MmRpc_E_NOMEM @copydoc MmRpc_E_NOMEM
264 * @retval MmRpc_E_SYS @copydoc MmRpc_E_SYS
265 *
266 * @sa MmRpc_use()
267 */
268 int MmRpc_release(MmRpc_Handle handle, MmRpc_BufType type, int num,
269 MmRpc_BufDesc *desc);
271 /*!
272 * @brief Declare the use of the given buffers
273 *
274 * @param[in] handle Service handle returned by MmRpc_create()
275 * @param[in] type Buffer descriptor type
276 * @param[in] num Number of elements in @c desc array
277 * @param[in] desc Pointer to array of buffer descriptors
278 *
279 * @remark When using MmRpc_call() to invoke remote function calls,
280 * any referenced buffers will be made available to the
281 * remote processor only for the duration of the remote
282 * function call. If the remote processor maintains a
283 * reference to the buffer across multiple invocations of
284 * MmRpc_call(), then the application must declare the buffer
285 * "in use". This will make the buffer persistent.
286 *
287 * @remark The application must release the buffer when it is no
288 * longer needed.
289 *
290 * @code
291 * #include <ti/ipc/mm/MmRpc.h>
292 *
293 * MmRpc_BufDesc desc[2];
294 *
295 * desc[0].handle = fd1;
296 * desc[1].handle = fd2;
297 *
298 * MmRpc_use(h, MmRpc_BufType_Handle, 2, desc);
299 * @endcode
300 *
301 * @retval MmRpc_S_SUCCESS @copydoc MmRpc_S_SUCCESS
302 * @retval MmRpc_E_INVALIDPARAM @copydoc MmRpc_E_INVALIDPARAM
303 * @retval MmRpc_E_NOMEM @copydoc MmRpc_E_NOMEM
304 * @retval MmRpc_E_SYS @copydoc MmRpc_E_SYS
305 *
306 * @sa MmRpc_release()
307 */
308 int MmRpc_use(MmRpc_Handle handle, MmRpc_BufType type, int num,
309 MmRpc_BufDesc *desc);
311 /*!
312 * @brief Initialize the instance create parameter structure
313 *
314 */
315 void MmRpc_Params_init(MmRpc_Params *params);
318 #if defined(__cplusplus)
319 }
320 #endif
321 #endif /* ti_ipc_mm_MmRpc__include */