clIocApi.h

Go to the documentation of this file.

/*
 * Copyright (C) 2002-2012 OpenClovis Solutions Inc.  All Rights Reserved.
 *
 * This file is available  under  a  commercial  license  from  the
 * copyright  holder or the GNU General Public License Version 2.0.
 * 
 * The source code for  this program is not published  or otherwise 
 * divested of  its trade secrets, irrespective  of  what  has been 
 * deposited with the U.S. Copyright office.
 * 
 * This program is distributed in the  hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied  warranty  of 
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 
 * General Public License for more details.
 * 
 * For more  information, see  the file  COPYING provided with this
 * material.
 */
/*******************************************************************************
 * ModuleName  : ioc
 * File        : clIocApi.h
 *******************************************************************************/

/*******************************************************************************
 * Description :
 *
 * Ioc data structures and APIs
 *
 *
 *****************************************************************************/

/*****************************************************************************/
/******************************** IOC APIs ***********************************/
/*****************************************************************************/
/*
 */
/*
 * clIocCommPortCreate
 */
/*
 * clIocCommPortDelete
 */
/*
 * clIocSend
 */
/*
 * clIocReceive
 */
/*
 * clIocTransparencyRegister
 */
/*
 * clIocTransparencyDeregister
 */
/*
 * clIocLocalAddressGet
 */
/*
 * clIocBind
 */
/*
 * clIocVersionCheck
 */
/*
 */
/*****************************************************************************/

#ifndef _CL_IOC_API_H_
# define _CL_IOC_API_H_

