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  */
  32
  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  */
  40
  41 #ifndef ti_ipc_mm_MmRpc__include
  42 #define ti_ipc_mm_MmRpc__include
  43
  44 /* add includes here */
  45 #include <stddef.h>
  46 #include <stdint.h>
  47
  48 #if defined(__cplusplus)
  49 extern "C" {
  50 #endif
  51
  52 /*!
  53  *  @brief  Operation is successful
  54  */
  55 #define MmRpc_S_SUCCESS (0)
  56
  57 /*!
  58  *  @brief  Operation failed
  59  */
  60 #define MmRpc_E_FAIL (-1)
  61
  62 /*!
  63  *  @brief  Invalid parameter type
  64  */
  65 #define MmRpc_E_INVALIDPARAM (-2)
  66
  67 /*!
  68  *  @brief  Memory allocation failed
  69  */
  70 #define MmRpc_E_NOMEM (-3)
  71
  72 /*!
  73  *  @brief  A system call failed
  74  */
  75 #define MmRpc_E_SYS (-4)
  76
  77 /*!
  78  *  @brief  Size of parameter array in function context structure
  79  */
  80 #define MmRpc_MAX_PARAMS (10)
  81
  82 /*!
  83  *  @brief  Maximum size of translation array in function context structure
  84  */
  85 #define MmRpc_MAX_TRANSLATIONS (1024)
  86
  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))
 103
 104 /*!
 105  *  @brief      MmRpc_Handle type
 106  */
 107 typedef struct MmRpc_Object *MmRpc_Handle;
 108
 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;
 118
 119 /*!
 120  *  @brief      MmRpc_Param type
 121  */
 122 typedef struct {
 123     MmRpc_ParamType     type;   /*!< parameter type */
 124
 125     union {
 126         struct {
 127             size_t      size;   /*!< size of the data */
 128             size_t      data;   /*!< data (pass by value)*/
 129         } scalar;
 130
 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;
 136
 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;
 143
 144     } param;
 145 } MmRpc_Param;
 146
 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;
 166
 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;
 178
 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;
 188
 189 /*!
 190  *  @brief      Memory buffer descriptor
 191  */
 192 typedef union {
 193     size_t      handle;         /*!< file descriptor or handle */
 194
 195     struct {
 196         size_t  addr;           /*!< address of memory buffer */
 197         size_t  size;           /*!< size (bytes) of memory buffer */
 198     } ptr;
 199
 200 } MmRpc_BufDesc;
 201
 202 /*!
 203  *  @brief      Instance create parameters
 204  */
 205 typedef struct {
 206     int reserved;
 207 } MmRpc_Params;
 208
 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);
 223
 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);
 240
 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);
 252
 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);
 277
 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);
 320
 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);
 334
 335 /*!
 336  *  @brief      Initialize the instance create parameter structure
 337  *
 338  */
 339 void MmRpc_Params_init(MmRpc_Params *params);
 340
 341
 342 #if defined(__cplusplus)
 343 }
 344 #endif
 345 #endif /* ti_ipc_mm_MmRpc__include */