OpenClovis Logo

clIocApi.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 : ioc
21  * File : clIocApi.h
22  *******************************************************************************/
23 
24 /*******************************************************************************
25  * Description :
26  *
27  * Ioc data structures and APIs
28  *
29  *
30  *****************************************************************************/
31 
32 /*****************************************************************************/
33 /******************************** IOC APIs ***********************************/
34 /*****************************************************************************/
35 /*
36  */
37 /*
38  * clIocCommPortCreate
39  */
40 /*
41  * clIocCommPortDelete
42  */
43 /*
44  * clIocSend
45  */
46 /*
47  * clIocReceive
48  */
49 /*
50  * clIocTransparencyRegister
51  */
52 /*
53  * clIocTransparencyDeregister
54  */
55 /*
56  * clIocLocalAddressGet
57  */
58 /*
59  * clIocBind
60  */
61 /*
62  * clIocVersionCheck
63  */
64 /*
65  */
66 /*****************************************************************************/
67 
81 #ifndef _CL_IOC_API_H_
82 # define _CL_IOC_API_H_
83 
84 # ifdef __cplusplus
85 extern "C"
86 {
87 # endif
88 
89 
90 /*****************************************************************************/
91 /*********************** User configurable parameters ************************/
92 /*****************************************************************************/
93 # include <clCommon.h>
94 # include <clBufferApi.h>
95 # include <clIocServices.h>
96 # include <clIocProtocols.h>
97 # include <clIocErrors.h>
98 
99 /*
100  * Defines
101  */
102 
103 
107 # define CL_IOC_HEADER_VERSION 1
108 
109 # define CL_IOC_NOTIFICATION_VERSION 1
110 
111 
115 # define CL_IOC_TIMEOUT_FOREVER ~0U
116 # define CL_IOC_RECEIVE_TIMEOUT 1500
117 
118 
123 # define CL_IOC_UNRELIABLE_MESSAGING 0
124 
129 # define CL_IOC_RELIABLE_MESSAGING (1<<0)
130 
131 
132 
133 
134  /*
135  * The node status and ARP related flags.
136  */
137 
138 
142 # define CL_IOC_NODE_UP 1
143 
147 # define CL_IOC_NODE_DOWN 0
148 
149 
150 
151 
155 # define CL_IOC_LINK_UP 2
156 
160 # define CL_IOC_LINK_DOWN 3
161 
162 
163 
164 
168 # define CL_IOC_BROADCAST_ADDRESS 0xffffffff
169 
173 # define CL_IOC_RESERVED_ADDRESS 0
174 
178 # define CL_IOC_GEO_ADDR_MAX_LENGTH 128
179 
180 
181 
182 
186 # define CL_IOC_PHYSICAL_ADDRESS_TYPE 0
187 
191 # define CL_IOC_LOGICAL_ADDRESS_TYPE 1
192 
196 # define CL_IOC_MULTICAST_ADDRESS_TYPE 2
197 
198 /*
199  * Master address type
200  */
201 # define CL_IOC_MASTER_ADDRESS_TYPE 3
202 
203 /*
204  * Local commport address type
205  */
206 # define CL_IOC_INTRANODE_ADDRESS_TYPE 4
207 
208 
209 # define CL_IOC_USER_ADDRESS_TYPE 10
210 
214 # define CL_IOC_BROADCAST_ADDRESS_TYPE 0xff
215 
216  /*
217  * Rest of the addresses are not valid
218  */
219 
220 
224 typedef enum {
229 
234 
239 
240  /*
241  * This is the priority for sending ordered proto messages,
242  * delivered in order
243  */
244  CL_IOC_ORDERED_PRIORITY = 3,
245 
246  /*
247  * This is the priority for sending notification protos in order
248  */
249  CL_IOC_NOTIFICATION_PRIORITY = 4,
250 
255 
256  CL_IOC_RESERVED_PRIORITY_USER = 6,
257 
258  CL_IOC_RESERVED_PRIORITY_USER_END = 16,
259 
263  CL_IOC_MAX_PRIORITIES = CL_IOC_RESERVED_PRIORITY_USER_END + 1
265 
266 
267 
271 typedef enum {
276 
282 
283 
284 
285 #define CL_IOC_ADDRESS_TYPE_BITS (0x8)
286 #define CL_IOC_ADDRESS_TYPE_MASK ((1<<CL_IOC_ADDRESS_TYPE_BITS)-1)
287 #define CL_IOC_NODE_MASK (~0U >> CL_IOC_ADDRESS_TYPE_BITS)
288 #define CL_IOC_ADDRESS_TYPE_SHIFT_WORD (32-CL_IOC_ADDRESS_TYPE_BITS)
289 #define CL_IOC_ADDRESS_TYPE_SHIFT_DWORD (64-CL_IOC_ADDRESS_TYPE_BITS)
294 # define CL_IOC_ADDRESS_TYPE_GET(param)\
295  ((ClUint32T)((*((ClUint64T*)(param))) >> CL_IOC_ADDRESS_TYPE_SHIFT_DWORD))
296 
297 #define CL_IOC_ADDRESS_FORM(addrType,addr,compId) \
298  (ClUint64T)( \
299  ( (((ClUint64T)(addrType)) & CL_IOC_ADDRESS_TYPE_MASK) << CL_IOC_ADDRESS_TYPE_SHIFT_DWORD ) | \
300  ( ( ((ClUint64T)(addr)) & CL_IOC_NODE_MASK) << 32 ) | \
301  ( ((ClUint64T)(compId)) & 0xffffffff ) \
302  )
303 
304 #define CL_IOC_TIPC_ADDRESS_TYPE_FORM(t,v) (((t) << CL_IOC_ADDRESS_TYPE_SHIFT_WORD) | ( (v) & CL_IOC_NODE_MASK ) )
305 
306 #define CL_IOC_TIPC_TYPE_FORM(v) \
307  CL_IOC_TIPC_ADDRESS_TYPE_FORM(CL_IOC_USER_ADDRESS_TYPE,v)
308 
312 # define CL_IOC_LOGICAL_ADDRESS_FORM(compId)\
313  CL_IOC_ADDRESS_FORM(CL_IOC_LOGICAL_ADDRESS_TYPE, 0 , compId)
314 
318 # define CL_IOC_MULTICAST_ADDRESS_FORM(addr, compId) \
319  CL_IOC_ADDRESS_FORM(CL_IOC_MULTICAST_ADDRESS_TYPE, addr, compId)
320 
321 
326 # define CL_IOC_TL_ACTIVE 0
327 
332 # define CL_IOC_TL_STDBY 1
333 
334 
335 
336  /*
337  * Type definitions
338  */
339 
343  typedef ClUint32T ClIocNodeAddressT;
344 
348  typedef ClUint32T ClIocPortT;
349 
353  typedef ClWordT ClIocCommPortHandleT;
354 
358  typedef ClHandleT ClIocToBindHandleT;
359 
360 
366  typedef ClUint32T ClIocCommPortFlagsT;
367 
371  typedef ClUint64T ClIocLogicalAddressT;
372 
376  typedef ClUint64T ClIocMulticastAddressT;
377 
378 
382  typedef struct ClIocPhysicalAddress
383  {
384 
389 
394 
396 
400  typedef union ClIocAddress
401  {
402 
407 
412 
417 
418 
420 
421 
422 
423 
424 
425 
426 
427 
428 
429 
430 
434  typedef enum ClIocMessageOption
435  {
441 
448 
449 
450 
451 
452 
456  typedef struct ClIocSendOption
457  {
458 
462  ClUint8T priority;
463 
467  ClUint8T sendType;
471  ClWordT linkHandle;
472 
477 
481  ClUint32T timeout;
482 
484 
485 
486 
490  typedef struct ClIocRecvParam
491  {
495  ClUint8T priority;
496 
500  ClUint8T protoType;
501 
505  ClUint32T length;
506 
511 
513 
514 
515 
516 
517 
522  typedef struct ClIocRecvOption
523  {
524 
528  ClUint32T recvTimeout;
530 
531  typedef enum ClIocQueueId
532  {
533  CL_IOC_SENDQ,
534  CL_IOC_RECVQ,
535  CL_IOC_QUEUE_MAX,
536  } ClIocQueueIdT;
537 
538  typedef struct ClIocQueueInfo
539  {
540  ClUint32T queueSize;
541  ClWaterMarkT queueWM;
542  } ClIocQueueInfoT;
543 
544  typedef struct ClIocQueueStats
545  {
546  ClIocQueueInfoT queueInfo;
547  ClUint32T queueUtilisation;
548  } ClIocQueueStatsT;
549 
550  typedef struct ClIocLibConfig
551  {
555  ClUint8T version;
559  ClIocNodeAddressT nodeAddress;
563  ClCharT iocGeoGraphicalAddress[CL_IOC_GEO_ADDR_MAX_LENGTH + 1];
567  ClUint32T iocMaxNumOfPriorities;
571  ClUint32T iocReassemblyTimeOut;
575  ClUint32T iocMaxNumOfXports;
579  ClUint32T iocHeartbeatTimeInterval;
583  ClUint32T iocTLMaxEntries;
584 
585  /*SendQ config*/
586  ClIocQueueInfoT iocSendQInfo;
587 
588  /*RecvQ config*/
589  ClIocQueueInfoT iocRecvQInfo;
590 
591  /*The port to which the global sendq events should be sent*/
592  ClIocPortT iocNodeRepresentative;
593 
594  /*The port to which the global sendq events should be sent*/
595  ClBoolT isNodeRepresentative;
596 
597  } ClIocLibConfigT;
598 
599 
600 /*****************************************************************************/
601 /***************** Transparency Layer related data structures ****************/
602 /*****************************************************************************/
603 
607  typedef enum ClIocTLContext
608  {
609 
614 
620 
621 
622 
623 
627  typedef struct
628  {
632  ClUint32T haState;
633 
638  } ClIocTLMappingT;
639 
640 
641 /* This is kept only for backward compatibility */
642 #define CL_IOC_TL_NO_REPLICATION 0
643 #define repliSemantics unused
644 
648  typedef struct ClIocTlInfo
649  {
650 
655 
659  ClUint32T compId;
660 
665 
669  ClUint32T unused;
670 
674  ClUint32T haState;
675 
680 
682 
683 
684  typedef struct ClIocMcastUserInfo
685  {
686  ClIocMulticastAddressT mcastAddr; /* multicast address */
687  ClIocPhysicalAddressT physicalAddr; /* IOC physical address */
688  } ClIocMcastUserInfoT;
689 
690 
691 /*****************************************************************************
692  * IOC APIs
693  *****************************************************************************/
694 
695 
743  CL_IN ClIocPortT portId,
744  CL_IN ClIocCommPortFlagsT portType,
745  CL_OUT ClIocCommPortHandleT * pIocCommPortHdl
746  );
747 
748 
749 
750 
779  CL_IN ClIocCommPortHandleT iocCommPortHdl
780  );
781 
782 
819  CL_IN ClIocCommPortHandleT portHandle,
820  CL_INOUT ClInt32T *pSd
821  );
822 
853  CL_IN ClIocCommPortHandleT pIocCommPort,
854  CL_OUT ClIocPortT * pPortId
855  );
856 
857 
890  CL_IN ClIocPortT port,
892  );
893 
894 
997  CL_IN ClIocCommPortHandleT commPortHandle,
998  CL_IN ClBufferHandleT message,
999  CL_IN ClUint8T protoType,
1000  CL_IN ClIocAddressT * pDestAddr,
1001  CL_IN ClIocSendOptionT * pSendOption
1002  );
1003 
1004 
1005 
1062  CL_IN ClIocCommPortHandleT commPortHdl,
1063  CL_IN ClIocRecvOptionT * pRecvOption,
1064  CL_OUT ClBufferHandleT userMsg,
1065  CL_OUT ClIocRecvParamT * pRecvParam
1066  );
1067 
1068  ClRcT clIocReceiveAsync(
1069  CL_IN ClIocCommPortHandleT commPortHdl,
1070  CL_IN ClIocRecvOptionT * pRecvOption,
1071  CL_OUT ClBufferHandleT userMsg,
1072  CL_OUT ClIocRecvParamT * pRecvParam
1073  );
1074 
1075  ClRcT clIocReceiveWithBuffer(
1076  CL_IN ClIocCommPortHandleT commPortHdl,
1077  CL_IN ClIocRecvOptionT * pRecvOption,
1078  CL_IN ClUint8T *buffer,
1079  CL_IN ClUint32T bufSize,
1080  CL_OUT ClBufferHandleT userMsg,
1081  CL_OUT ClIocRecvParamT * pRecvParam
1082  );
1083 
1084  ClRcT clIocReceiveWithBufferAsync(
1085  CL_IN ClIocCommPortHandleT commPortHdl,
1086  CL_IN ClIocRecvOptionT * pRecvOption,
1087  CL_IN ClUint8T *buffer,
1088  CL_IN ClUint32T bufSize,
1089  CL_OUT ClBufferHandleT userMsg,
1090  CL_OUT ClIocRecvParamT * pRecvParam
1091  );
1092 
1093 
1125  CL_IN ClIocCommPortHandleT commPortHdl
1126  );
1127 
1128 
1129 
1130 
1131 /*********************************************************************************/
1132 /************************ Transparency Layer APIs ******************************/
1133 /*********************************************************************************/
1134 
1135 
1136 
1179  CL_IN ClIocTLInfoT * pTLInfo
1180  );
1181 
1182 
1183 
1210  CL_IN ClUint32T compId
1211  );
1212 
1213 
1214 
1215 
1247  ClRcT clIocMulticastRegister(CL_IN ClIocMcastUserInfoT *pMcastInfo);
1248 
1285  ClRcT clIocMulticastDeregister(CL_IN ClIocMcastUserInfoT *pMcastInfo);
1286 
1328 
1329 
1330 
1331 
1355  void
1356  );
1357 
1358 
1359 
1360 
1385  CL_IN ClVersionT * pVersion
1386  );
1387 
1388 
1389 #if 0
1390 
1391  ClRcT clIocTransparencyDeregisterNode(
1392  CL_IN ClIocNodeAddressT nodeId
1393  ) CL_DEPRECATED;
1394 
1395 #endif
1396 
1397  ClRcT clIocTransparencyLogicalToPhysicalAddrGet(
1398  CL_IN ClIocLogicalAddressT logicalAddr,
1399  CL_OUT ClIocTLMappingT ** pPhysicalAddr,
1400  CL_OUT ClUint32T * pNoEntries
1401  ) CL_DEPRECATED;
1402 
1403 
1404 # ifdef __cplusplus
1405 }
1406 # endif
1407 #endif /* _CL_IOC_API_H_ */
1408 
Typical defines found in any software project.
Header file of Buffer Management related APIs.
Header file of Ioc Error Codes.
Header file of Ioc Protocols.
Header file of Reserved Communication Ports.
ClPtrT ClBufferHandleT
The type of the handle for the buffer messages.
Definition: clBufferApi.h:82
ClUint32T ClRcT
Clovis return code type.
Definition: clCommon.h:168
#define CL_INOUT
CL_INOUT macro assists in clearly defining arguments of an API, but has no actual meaning.
Definition: clCommon.h:108
#define CL_OUT
CL_OUT macro assists in clearly defining arguments of an API, but has no actual meaning.
Definition: clCommon.h:110
#define CL_IN
CL_IN macro assists in clearly defining arguments of an API, but has no actual meaning.
Definition: clCommon.h:106
struct ClIocRecvParam ClIocRecvParamT
The IOC receive returns this structure along with the message.
ClWordT ClIocCommPortHandleT
The Communication port handle.
Definition: clIocApi.h:353
ClRcT clIocMulticastRegister(CL_IN ClIocMcastUserInfoT *pMcastInfo)
Registers an application against a multicast address with IOC Multicast Layer.
struct ClIocTlInfo ClIocTLInfoT
Transparency layer parameters.
ClUint64T ClIocMulticastAddressT
IOC Multicast address.
Definition: clIocApi.h:376
struct ClIocSendOption ClIocSendOptionT
Send related options.
ClRcT clIocReceive(CL_IN ClIocCommPortHandleT commPortHdl, CL_IN ClIocRecvOptionT *pRecvOption, CL_OUT ClBufferHandleT userMsg, CL_OUT ClIocRecvParamT *pRecvParam)
Receives message on communication port.
ClIocNotificationActionT
This defines all notification related actions that can be performed on a port.
Definition: clIocApi.h:271
ClUint64T ClIocLogicalAddressT
IOC Logical address.
Definition: clIocApi.h:371
ClRcT clIocCommPortReceiverUnblock(CL_IN ClIocCommPortHandleT commPortHdl)
Unblocks all receive calls.
union ClIocAddress ClIocAddressT
IOC address.
ClRcT clIocCommPortDelete(CL_IN ClIocCommPortHandleT iocCommPortHdl)
Deletes the communication port.
ClIocNodeAddressT clIocLocalAddressGet(void)
Returns the local IOC node addrress.
ClRcT clIocCommPortGet(CL_IN ClIocCommPortHandleT pIocCommPort, CL_OUT ClIocPortT *pPortId)
Returns the port Id.
ClUint32T ClIocCommPortFlagsT
Port Type.
Definition: clIocApi.h:366
ClUint32T ClIocPortT
The IOC communication port.
Definition: clIocApi.h:348
#define CL_IOC_GEO_ADDR_MAX_LENGTH
The maximum size of the geographical address.
Definition: clIocApi.h:178
enum ClIocTLContext ClIocTLContextT
Transparency layer context.
ClIocTLContext
Transparency layer context.
Definition: clIocApi.h:608
ClIocMessageOption
The send message option.
Definition: clIocApi.h:435
ClRcT clIocSend(CL_IN ClIocCommPortHandleT commPortHandle, CL_IN ClBufferHandleT message, CL_IN ClUint8T protoType, CL_IN ClIocAddressT *pDestAddr, CL_IN ClIocSendOptionT *pSendOption)
Sends message on a communication port.
struct ClIocRecvOption ClIocRecvOptionT
IOC receive options.
ClIocPriorityT
This defines all the priorities that can be used with IOC.
Definition: clIocApi.h:224
ClRcT clIocTransparencyDeregister(CL_IN ClUint32T compId)
De-registers the application with Transparency Layer.
ClRcT clIocCommPortFdGet(CL_IN ClIocCommPortHandleT portHandle, CL_INOUT ClInt32T *pSd)
Gets the socket descriptor used by communication of a CommPort.
ClRcT clIocCommPortCreate(CL_IN ClIocPortT portId, CL_IN ClIocCommPortFlagsT portType, CL_OUT ClIocCommPortHandleT *pIocCommPortHdl)
Creates a communication port.
ClRcT clIocVersionCheck(CL_IN ClVersionT *pVersion)
Checks for appropriate version of application.
ClRcT clIocMulticastDeregister(CL_IN ClIocMcastUserInfoT *pMcastInfo)
De-registers the application against a multicast address with the IOC Multicast Layer.
ClRcT clIocTransparencyRegister(CL_IN ClIocTLInfoT *pTLInfo)
Registers an application's logical address with Transparency Layer.
struct ClIocPhysicalAddress ClIocPhysicalAddressT
The IOC Physical address of an application's communication end point.
ClHandleT ClIocToBindHandleT
The Transport handle.
Definition: clIocApi.h:358
enum ClIocMessageOption ClIocMessageOptionT
The send message option.
ClUint32T ClIocNodeAddressT
The IOC node address.
Definition: clIocApi.h:343
ClRcT clIocPortNotification(CL_IN ClIocPortT port, CL_IN ClIocNotificationActionT action)
Enables/Disables the notifications form IOC on the port.
ClRcT clIocMulticastDeregisterAll(CL_IN ClIocMulticastAddressT *pMcastAddress)
De-registers the application against a multicast address with the IOC Multicast Layer.
@ CL_IOC_NOTIFICATION_DISABLE
Disables component/node arrival/departure notifications.
Definition: clIocApi.h:275
@ CL_IOC_NOTIFICATION_ENABLE
Enable scomponent/node arrival/departure notifications.
Definition: clIocApi.h:280
@ CL_IOC_TL_LOCAL_SCOPE
The context for local scope entries.
Definition: clIocApi.h:618
@ CL_IOC_TL_GLOBAL_SCOPE
The context for Global scope entries.
Definition: clIocApi.h:613
@ CL_IOC_NON_PERSISTENT_MSG
The message is non persistent in nature and is consumed by IOC on send.
Definition: clIocApi.h:446
@ CL_IOC_PERSISTENT_MSG
The message is persistent in nature and is not consumed by IOC on send.
Definition: clIocApi.h:440
@ CL_IOC_DEFAULT_PRIORITY
This is the default priority.
Definition: clIocApi.h:228
@ CL_IOC_HIGH_PRIORITY
This is the higest priority with which a packet can be sent.
Definition: clIocApi.h:233
@ CL_IOC_LOW_PRIORITY
This is the lowest priority.
Definition: clIocApi.h:238
@ CL_IOC_RESERVED_PRIORITY
This is reserved by IOC for future use.
Definition: clIocApi.h:254
@ CL_IOC_MAX_PRIORITIES
This limits the use of the number of priorities that can be used with IOC.
Definition: clIocApi.h:263
Version Information for various services.
Definition: clCommon.h:250
The IOC Physical address of an application's communication end point.
Definition: clIocApi.h:383
ClIocPortT portId
The IOC communication end point identification on a node.
Definition: clIocApi.h:393
ClIocNodeAddressT nodeAddress
The IOC Node address.
Definition: clIocApi.h:388
IOC address.
Definition: clIocApi.h:401
ClIocPhysicalAddressT iocPhyAddress
Physical address.
Definition: clIocApi.h:406
ClIocMulticastAddressT iocMulticastAddress
Multicast address.
Definition: clIocApi.h:416
ClIocLogicalAddressT iocLogicalAddress
Logical address.
Definition: clIocApi.h:411
Send related options.
Definition: clIocApi.h:457
ClUint8T sendType
The send type, it can be session based or not.
Definition: clIocApi.h:467
ClUint32T timeout
The timeout interval in milliseconds.
Definition: clIocApi.h:481
ClWordT linkHandle
The Handle for uniquely identifying Transport and Link.
Definition: clIocApi.h:471
ClUint8T priority
Message priority.
Definition: clIocApi.h:462
ClIocMessageOptionT msgOption
The message type, it can be persistent or non persistent message.
Definition: clIocApi.h:476
The IOC receive returns this structure along with the message.
Definition: clIocApi.h:491
ClUint32T length
Length of the message received.
Definition: clIocApi.h:505
ClUint8T protoType
Protocol used.
Definition: clIocApi.h:500
ClUint8T priority
Priority of the message received.
Definition: clIocApi.h:495
ClIocAddressT srcAddr
Sender address.
Definition: clIocApi.h:510
IOC receive options.
Definition: clIocApi.h:523
ClUint32T recvTimeout
Timeout value for blocking call.
Definition: clIocApi.h:528
Data-type for holding the physical address and its state.
Definition: clIocApi.h:628
ClIocPhysicalAddressT physicalAddr
Physical address of the component.
Definition: clIocApi.h:637
ClUint32T haState
State of the component corresponding to the physicalAddr.
Definition: clIocApi.h:632
Transparency layer parameters.
Definition: clIocApi.h:649
ClUint32T haState
Active or Standby mode.
Definition: clIocApi.h:674
ClUint32T compId
Id of the component providing the service.
Definition: clIocApi.h:659
ClUint32T unused
Replication Semantics.
Definition: clIocApi.h:669
ClIocLogicalAddressT logicalAddr
Logical address of the service.
Definition: clIocApi.h:654
ClIocPhysicalAddressT physicalAddr
Physical address of the component.
Definition: clIocApi.h:679
ClIocTLContextT contextType
Context, it can be either GLOBAL or LOCAL.
Definition: clIocApi.h:664

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