Final merge of Suman and Angela's latest updates. Updates to MmRpc.
[ipc/ipcdev.git] / 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  */
33 /*
34  *  ======== OmapRpc.h ========
35  *  OMAP Remote Procedure Call Driver.
36  *
37  */
39 #ifndef ti_srvmgr_OmapRpc__include
40 #define ti_srvmgr_OmapRpc__include
42 #include <ti/grcm/RcmServer.h>
45 #if defined (__cplusplus)
46 extern "C" {
47 #endif
50 /*!
51  *  @def    OmapRpc_S_SUCCESS
52  *  @brief  Operation is successful.
53  */
54 #define OmapRpc_S_SUCCESS              0
56 /*!
57  *  @def    OmapRpc_E_FAIL
58  *  @brief  Operation is not successful.
59  */
60 #define OmapRpc_E_FAIL                 -1
62 #define OmapRpc_NUM_PARAMETERS(size) \
63     (size/sizeof(struct OmapRpc_Parameter))
65 #define OmapRpc_PAYLOAD(ptr, type) \
66     ((struct type *)&(ptr)[sizeof(struct OmapRpc_MsgHeader)])
68 #define OmapRpc_PARAM(param, type) (param.size == sizeof(type) ? (type)param.data : 0)
70 #define OmapRpc_Stringerize(func)   #func
72 #define OmapRpc_dimof(x)    (sizeof(x)/sizeof(x[0]))
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)
83 #define OmapRpc_SET_FXN_IDX(idx)    (idx | 0x80000000)
84 #define OmapRpc_FXN_MASK(idx)       (idx & 0x7FFFFFFF)
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)
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,
99     /** @hidden used to define the maximum info type */
100     OmapRpc_InfoType_MAX
101 } OmapRpc_InfoType;
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 = 6,
120     /** The return message from OMAPRPC_CREATE_INSTANCE,
121      * contains the new endpoint address in the OmapRpc_InstanceHandle */
122     OmapRpc_MsgType_INSTANCE_CREATED = 8,
123     /** Ask the Service Mgr to destroy an instance */
124     OmapRpc_MsgType_DESTROY_INSTANCE = 4,
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 = 5,
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;
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,
153     /** @hidden used to define the max error value */
154     OmapRpc_ErrorType_MAX_VALUE
155 } OmapRpc_ErrorType;
157 typedef struct OmapRpc_CreateInstance {
158     Char name[OMAPRPC_MAX_INST_NAMELEN];
159 } OmapRpc_CreateInstance;
161 typedef struct OmapRpc_ChannelInfo {
162     UInt32 numFuncs;        /**< The number of functions supported on this endpoint */
163 } OmapRpc_ChannelInfo;
165 typedef struct OmapRpc_FuncPerf {
166     UInt32 clocksPerSec;
167     UInt32 clockCycles;
168 } OmapRpc_FuncPerf;
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;
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,
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;
194 #define OmapRpc_PtrType(type)   (type | OmapRpc_Param_PTR)
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;
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;
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;
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;
235 typedef struct OmapRpc_InstanceHandle {
236     UInt32 endpointAddress;
237     UInt32 status;
238 } OmapRpc_InstanceHandle;
240 typedef struct OmapRpc_Error {
241     UInt32 endpointAddress;
242     UInt32 status;
243 } OmapRpc_Error;
245 typedef struct OmapRpc_Parameter {
246     SizeT size;
247     SizeT data;
248 } OmapRpc_Parameter;
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;
261 /** An OmapRpc Function is really an RCM function */
262 typedef RcmServer_MsgFxn OmapRpc_Function;
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;
274 typedef struct OmapRpc_Object *OmapRpc_Handle;
275 typedef Void (*OmapRpc_SrvDelNotifyFxn)(Void);
277 OmapRpc_Handle OmapRpc_createChannel(String channelName,
278                                      UInt16 dstProc,
279                                      UInt32 port,
280                                      UInt32 numFuncs,
281                                      OmapRpc_FuncDeclaration* fxns,
282                                      OmapRpc_SrvDelNotifyFxn func);
284 Int OmapRpc_deleteChannel(OmapRpc_Handle handle);
287 #if defined (__cplusplus)
289 #endif /* defined (__cplusplus) */
291 /*@}*/
292 #endif /* ti_srvmgr_OmapRpc__include */