packages/ti/srvmgr/omaprpc/OmapRpc.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  *  ======== OmapRpc.h ========
  35  *  OMAP Remote Procedure Call Driver.
  36  *
  37  */
  38
  39 #ifndef ti_srvmgr_OmapRpc__include
  40 #define ti_srvmgr_OmapRpc__include
  41
  42 #include <ti/grcm/RcmServer.h>
  43 #include <ti/ipc/mm/MmType.h>
  44
  45
  46 #if defined (__cplusplus)
  47 extern "C" {
  48 #endif
  49
  50
  51 /*!
  52  *  @def    OmapRpc_S_SUCCESS
  53  *  @brief  Operation is successful.
  54  */
  55 #define OmapRpc_S_SUCCESS              (0)
  56
  57 /*!
  58  *  @def    OmapRpc_E_FAIL
  59  *  @brief  Operation is not successful.
  60  */
  61 #define OmapRpc_E_FAIL                 (-1)
  62
  63 #define OmapRpc_NUM_PARAMETERS(size) \
  64     ((size)/sizeof(struct OmapRpc_Parameter))
  65
  66 #define OmapRpc_PAYLOAD(ptr, type) \
  67     ((struct type *)&(ptr)[sizeof(struct OmapRpc_MsgHeader)])
  68
  69 #define OmapRpc_PARAM(param, type) ((param).size == sizeof(type) ? (type)(param).data : 0)
  70
  71 #define OmapRpc_Stringerize(func)   #func
  72
  73 #define OmapRpc_dimof(x)    (sizeof(x)/sizeof((x)[0]))
  74
  75 #define OmapRpc_DESC_EXEC_SYNC  (0x0100)
  76 #define OmapRpc_DESC_EXEC_ASYNC (0x0200)
  77 #define OmapRpc_DESC_SYM_ADD    (0x0300)
  78 #define OmapRpc_DESC_SYM_IDX    (0x0400)
  79 #define OmapRpc_DESC_CMD        (0x0500)
  80 #define OmapRpc_DESC_TYPE_MASK  (0x0F00)
  81 #define OmapRpc_JOBID_DISCRETE  (0)
  82 #define OmapRpc_POOLID_DEFAULT  (0x8000)
  83
  84 #define OmapRpc_SET_FXN_IDX(idx)    ((idx) | 0x80000000)
  85 #define OmapRpc_FXN_MASK(idx)       ((idx) & 0x7FFFFFFF)
  86
  87 #define OMAPRPC_MAX_CHANNEL_NAMELEN (64)
  88 #define OMAPRPC_MAX_FUNC_NAMELEN    (64)
  89 #define OMAPRPC_MAX_NUM_PARAMS      (10)
  90 #define OMAPRPC_MAX_INST_NAMELEN    (48)
  91
  92 typedef enum OmapRpc_InfoType {
  93     /** The function signature */
  94     OmapRpc_InfoType_FUNC_SIGNATURE = 1,
  95     /** The number of times a function has been called */
  96     OmapRpc_InfoType_NUM_CALLS,
  97     /** The performance information releated to the function */
  98     OmapRpc_InfoType_FUNC_PERFORMANCE,
  99
 100     /** @hidden used to define the maximum info type */
 101     OmapRpc_InfoType_MAX
 102 } OmapRpc_InfoType;
 103
 104 /** The applicable types of messages that the HOST may send the SERVICE.
 105  */
 106 typedef enum OmapRpc_MsgType {
 107     /** Ask Service for channel information, uses \ref OmapRpc_ChannelInfo */
 108     OmapRpc_MsgType_QUERY_CHAN_INFO = 0,
 109     /** The return message from OMAPRPC_MSG_QUERY_CHAN_INFO*/
 110     OmapRpc_MsgType_CHAN_INFO = 1,
 111     /** Ask the Service Instance to send information about the Service.
 112      * Uses \ref OmapRpc_QueryFunction */
 113     OmapRpc_MsgType_QUERY_FUNCTION = 2,
 114     /** The return message from OMAPRPC_QUERY_INSTANCE,
 115      * which contains the information about the instance.
 116      * Uses \ref OmapRpc_Instance_Info */
 117     OmapRpc_MsgType_FUNCTION_INFO = 3,
 118     /** Ask the ServiceMgr to create a new instance of the service.
 119      * No secondary data is needed. */
 120     OmapRpc_MsgType_CREATE_INSTANCE = 6,
 121     /** The return message from OMAPRPC_CREATE_INSTANCE,
 122      * contains the new endpoint address in the OmapRpc_InstanceHandle */
 123     OmapRpc_MsgType_INSTANCE_CREATED = 8,
 124     /** Ask the Service Mgr to destroy an instance */
 125     OmapRpc_MsgType_DESTROY_INSTANCE = 4,
 126     /** The return message from OMAPRPC_DESTROY_INSTANCE.
 127      * contains the old endpoint address in the OmapRpc_InstanceHandle */
 128     OmapRpc_MsgType_INSTANCE_DESTROYED = 7,
 129     /** Ask the Service Instance to call a particular function */
 130     OmapRpc_MsgType_CALL_FUNCTION = 5,
 131     /** The return values from a function call */
 132     OmapRpc_MsgType_FUNCTION_RETURN = 9,
 133     /** Returned from either the ServiceMgr or Service Instance
 134      * when an error occurs */
 135     OmapRpc_MsgType_ERROR = 10,
 136     /** \hidden used to define the max msg enum, not an actual message */
 137     OmapRpc_MsgType_MAX
 138 } OmapRpc_MsgType;
 139
 140 typedef enum OmapRpc_ErrorType {
 141     /**< No errors to report */
 142     OmapRpc_ErrorType_NONE = 0,
 143     /**< Not enough memory exist to process request */
 144     OmapRpc_ErrorType_NOT_ENOUGH_MEMORY,
 145     /**< The instance died */
 146     OmapRpc_ErrorType_INSTANCE_DIED,
 147     /**< Some resource was unavailable. */
 148     OmapRpc_ErrorType_RESOURCE_UNAVAILABLE,
 149     /**< A provided parameter was either out of range, incorrect or NULL */
 150     OmapRpc_ErrorType_BAD_PARAMETER,
 151     /**< The requested item is not supported */
 152     OmapRpc_ErrorType_NOT_SUPPORTED,
 153
 154     /** @hidden used to define the max error value */
 155     OmapRpc_ErrorType_MAX_VALUE
 156 } OmapRpc_ErrorType;
 157
 158 typedef struct OmapRpc_CreateInstance {
 159     Char name[OMAPRPC_MAX_INST_NAMELEN];
 160     UInt32 id;
 161 } OmapRpc_CreateInstance;
 162
 163 typedef struct OmapRpc_ChannelInfo {
 164     UInt32 numFuncs;        /**< The number of functions supported on this endpoint */
 165 } OmapRpc_ChannelInfo;
 166
 167 typedef struct OmapRpc_FuncPerf {
 168     UInt32 clocksPerSec;
 169     UInt32 clockCycles;
 170 } OmapRpc_FuncPerf;
 171
 172 /** The parameter direction as relative to the function it describes */
 173 typedef enum OmapRpc_Direction {
 174     OmapRpc_Direction_In = 0,
 175     OmapRpc_Direction_Out,
 176     OmapRpc_Direction_Bi,
 177     OmapRpc_Direction_MAX
 178 } OmapRpc_Direction;
 179
 180 typedef enum OmapRpc_Param_Type {
 181     OmapRpc_Param_VOID = 0,
 182     OmapRpc_Param_S08,
 183     OmapRpc_Param_U08,
 184     OmapRpc_Param_S16,
 185     OmapRpc_Param_U16,
 186     OmapRpc_Param_S32,
 187     OmapRpc_Param_U32,
 188     OmapRpc_Param_S64,
 189     OmapRpc_Param_U64,
 190
 191     OmapRpc_Param_PTR = 0x80,   /**< Logically OR'd with lower type to make a
 192                                      pointer to the correct type */
 193     OmapRpc_Param_MAX
 194 } OmapRpc_Param_Type;
 195
 196 #define OmapRpc_PtrType(type)   ((type) | OmapRpc_Param_PTR)
 197
 198 typedef struct OmapRpc_ParamSignature {
 199     UInt32 direction;   /**< @see OmapRpc_Direction */
 200     UInt32 type;        /**< @see OmapRpc_Param_Type */
 201     UInt32 count;       /**< Used to do some basic sanity checking on array bounds */
 202 } OmapRpc_ParamSignature;
 203
 204 /**
 205  * This is the data structure that represents the function signature.
 206  * @note The first parameter (params[0]) is the return value.
 207  */
 208 typedef struct OmapRpc_FuncSignature {
 209     Char name[OMAPRPC_MAX_FUNC_NAMELEN];
 210     UInt32 numParam;
 211     OmapRpc_ParamSignature params[OMAPRPC_MAX_NUM_PARAMS+1];
 212 } OmapRpc_FuncSignature;
 213
 214 /**
 215  * \brief Function Query Structure.
 216  * \details This is used by the host first to ask the remote side for details
 217  * about it's published functions
 218  */
 219 typedef struct OmapRpc_QueryFunction {
 220     UInt32 infoType;        /**< @see OmapRpc_InfoType */
 221     UInt32 funcIndex;       /**< The function index to query */
 222     union info {
 223         UInt32 numCalls;
 224         OmapRpc_FuncPerf performance;
 225         OmapRpc_FuncSignature signature;
 226     } info;
 227 } OmapRpc_QueryFunction;
 228
 229 /** @brief The generic OMAPRPC message header.
 230  * (actually a copy of omx_msg_hdr which is a copy of an RCM header)
 231  */
 232 typedef struct OmapRpc_MsgHeader {
 233     UInt32 msgType;    /**< @see OmapRpc_MsgType */
 234     UInt32 msgLen;     /**< The length of the message data in bytes */
 235 } OmapRpc_MsgHeader;
 236
 237 typedef struct OmapRpc_InstanceHandle {
 238     UInt32 endpointAddress;
 239     UInt32 status;
 240 } OmapRpc_InstanceHandle;
 241
 242 typedef struct OmapRpc_Error {
 243     UInt32 endpointAddress;
 244     UInt32 status;
 245 } OmapRpc_Error;
 246
 247 typedef struct OmapRpc_Parameter {
 248     SizeT size;
 249     SizeT data;
 250 } OmapRpc_Parameter;
 251
 252 /** This is actually a frankensteined structure of RCM */
 253 typedef struct OmapRpc_Packet{
 254     UInt16  desc;       /**< @see RcmClient_Packet.desc */
 255     UInt16  msgId;      /**< @see RcmClient_Packet.msgId */
 256     UInt16  poolId;     /**< @see RcmClient_Message.poolId */
 257     UInt16  jobId;      /**< @see RcmClient_Message.jobId */
 258     UInt32  fxnIdx;     /**< @see RcmClient_Message.fxnIdx */
 259     Int32   result;     /**< @see RcmClient_Message.result */
 260     UInt32  dataSize;   /**< @see RcmClient_Message.data_size */
 261 } OmapRpc_Packet;
 262
 263 /** An OmapRpc Function is really an RCM function */
 264 typedef RcmServer_MsgFxn OmapRpc_Function;
 265
 266 /**
 267  * \brief The Function Declaration Structure.
 268  * \details This structure is used to declare the function signature and their
 269  * associated functions
 270  */
 271 typedef struct OmapRpc_FuncDeclaration {
 272     OmapRpc_Function      function;  /**< \brief The function pointer */
 273     OmapRpc_FuncSignature signature; /**< \brief The signature of the function */
 274 } OmapRpc_FuncDeclaration;
 275
 276 typedef struct OmapRpc_Object *OmapRpc_Handle;
 277 typedef Void (*OmapRpc_SrvDelNotifyFxn)(Void);
 278 typedef Void (*OmapRpc_SrvDelNotifyFxn2)(UInt32);
 279
 280 OmapRpc_Handle OmapRpc_createChannel(String channelName, UInt16 dstProc,
 281         UInt32 port, RcmServer_Params *rcmParams, MmType_FxnSigTab *fxnSigTab,
 282         OmapRpc_SrvDelNotifyFxn srvDelCBFunc);
 283
 284 /*
 285  * OmapRpc_createChannel2
 286  * Same as OmapRpc_createChannel but with OmapRpc_SrvDelNotifyFxn2
 287  */
 288 OmapRpc_Handle OmapRpc_createChannel2(String channelName, UInt16 dstProc,
 289         UInt32 port, RcmServer_Params *rcmParams, MmType_FxnSigTab *fxnSigTab,
 290         OmapRpc_SrvDelNotifyFxn2 srvDelCBFunc);
 291
 292 Int OmapRpc_deleteChannel(OmapRpc_Handle handle);
 293
 294
 295 #if defined (__cplusplus)
 296 }
 297 #endif /* defined (__cplusplus) */
 298
 299 /*@}*/
 300 #endif /* ti_srvmgr_OmapRpc__include */