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