1 /*
2 * Copyright (c) 2012-2014, 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 HLOS (Linux, QNX, Android).
39 */
41 #ifndef ti_ipc_mm_MmRpc__include
42 #define ti_ipc_mm_MmRpc__include
44 /* add includes here */
45 #include <stddef.h>
46 #include <stdint.h>
48 #if defined(__cplusplus)
49 extern "C" {
50 #endif
52 /*!
53 * @brief Operation is successful
54 */
55 #define MmRpc_S_SUCCESS (0)
57 /*!
58 * @brief Operation failed
59 */
60 #define MmRpc_E_FAIL (-1)
62 /*!
63 * @brief Invalid parameter type
64 */
65 #define MmRpc_E_INVALIDPARAM (-2)
67 /*!
68 * @brief Memory allocation failed
69 */
70 #define MmRpc_E_NOMEM (-3)
72 /*!
73 * @brief A system call failed
74 */
75 #define MmRpc_E_SYS (-4)
77 /*!
78 * @brief Size of parameter array in function context structure
79 */
80 #define MmRpc_MAX_PARAMS (10)
82 /*!
83 * @brief Maximum size of translation array in function context structure
84 */
85 #define MmRpc_MAX_TRANSLATIONS (1024)
87 /*!
88 * @brief Macro for computing offset to a field of a structure.
89 *
90 * @code
91 * struct foobar {
92 * int a;
93 * int *p;
94 * };
95 *
96 * struct foobar *sp = ...;
97 * offset = MmRpc_OFFSET(sp, &sp->p);
98 * struct foobar st = ...;
99 * offset = MmRpc_OFFSET(&st, &st.p);
100 * @endcode
101 */
102 #define MmRpc_OFFSET(base, field) ((unsigned int)(field)-(unsigned int)(base))
104 /*!
105 * @brief MmRpc_Handle type
106 */
107 typedef struct MmRpc_Object *MmRpc_Handle;
109 /*!
110 * @brief MmRpc_ParamType enum
111 */
112 typedef enum {
113 MmRpc_ParamType_Scalar = 1, /*!< pass by value */
114 MmRpc_ParamType_Ptr, /*!< data pointer */
115 MmRpc_ParamType_OffPtr, /*!< buffer at offset in memory block */
116 MmRpc_ParamType_Elem /*!< array element */
117 } MmRpc_ParamType;
119 /*!
120 * @brief MmRpc_Param type
121 */
122 typedef struct {
123 MmRpc_ParamType type; /*!< parameter type */
125 union {
126 struct {
127 size_t size; /*!< size of the data */
128 size_t data; /*!< data (pass by value)*/
129 } scalar;
131 struct {
132 size_t size; /*!< size of the data referenced */
133 size_t addr; /*!< pointer value */
134 size_t handle; /*!< memory allocator handle */
135 } ptr;
137 struct {
138 size_t size; /*!< size (bytes) of param structure */
139 size_t base; /*!< param address */
140 size_t offset; /*!< offset within param */
141 size_t handle; /*!< memory allocator handle */
142 } offPtr;
144 } param;
145 } MmRpc_Param;
147 typedef struct {
148 uint32_t index; /*!< parameter index to base pointer */
149 ptrdiff_t offset; /*!< offset to embedded pointer
150 *
151 * If param type is MmRpc_ParamType_Ptr, offset
152 * to embedded pointer from addr. If param type
153 * is MmRpc_ParamType_OffPtr, offset to embedded
154 * pointer from base+offset.
155 */
156 size_t base; /*!< addr or file descriptor [+ data offset]
157 *
158 * If param type is MmRpc_ParamType_Ptr, the
159 * value of the embedded pointer. If param type
160 * is MmRpc_ParamType_OffPtr, the file descriptor
161 * of the block referenced by the embedded pointer
162 * plus an optional data offset.
163 */
164 size_t handle; /*!< memory allocator handle */
165 } MmRpc_Xlt;
167 /*!
168 * @brief Function call context structure
169 */
170 typedef struct {
171 uint32_t fxn_id; /*!< function id to call */
172 uint32_t num_params; /*!< number of parameters in params array */
173 MmRpc_Param params[MmRpc_MAX_PARAMS];
174 /*!< the array of parameters */
175 uint32_t num_xlts; /*!< number of translations in xltAry */
176 MmRpc_Xlt * xltAry; /*!< array of translations */
177 } MmRpc_FxnCtx;
179 /*!
180 * @brief Memory buffer types
181 *
182 * @remark Not all operating systems support all buffer types.
183 */
184 typedef enum {
185 MmRpc_BufType_Handle, /*!< memory allocator handle */
186 MmRpc_BufType_Ptr /*!< buffer address */
187 } MmRpc_BufType;
189 /*!
190 * @brief Memory buffer descriptor
191 */
192 typedef union {
193 size_t handle; /*!< file descriptor or handle */
195 struct {
196 size_t addr; /*!< address of memory buffer */
197 size_t size; /*!< size (bytes) of memory buffer */
198 } ptr;
200 } MmRpc_BufDesc;
202 /*!
203 * @brief Instance create parameters
204 */
205 typedef struct {
206 int reserved;
207 } MmRpc_Params;
209 /*!
210 * @brief Invoke a remote procedure call
211 *
212 * @param[in] handle MmRpc handle, obtained from MmRpc_create()
213 * @param[in] ctx Context with which to invoke the remote service
214 * @param[in, out] ret Return value from the remotely invoked service
215 *
216 * @pre @c handle must be a valid handle for the service instance
217 * returned by an earlier call to MmRpc_create().
218 *
219 * @sa MmRpc_create()
220 * @sa MmRpc_delete()
221 */
222 int MmRpc_call(MmRpc_Handle handle, MmRpc_FxnCtx *ctx, int32_t *ret);
224 /*!
225 * @brief Create an MmRpc instance
226 *
227 * @param[in] service Name of the service to create
228 * @param[in] params Initialized MmRpc parameters
229 * @param[in,out] handlePtr Space to hold the MmRpc handle
230 *
231 * @retval MmRpc_S_SUCCESS @copydoc MmRpc_S_SUCCESS
232 * @retval MmRpc_E_FAIL @copydoc MmRpc_E_FAIL
233 *
234 * @remark This instantiates an instance of the service on a remote
235 * core. Each remote instance consists of a unique thread
236 * listening for requests made via a call to MmRpc_call().
237 */
238 int MmRpc_create(const char *service, const MmRpc_Params *params,
239 MmRpc_Handle *handlePtr);
241 /*!
242 * @brief Delete an MmRpc instance
243 *
244 * @param[in] handlePtr MmRpc handle, obtained from MmRpc_create()
245 *
246 * @pre @c handlePtr must be a valid handle for the service instance
247 * returned by an earlier call to MmRpc_create()
248 *
249 * @sa MmRpc_create()
250 */
251 int MmRpc_delete(MmRpc_Handle *handlePtr);
253 /*!
254 * @brief Release buffers which were declared in use
255 *
256 * @param[in] handle Service handle returned by MmRpc_create()
257 * @param[in] type Buffer descriptor type
258 * @param[in] num Number of elements in @c desc array
259 * @param[in] desc Pointer to array of buffer descriptors
260 *
261 * @pre @c handle must be a valid handle for the service instance
262 * returned by an earlier call to MmRpc_create().
263 *
264 * @remark When the remote processor no longer needs a reference
265 * to a buffer, calling MmRpc_release() will release the
266 * buffer and any associated resources.
267 *
268 * @retval MmRpc_S_SUCCESS @copydoc MmRpc_S_SUCCESS
269 * @retval MmRpc_E_INVALIDPARAM @copydoc MmRpc_E_INVALIDPARAM
270 * @retval MmRpc_E_NOMEM @copydoc MmRpc_E_NOMEM
271 * @retval MmRpc_E_SYS @copydoc MmRpc_E_SYS
272 *
273 * @sa MmRpc_use()
274 */
275 int MmRpc_release(MmRpc_Handle handle, MmRpc_BufType type, int num,
276 MmRpc_BufDesc *desc);
278 /*!
279 * @brief Declare the use of the given buffers
280 *
281 * @param[in] handle Service handle returned by MmRpc_create()
282 * @param[in] type Buffer descriptor type
283 * @param[in] num Number of elements in @c desc array
284 * @param[in] desc Pointer to array of buffer descriptors
285 *
286 * @pre @c handle must be a valid handle for the service instance
287 * returned by an earlier call to MmRpc_create().
288 *
289 * @remark When using MmRpc_call() to invoke remote function calls,
290 * any referenced buffers will be made available to the
291 * remote processor only for the duration of the remote
292 * function call. If the remote processor maintains a
293 * reference to the buffer across multiple invocations of
294 * MmRpc_call(), then the application must declare the buffer
295 * "in use". This will make the buffer persistent.
296 *
297 * @remark The application must release the buffer when it is no
298 * longer needed.
299 *
300 * @code
301 * #include <ti/ipc/mm/MmRpc.h>
302 *
303 * MmRpc_BufDesc desc[2];
304 *
305 * desc[0].handle = fd1;
306 * desc[1].handle = fd2;
307 *
308 * MmRpc_use(h, MmRpc_BufType_Handle, 2, desc);
309 * @endcode
310 *
311 * @retval MmRpc_S_SUCCESS @copydoc MmRpc_S_SUCCESS
312 * @retval MmRpc_E_INVALIDPARAM @copydoc MmRpc_E_INVALIDPARAM
313 * @retval MmRpc_E_NOMEM @copydoc MmRpc_E_NOMEM
314 * @retval MmRpc_E_SYS @copydoc MmRpc_E_SYS
315 *
316 * @sa MmRpc_release()
317 */
318 int MmRpc_use(MmRpc_Handle handle, MmRpc_BufType type, int num,
319 MmRpc_BufDesc *desc);
321 /*!
322 * @brief Initialize the instance create parameter structure
323 *
324 */
325 void MmRpc_Params_init(MmRpc_Params *params);
328 #if defined(__cplusplus)
329 }
330 #endif
331 #endif /* ti_ipc_mm_MmRpc__include */