OpenClovis Logo

clEoApi.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2002-2012 OpenClovis Solutions Inc. All Rights Reserved.
3  *
4  * This file is available under a commercial license from the
5  * copyright holder or the GNU General Public License Version 2.0.
6  *
7  * The source code for this program is not published or otherwise
8  * divested of its trade secrets, irrespective of what has been
9  * deposited with the U.S. Copyright office.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * General Public License for more details.
15  *
16  * For more information, see the file COPYING provided with this
17  * material.
18  */
19 /*******************************************************************************
20  * ModuleName : eo
21  * File : clEoApi.h
22  *******************************************************************************/
23 
24 /*******************************************************************************
25  * Description :
26  * This header contains the definitions of various Execution Object (EO)
27  * data types and APIs.
28  *
29  *
30  *****************************************************************************/
31 
32 
33 /*****************************************************************************/
34 /******************************** EO APIs ************************************/
35 /*****************************************************************************/
36 /* */
37 /* clEoCreate */
38 /* clEoWalk */
39 /* clEoServiceValidate */
40 /* clEoStateSet */
41 /* clEoClientInstall */
42 /* clEoClientUninstall */
43 /* clEoClientDataSet */
44 /* clEoClientDataGet */
45 /* clEoServiceInstall */
46 /* clEoServiceUninstall */
47 /* clEoPrivateDataSet */
48 /* clEoPrivateDataGet */
49 /* clEoMyEoIocPortSet */
50 /* clEoMyEoIocPortGet */
51 /* clEoMyEoObjectSet */
52 /* clEoMyEoObjectGet */
53 /* clEoReceiveStart */
54 /* */
55 /*****************************************************************************/
56 
68 /*******************************************************************************
69  Any execution manager in the form of a process, task or thread (let's call it
70  an execution entity) is presumed to contain a set of data and an execution
71  context.
72 
73  The execution entity running in the system without external communication is
74  not very effective in the system, unless it is capable of interacting with
75  other execution entities. Since the execution entities are distributed in
76  nature, there needs to be a common mechanism that facilitates the
77  communication of these execution entities. Basically, the execution entity
78  consists of three responsibilities:
79  - The attributes and methods required to manage the execution entity.
80  - A mechanism to communicate with external execution entities.
81  - Implementation specific to the responsibilities of the execution entity.
82 
83  Clovis provides the first two functionalities, which are encapsulated within
84  the ExecutionObject. The ExecutionObject encapsulates all the common attributes
85  and methods that are used to represent the execution entity in the system.
86  Also, provided is the mechanism that facilitates the external communication.
87  The external communication is provided by creating a background thread that
88  receives the messages on behalf of the execution entity from external entities.
89  Once the messages are received, decoded and the corresponding method within
90  the execution entity is invoked. The user of the ExecutionObject is totally
91  unaware of this processing, and can simple assume the implemented methods are
92  invoked auto magically.
93 *******************************************************************************/
94 
95 
96 #ifndef _CL_EO_API_H_
97 #define _CL_EO_API_H_
98 
99 #ifdef __cplusplus
100 extern "C" {
101 #endif
102 
103 /* CL_INCLUDES */
104 #include <clCommon.h>
105 #include <clCommonErrors.h>
106 
107 #include <clOsalApi.h>
108 #include <clHeapApi.h>
109 #include <clQueueApi.h>
110 #include <clIocApi.h>
111 #include <clIocManagementApi.h>
112 #include <clRmdApi.h>
113 #include <clCntApi.h>
114 #include <clVersion.h>
115 
116 #include <clEoConfigApi.h>
117 #include <clEoErrors.h>
118 #include <clRadixTree.h>
119 
120 /******************************************************************************
121  * Constant and Macro Definitions
122  *****************************************************************************/
123 
125 extern ClCharT ASP_NODENAME[CL_MAX_NAME_LENGTH];
127 extern ClCharT ASP_COMPNAME[CL_MAX_NAME_LENGTH];
129 extern ClUint32T ASP_NODEADDR;
130 
132 extern ClCharT ASP_RUNDIR[CL_MAX_NAME_LENGTH];
134 extern ClCharT ASP_LOGDIR[CL_MAX_NAME_LENGTH];
136 extern ClCharT ASP_BINDIR[CL_MAX_NAME_LENGTH];
138 extern ClCharT CL_APP_BINDIR[CL_MAX_NAME_LENGTH];
140 extern ClCharT ASP_APP_BINDIR[CL_MAX_NAME_LENGTH];
141 
143 extern ClCharT ASP_CONFIG[CL_MAX_NAME_LENGTH];
145 extern ClCharT ASP_DBDIR[CL_MAX_NAME_LENGTH];
146 
148 extern ClBoolT SYSTEM_CONTROLLER;
150 extern ClBoolT ASP_SC_PROMOTE;
151 
156 #define CL_EO_MAX_NO_FUNC 64
157 
158 typedef enum {
159 
164 
170 
174 #define CL_EO_CLIENT_BIT_SHIFT 6
175 
179 #define CL_EO_FN_MASK (0x3F)
180 
181 #define CL_EO_CLIENT_ID_MASK (ClUint32T)(~0U >> CL_EO_CLIENT_BIT_SHIFT)
182 
186 #define CL_EO_GET_FULL_FN_NUM(cl, fn) (((cl) << CL_EO_CLIENT_BIT_SHIFT) | \
187  ((fn) << 0))
188 
189 /******************************************************************************
190  * Data Types
191  *****************************************************************************/
192 
197 
201 typedef ClUint32T ClEoArgT;
202 
203 typedef enum {
204 
209 
214 
219 
224 
229 
234 
239 
240 /*
241  * This value is Debug specific.
242  */
243  CL_DEBUG_CLIENT_TABLE_ID,
244 
245 /*
246  * This value is Transaction Agent-specific.
247  */
248  CL_TXN_CLIENT_TABLE_ID,
249 
254 
259 
264 
273 
278 
283 
292 
297 /*
298  * Extended AMS mgmt server tables.
299  */
300  CL_AMS_MGMT_SERVER_TABLE2_ID,
301 
306 
307 } ClEoClientIdT;
308 
312 #define CL_EO_USER_CLIENT_ID_START CL_EO_CLOVIS_RESERVED_CLIENTID_END
313 
321 #define CL_EO_SERVER_COOKIE_BIT_SIZE 8
322 
323 #define CL_EO_SERVER_COOKIE_BASE(cId) ((cId) << (CL_EO_SERVER_COOKIE_BIT_SIZE))
324 
331 #define CL_EO_EVENT_CHANNEL_NAME "CL_EO_EVENT_CHANNEL_NAME"
332 #define CL_EO_EVENT_SUBSCRIBE_FLAG (CL_EVENT_CHANNEL_SUBSCRIBER | CL_EVENT_GLOBAL_CHANNEL)
333 #define CL_EO_EVENT_DEFAULT_FILTER NULL
334 
335 /*
336  * A typical call to subscribe would be as below:
337  * rc = clEventSubscribe(eoChannelHandle, CL_EO_EVENT_DEFAULT_FILTER, 0, NULL);
338  *
339  * For a more specific filter during subscribe one can specify the pattern as below:
340  * patterns[0].patternSize = sizeof(CL_EO_NAME);
341  * patterns[0].pPattern = (ClUint8T *)CL_EO_NAME;
342  *
343  * patterns[1].patternSize = sizeof(libraryId);
344  * patterns[1].pPattern = (ClUint8T *)&libraryId;
345  *
346  * patterns[2].patternSize = sizeof(waterMarkId);
347  * patterns[2].pPattern = (ClUint8T *)&waterMarkId;
348  *
349  * patterns[3].patternSize = sizeof(waterMarkType);
350  * patterns[3].pPattern = (ClUint8T *)&waterMarkType;
351  *
352  * patterns[4].patternSize = sizeof(waterMarkValue);
353  * patterns[4].pPattern = (ClUint8T *)(&waterMarkValue);
354  */
355 
356 typedef enum {
357  CL_EO_NATIVE_COMPONENT_COOKIE_BASE
358  = CL_EO_SERVER_COOKIE_BASE(CL_EO_NATIVE_COMPONENT_TABLE_ID),
359  CL_EO_EO_MGR_SERVER_COOKIE_ID
360  = CL_EO_SERVER_COOKIE_BASE(CL_EO_EO_MGR_CLIENT_TABLE_ID),
361  CL_EO_COR_SERVER_COOKIE_ID
362  = CL_EO_SERVER_COOKIE_BASE(CL_EO_COR_CLIENT_TABLE_ID),
363  CL_EO_EVT_EVENT_DELIVERY_COOKIE_ID
364  = CL_EO_SERVER_COOKIE_BASE(CL_EO_EVT_CLIENT_TABLE_ID),
365  CL_EO_DEBUG_OBJECT_COOKIE_ID
366  = CL_EO_SERVER_COOKIE_BASE(CL_DEBUG_CLIENT_TABLE_ID),
367  CL_EO_RMD_CLIENT_COOKIE_ID
368  = CL_EO_SERVER_COOKIE_BASE(CL_EO_RMD_CLIENT_TABLE_ID)
369 } ClEoServerIdT;
370 
371 
390  CL_IN ClEoDataT data,
391  CL_IN ClBufferHandleT inMsgHandle,
392  CL_OUT ClBufferHandleT outMsgHandle);
393 
394 typedef struct ClEoPayloadWithReplyCallbackServer
395 {
397  ClUint32T funId;
398  ClUint32T version;
399 } ClEoPayloadWithReplyCallbackServerT;
400 
401 typedef struct ClEoPayloadWithReplyCallbackClient
402 {
403  ClUint32T funId;
404  ClUint32T version;
405 } ClEoPayloadWithReplyCallbackClientT;
406 
407 typedef struct ClEoPayloadWithReplyCallbackTableClient
408 {
409  ClUint32T clientID;
410  ClEoPayloadWithReplyCallbackClientT *funTable;
411  ClUint32T funTableSize;
412 } ClEoPayloadWithReplyCallbackTableClientT;
413 
414 typedef struct ClEoPayloadWithReplyCallbackTableServer
415 {
416  ClUint32T clientID;
417  ClEoPayloadWithReplyCallbackServerT *funTable;
418  ClUint32T funTableSize;
419 } ClEoPayloadWithReplyCallbackTableServerT;
420 
424 typedef struct ClEoServiceObj {
425 
429  void (*func)();
430 
436 
442 typedef struct {
443 
448 
452  ClEoDataT data;
453 
455 
456 #define __CLIENT_RADIX_TREE_INDEX(fun_id, version_code) ( (((fun_id & CL_EO_FN_MASK) << CL_VERSION_SHIFT) ) | ((version_code) & CL_VERSION_MASK) )
457 
458 typedef struct {
459  ClUint32T maxClients;
460  ClRadixTreeHandleT funTable;
461 }ClEoClientTableT;
462 
463 typedef struct {
464  ClUint32T maxClients;
465  ClRadixTreeHandleT funTable;
466  ClEoDataT data;
467 }ClEoServerTableT;
468 
473 typedef struct ClEoExecutionObj{
474 
479 
484 
489 
494 
498  ClUint32T threadRunning;
499 
504 
508  ClEoClientTableT *pClientTable;
509 
513  ClEoServerTableT *pServerTable;
514 
518  ClUint32T noOfThreads;
519 
524 
529 
533  ClRmdObjHandleT rmdObj;
534 
538  ClUint32T eoInitDone;
539 
543  ClUint32T eoSetDoneCnt;
544 
549 
550  ClUint32T refCnt;
551 
555  ClOsalMutexT eoMutex;
556 
557  ClOsalCondT eoCond;
558 
563 
567  ClUint32T appType;
568 
572  ClUint32T maxNoClients;
573 
578 
583 
588 
594 
596 
597 
598 
617  CL_IN ClEoDataT eoArg,
618  CL_IN ClBufferHandleT inMsgHdl,
619  CL_OUT ClBufferHandleT outMsgHdl);
620 
648 
649  CL_IN ClEoExecutionObjT* pThis,
650  CL_IN ClBufferHandleT eoRecvMsg,
651  CL_IN ClUint8T priority,
652  CL_IN ClUint8T protoType,
653  CL_IN ClUint32T length,
654  CL_IN ClIocPhysicalAddressT srcAddr);
655 
656 
661 typedef struct
662 {
663 
667  ClUint8T protoID;
668 
672  ClCharT name[CL_MAX_NAME_LENGTH];
673 
678 
683 
687  ClUint32T flags;
688 
689 } ClEoProtoDefT;
690 
691 #define EO_CLIENT_SYM(sym) sym##Client
692 #define CL_EO_CLIENT_SYM_MOD(sym, mod) EO_CLIENT_SYM(sym##mod)
693 #define CL_EO_SERVER_SYM_MOD(sym, mod) sym##mod
694 
695 #if defined (__SERVER__)
696 
697 #define CL_EO_CALLBACK_TABLE_DECL(sym) ClEoPayloadWithReplyCallbackServerT VDECL(sym)
698 #define CL_EO_CALLBACK_TABLE_VER_DECL(sym, rel, major, minor) ClEoPayloadWithReplyCallbackServerT VDECL_VER(sym, rel, major, minor)
699 #define CL_EO_CALLBACK_TABLE_LIST_DECL(sym, module) ClEoPayloadWithReplyCallbackTableServerT sym##module
700 #define CL_EO_CALLBACK_TABLE_LIST_DEF(clnt, sym) { \
701  clnt, VDECL(sym), (ClUint32T)sizeof(VDECL(sym))/sizeof(VDECL(sym)[0]) }
702 #define CL_EO_CALLBACK_TABLE_LIST_VER_DEF(clnt, sym, rel, major, minor) { \
703  clnt, VDECL_VER(sym, rel, major, minor), \
704  (ClUint32T)sizeof(VDECL_VER(sym, rel, major, minor))/sizeof(VDECL_VER(sym, rel, major, minor)[0]) }
705 
706 #else
707 
708 #define CL_EO_CALLBACK_TABLE_DECL(sym) ClEoPayloadWithReplyCallbackClientT VDECL(EO_CLIENT_SYM(sym))
709 #define CL_EO_CALLBACK_TABLE_VER_DECL(sym, rel, major, minor) ClEoPayloadWithReplyCallbackClientT VDECL_VER(EO_CLIENT_SYM(sym), rel, major, minor)
710 #define CL_EO_CALLBACK_TABLE_LIST_DECL(sym, module) ClEoPayloadWithReplyCallbackTableClientT EO_CLIENT_SYM(sym##module)
711 #define CL_EO_CALLBACK_TABLE_LIST_DEF(clnt, sym) { clnt, VDECL(EO_CLIENT_SYM(sym) ), \
712  (ClUint32T)sizeof(VDECL(EO_CLIENT_SYM(sym))) / sizeof(VDECL(EO_CLIENT_SYM(sym))[0]) }
713 #define CL_EO_CALLBACK_TABLE_LIST_VER_DEF(clnt, sym, rel, major, minor) { \
714  clnt, VDECL_VER(EO_CLIENT_SYM(sym), rel, major, minor), \
715  (ClUint32T) sizeof(VDECL_VER(EO_CLIENT_SYM(sym), rel, major, minor)) / sizeof(VDECL_VER(EO_CLIENT_SYM(sym), rel, major, minor)[0]) }
716 #endif
717 
718 #define CL_EO_CALLBACK_TABLE_LIST_DEF_NULL { 0, NULL, 0 }
719 
720 extern ClEoPayloadWithReplyCallbackTableClientT EO_CLIENT_SYM(gAspFuncTable)[];
721 
722 ClRcT clEoClientInstallTables(ClEoExecutionObjT *pThis,
723  ClEoPayloadWithReplyCallbackTableServerT *table);
724 
725 ClRcT clEoClientInstallTablesWithCookie(ClEoExecutionObjT *pThis,
726  ClEoPayloadWithReplyCallbackTableServerT *table,
727  ClEoDataT data);
728 
729 ClRcT clEoClientUninstallTables(ClEoExecutionObjT *pThis,
730  ClEoPayloadWithReplyCallbackTableServerT *table);
731 
732 ClBoolT clEoClientTableFilter(ClIocPortT eoPort, ClUint32T clientID);
733 
734 ClRcT clEoClientTableRegister(ClEoPayloadWithReplyCallbackTableClientT *clientTable,
735  ClIocPortT clientPort);
736 
748  void clEoProtoInstall(ClEoProtoDefT* def);
749 
758  void clEoProtoUninstall(ClUint8T id);
759 
768  void clEoProtoSwitch(ClEoProtoDefT* def);
769 
770 
771 /************************ EO APIs ***************************/
772 
803 extern ClRcT clEoWalk(
804  CL_IN ClEoExecutionObjT *pThis,
805  CL_IN ClUint32T func,
806  CL_IN ClEoCallFuncCallbackT pFuncCallout,
807  CL_IN ClBufferHandleT inMsgHdl,
808  CL_OUT ClBufferHandleT outMsgHdl);
809 
810 extern ClRcT clEoWalkWithVersion(
811  CL_IN ClEoExecutionObjT *pThis,
812  CL_IN ClUint32T func,
813  CL_IN ClVersionT *version,
814  CL_IN ClEoCallFuncCallbackT pFuncCallout,
815  CL_IN ClBufferHandleT inMsgHdl,
816  CL_OUT ClBufferHandleT outMsgHdl);
817 
846  CL_IN ClEoExecutionObjT *pThis,
847  CL_IN ClUint32T func);
848 
849 
882 extern ClRcT clEoClientInstall(
883  CL_IN ClEoExecutionObjT *pThis,
884  CL_IN ClUint32T clientId,
886  CL_IN ClEoDataT data,
887  CL_IN ClUint32T nFuncs);
888 
889 extern ClRcT clEoClientInstallTable(
890  CL_IN ClEoExecutionObjT *pThis,
891  CL_IN ClUint32T clientId,
892  CL_IN ClEoDataT data,
893  CL_IN ClEoPayloadWithReplyCallbackServerT *pFuncs,
894  CL_IN ClUint32T nFuncs);
895 
924  CL_IN ClEoExecutionObjT *pThis,
925  CL_IN ClUint32T clientId);
926 
927 extern ClRcT clEoClientUninstallTable(ClEoExecutionObjT *pThis,
928  ClUint32T clientID,
929  ClEoPayloadWithReplyCallbackServerT *pfunTable,
930  ClUint32T nentries);
931 
957 extern ClRcT clEoClientDataSet(
958  CL_IN ClEoExecutionObjT *pThis,
959  CL_IN ClUint32T clientId,
960  CL_IN ClEoDataT data);
961 
962 
988 extern ClRcT clEoClientDataGet(
989  CL_IN ClEoExecutionObjT *pThis,
990  CL_IN ClUint32T clientId,
991  CL_OUT ClEoDataT *pData);
992 
993 
994 
1028 extern ClRcT clEoServiceInstall(
1029  CL_IN ClEoExecutionObjT *pThis,
1031  CL_IN ClUint32T iFuncNum,
1033 
1064  CL_IN ClEoExecutionObjT *pThis,
1066  CL_IN ClUint32T iFuncNum);
1067 
1068 
1095 extern ClRcT clEoPrivateDataSet(
1096  CL_IN ClEoExecutionObjT *pThis,
1097  CL_IN ClUint32T type,
1098  CL_IN void *pData);
1099 
1100 
1101 
1129  CL_IN ClUint32T type,
1130  CL_OUT void **data);
1131 
1132 
1133 
1155 extern ClRcT clEoMyEoIocPortSet(
1156  CL_IN ClIocPortT iocPort);
1157 
1158 
1159 
1184 extern ClRcT clEoMyEoIocPortGet(
1185  CL_OUT ClIocPortT *pIocPort);
1186 
1187 
1188 
1211 extern ClRcT clEoMyEoObjectSet(
1212  CL_IN ClEoExecutionObjT* eoObj);
1213 
1214 
1215 
1239 extern ClRcT clEoMyEoObjectGet(
1240  CL_OUT ClEoExecutionObjT** pEOObj);
1241 
1242 
1266 extern ClRcT clEoReceiveStart(
1267  CL_IN ClEoExecutionObjT *pThis);
1268 
1269 
1270 
1271 
1272 /***********************************************************************/
1273 /* external symbols we expect here */
1274 /***********************************************************************/
1275 
1276 /*
1277  * This is the configuration for an EO. Since we can only do one EO
1278  * per process in RC1, this can be here. But when support for multiple
1279  * EOs per process shows up, this has to be fixed in some way.
1280  */
1281 
1282 extern ClEoConfigT clEoConfig;
1283 
1284 /*
1285  * The list of libraries to initialize and finalize. The order of elements in
1286  * the array are as follows:
1287  *
1288  * Basic and mandatory libs in clEoBasicLibs[]. These have to be set to
1289  * CL_TRUE:
1290  * Osal
1291  * Timer
1292  * Buffer
1293  * Ioc
1294  * Rmd
1295  * Eo
1296  *
1297  * Basic and optional libs in clEoBasicLibs[]. These can be CL_TRUE or
1298  * CL_FALSE:
1299  * Om
1300  * Hal
1301  * Dbal
1302  *
1303  * These are the really optional client libs in clEoClientLibs[]. These
1304  * can be either CL_TRUE or CL_FALSE:
1305  * Cor
1306  * Cm
1307  * Name
1308  * Log
1309  * Trace
1310  * Diag
1311  * Txn
1312  * Hpi
1313  * Cli
1314  * Alarm
1315  * Gms
1316  */
1317 
1318 extern ClUint8T clEoBasicLibs[];
1319 
1320 extern ClUint8T clEoClientLibs[];
1321 
1322 
1323 #ifdef __cplusplus
1324 }
1325 
1326 #endif
1327 
1328 
1329 #endif /* _CL_EO_API_H_ */
1330 

Generated on Tue Jan 10 10:29:15 PST 2012 for OpenClovis SDK using Doxygen