# ifdef __cplusplus
extern "C"
{
# endif


/*****************************************************************************/
/*********************** User configurable parameters ************************/
/*****************************************************************************/
# include <clCommon.h>
# include <clBufferApi.h>
# include <clIocServices.h>
# include <clIocProtocols.h>
# include <clIocErrors.h>

/*
 * Defines
 */


# define CL_IOC_HEADER_VERSION 1

# define CL_IOC_NOTIFICATION_VERSION 1


# define CL_IOC_TIMEOUT_FOREVER ~0U


# define CL_IOC_UNRELIABLE_MESSAGING 0

# define CL_IOC_RELIABLE_MESSAGING (1<<0)




    /*
     * The node status and ARP related flags.
     */


# define CL_IOC_NODE_UP 1

# define CL_IOC_NODE_DOWN 0




# define CL_IOC_LINK_UP 2

# define CL_IOC_LINK_DOWN 3




# define CL_IOC_BROADCAST_ADDRESS  0xffffffff

# define CL_IOC_RESERVED_ADDRESS  0

# define CL_IOC_GEO_ADDR_MAX_LENGTH 128




# define CL_IOC_PHYSICAL_ADDRESS_TYPE       0

# define CL_IOC_LOGICAL_ADDRESS_TYPE        1

# define CL_IOC_MULTICAST_ADDRESS_TYPE      2

/* 
 * Master address type
 */
# define CL_IOC_MASTER_ADDRESS_TYPE         3

/*
 * Local commport address type
 */
# define CL_IOC_INTRANODE_ADDRESS_TYPE      4


# define CL_IOC_USER_ADDRESS_TYPE          10 

# define CL_IOC_BROADCAST_ADDRESS_TYPE   0xff

    /*
     * Rest of the addresses are not valid
     */


typedef enum {
    CL_IOC_DEFAULT_PRIORITY   = 0,

    CL_IOC_HIGH_PRIORITY      = 1,

    CL_IOC_LOW_PRIORITY       = 2,

    /*
     * This is the priority for sending ordered proto messages, 
     * delivered in order
     */
    CL_IOC_ORDERED_PRIORITY = 3,

    /* 
     * This is the priority for sending notification protos in order
     */      
    CL_IOC_NOTIFICATION_PRIORITY = 4,

    CL_IOC_RESERVED_PRIORITY  = 5,

    CL_IOC_RESERVED_PRIORITY_USER = 6,

    CL_IOC_RESERVED_PRIORITY_USER_END = 16,

    CL_IOC_MAX_PRIORITIES     = CL_IOC_RESERVED_PRIORITY_USER_END + 1
} ClIocPriorityT;



typedef enum {
    CL_IOC_NOTIFICATION_DISABLE = 0,

    CL_IOC_NOTIFICATION_ENABLE,
} ClIocNotificationActionT;



#define CL_IOC_ADDRESS_TYPE_BITS (0x8)
#define CL_IOC_ADDRESS_TYPE_MASK ((1<<CL_IOC_ADDRESS_TYPE_BITS)-1)
#define CL_IOC_NODE_MASK (~0U >> CL_IOC_ADDRESS_TYPE_BITS)
#define CL_IOC_ADDRESS_TYPE_SHIFT_WORD (32-CL_IOC_ADDRESS_TYPE_BITS)
#define CL_IOC_ADDRESS_TYPE_SHIFT_DWORD (64-CL_IOC_ADDRESS_TYPE_BITS)

# define CL_IOC_ADDRESS_TYPE_GET(param)\
    ((ClUint32T)((*((ClUint64T*)(param))) >> CL_IOC_ADDRESS_TYPE_SHIFT_DWORD))

#define CL_IOC_ADDRESS_FORM(addrType,addr,compId)                       \
    (ClUint64T)(                                                        \
    ( (((ClUint64T)(addrType)) & CL_IOC_ADDRESS_TYPE_MASK) << CL_IOC_ADDRESS_TYPE_SHIFT_DWORD ) | \
    ( ( ((ClUint64T)(addr)) & CL_IOC_NODE_MASK) << 32 )    |                      \
    ( ((ClUint64T)(compId)) & 0xffffffff )                              \
    )

#define CL_IOC_TIPC_ADDRESS_TYPE_FORM(t,v) (((t) << CL_IOC_ADDRESS_TYPE_SHIFT_WORD) | ( (v) & CL_IOC_NODE_MASK ) )

#define CL_IOC_TIPC_TYPE_FORM(v)                                \
    CL_IOC_TIPC_ADDRESS_TYPE_FORM(CL_IOC_USER_ADDRESS_TYPE,v)

# define CL_IOC_LOGICAL_ADDRESS_FORM(compId)\
     CL_IOC_ADDRESS_FORM(CL_IOC_LOGICAL_ADDRESS_TYPE, 0 , compId)

# define CL_IOC_MULTICAST_ADDRESS_FORM(addr, compId)                         \
     CL_IOC_ADDRESS_FORM(CL_IOC_MULTICAST_ADDRESS_TYPE, addr, compId)


# define CL_IOC_TL_ACTIVE 0

# define CL_IOC_TL_STDBY  1



    /*
     * Type definitions
     */

    typedef ClUint32T ClIocNodeAddressT;

    typedef ClUint32T ClIocPortT;

    typedef ClWordT ClIocCommPortHandleT;

    typedef ClHandleT ClIocToBindHandleT;


    typedef ClUint32T ClIocCommPortFlagsT;

    typedef ClUint64T ClIocLogicalAddressT;

    typedef ClUint64T ClIocMulticastAddressT;


    typedef struct ClIocPhysicalAddress
    {

        ClIocNodeAddressT nodeAddress;

        ClIocPortT portId;

    } ClIocPhysicalAddressT;

    typedef union ClIocAddress
    {

        ClIocPhysicalAddressT iocPhyAddress;

        ClIocLogicalAddressT iocLogicalAddress;
        
        ClIocMulticastAddressT iocMulticastAddress;


    } ClIocAddressT;











    typedef enum ClIocMessageOption
    {
        CL_IOC_PERSISTENT_MSG = 0,

        CL_IOC_NON_PERSISTENT_MSG
    } ClIocMessageOptionT;





    typedef struct ClIocSendOption
    {

        ClUint8T priority;

        ClUint8T sendType;
        ClWordT linkHandle;

        ClIocMessageOptionT msgOption;

        ClUint32T timeout;

    } ClIocSendOptionT;



    typedef struct ClIocRecvParam
    {
        ClUint8T priority;

        ClUint8T protoType;

        ClUint32T length;

        ClIocAddressT srcAddr;

    } ClIocRecvParamT;





    typedef struct ClIocRecvOption
    {

        ClUint32T recvTimeout;
    } ClIocRecvOptionT;

    typedef enum ClIocQueueId
    {
        CL_IOC_SENDQ,
        CL_IOC_RECVQ,
        CL_IOC_QUEUE_MAX,
    } ClIocQueueIdT;

    typedef struct ClIocQueueInfo
    {
        ClUint32T queueSize;
        ClWaterMarkT queueWM;
    } ClIocQueueInfoT;

    typedef struct ClIocQueueStats
    {
        ClIocQueueInfoT queueInfo;
        ClUint32T queueUtilisation;
    } ClIocQueueStatsT;

    typedef struct ClIocLibConfig
    {
        ClUint8T version;
        ClIocNodeAddressT nodeAddress;
        ClCharT iocGeoGraphicalAddress[CL_IOC_GEO_ADDR_MAX_LENGTH + 1];
        ClUint32T iocMaxNumOfPriorities;
        ClUint32T iocReassemblyTimeOut;
        ClUint32T iocMaxNumOfXports;
        ClUint32T iocHeartbeatTimeInterval;
        ClUint32T iocTLMaxEntries;

        /*SendQ config*/
        ClIocQueueInfoT iocSendQInfo;

        /*RecvQ config*/
        ClIocQueueInfoT iocRecvQInfo;

        /*The port to which the global sendq events should be sent*/
        ClIocPortT iocNodeRepresentative;

        /*The port to which the global sendq events should be sent*/
        ClBoolT isNodeRepresentative;

    } ClIocLibConfigT;


/*****************************************************************************/
/***************** Transparency Layer related data structures ****************/
/*****************************************************************************/

    typedef enum ClIocTLContext
    {

        CL_IOC_TL_GLOBAL_SCOPE,

        CL_IOC_TL_LOCAL_SCOPE
    } ClIocTLContextT;




    typedef struct
    {
        ClUint32T haState;

        ClIocPhysicalAddressT physicalAddr;
    } ClIocTLMappingT;


/* This is kept only for backward compatibility */
#define CL_IOC_TL_NO_REPLICATION      0
#define repliSemantics                unused

    typedef struct ClIocTlInfo
    {

        ClIocLogicalAddressT logicalAddr;

        ClUint32T compId;

        ClIocTLContextT contextType;

        ClUint32T unused;

        ClUint32T haState;

        ClIocPhysicalAddressT physicalAddr;

    } ClIocTLInfoT;


    typedef struct ClIocMcastUserInfo
    {
        ClIocMulticastAddressT mcastAddr;   /* multicast address */
        ClIocPhysicalAddressT physicalAddr; /* IOC physical address */
    } ClIocMcastUserInfoT;


/*****************************************************************************
 *  IOC APIs
 *****************************************************************************/


    ClRcT clIocCommPortCreate(
    CL_IN ClIocPortT portId,
    CL_IN ClIocCommPortFlagsT portType,
    CL_OUT ClIocCommPortHandleT * pIocCommPortHdl
    );




    ClRcT clIocCommPortDelete(
    CL_IN ClIocCommPortHandleT iocCommPortHdl
    );


    ClRcT clIocCommPortFdGet(
            CL_IN ClIocCommPortHandleT portHandle, 
            CL_INOUT ClInt32T *pSd
            );

    ClRcT clIocCommPortGet(
    CL_IN ClIocCommPortHandleT pIocCommPort,
    CL_OUT ClIocPortT * pPortId
    );


    ClRcT clIocPortNotification(
            CL_IN ClIocPortT port,
            CL_IN ClIocNotificationActionT action
            );


    ClRcT clIocSend(
    CL_IN ClIocCommPortHandleT commPortHandle,
    CL_IN ClBufferHandleT message,
    CL_IN ClUint8T protoType,
    CL_IN ClIocAddressT * pDestAddr,
    CL_IN ClIocSendOptionT * pSendOption
    );



    ClRcT clIocReceive(
    CL_IN ClIocCommPortHandleT commPortHdl,
    CL_IN ClIocRecvOptionT * pRecvOption,
    CL_OUT ClBufferHandleT userMsg,
    CL_OUT ClIocRecvParamT * pRecvParam
    );

    ClRcT clIocReceiveAsync(
    CL_IN ClIocCommPortHandleT commPortHdl,
    CL_IN ClIocRecvOptionT * pRecvOption,
    CL_OUT ClBufferHandleT userMsg,
    CL_OUT ClIocRecvParamT * pRecvParam
    );

    ClRcT clIocReceiveWithBuffer(
                                 CL_IN ClIocCommPortHandleT commPortHdl,
                                 CL_IN ClIocRecvOptionT * pRecvOption,
                                 CL_IN ClUint8T *buffer,
                                 CL_IN ClUint32T bufSize,
                                 CL_OUT ClBufferHandleT userMsg,
                                 CL_OUT ClIocRecvParamT * pRecvParam
                                 );

    ClRcT clIocReceiveWithBufferAsync(
                                      CL_IN ClIocCommPortHandleT commPortHdl,
                                      CL_IN ClIocRecvOptionT * pRecvOption,
                                      CL_IN ClUint8T *buffer,
                                      CL_IN ClUint32T bufSize,
                                      CL_OUT ClBufferHandleT userMsg,
                                      CL_OUT ClIocRecvParamT * pRecvParam
                                      );


    ClRcT clIocCommPortReceiverUnblock(
    CL_IN ClIocCommPortHandleT commPortHdl
    );




/*********************************************************************************/
/************************  Transparency Layer APIs  ******************************/
/*********************************************************************************/



    ClRcT clIocTransparencyRegister(
    CL_IN ClIocTLInfoT * pTLInfo
    );



    ClRcT clIocTransparencyDeregister(
    CL_IN ClUint32T compId
    );




    ClRcT clIocMulticastRegister(CL_IN ClIocMcastUserInfoT *pMcastInfo);

    ClRcT clIocMulticastDeregister(CL_IN ClIocMcastUserInfoT *pMcastInfo);

    ClRcT clIocMulticastDeregisterAll(CL_IN ClIocMulticastAddressT *pMcastAddress);




    ClIocNodeAddressT clIocLocalAddressGet(
    void
    );




    ClRcT clIocVersionCheck(
    CL_IN ClVersionT * pVersion
    );


#if 0

    ClRcT clIocTransparencyDeregisterNode(
    CL_IN ClIocNodeAddressT nodeId
    ) CL_DEPRECATED;

#endif

    ClRcT clIocTransparencyLogicalToPhysicalAddrGet(
    CL_IN ClIocLogicalAddressT logicalAddr,
    CL_OUT ClIocTLMappingT ** pPhysicalAddr,
    CL_OUT ClUint32T * pNoEntries
    ) CL_DEPRECATED;


# ifdef __cplusplus
}
# endif
#endif                          /* _CL_IOC_API_H_ */