Docs: Update MmRpc doxygen documentation
[ipc/ipcdev.git] / packages / ti / ipc / mm / MmRpc.h
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)
320 #endif
321 #endif /* ti_ipc_mm_MmRpc__include */