Support in QNX MmRpc/MmServiceMgr to identify deleted instance during cleanup
[ipc/ipcdev.git] / packages / ti / ipc / mm / MmRpc.h
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      Get the id of an MmRpc instance
323  *              (currently only supported in QNX)
324  *
325  *  @param[in]  handle   Service handle returned by MmRpc_create()
326  *
327  *  @retval     32-bit id corresponding to the MmRpc instance
328  *
329  *  @remark     This returns the id corresponding to the MmRpc instance.
330  *              This id can be used to identify the MmRpc instance
331  *              on the slave core during instance deletion.
332  */
333 uint32_t MmRpc_getId(MmRpc_Handle handle);
335 /*!
336  *  @brief      Initialize the instance create parameter structure
337  *
338  */
339 void MmRpc_Params_init(MmRpc_Params *params);
342 #if defined(__cplusplus)
344 #endif
345 #endif /* ti_ipc_mm_MmRpc__include */