vipl.h

Go to the documentation of this file.

/********************************************************
 * Myricom VI-GM  networking software and documentation *
 * Copyright (c) 2001 by Myricom, Inc.                  *
 * All rights reserved.                                 *
 * See the file `COPYING' for copyright notice.         *
 ********************************************************/

#ifndef __VIPL
#define __VIPL

#include "gm.h"


/********************************************************
 *                                                      *
 *                    VIPL Constants                    *
 *                                                      *
 ********************************************************/

#define IN

#define OUT

#define VIP_FALSE (0)

#define VIP_TRUE (1)

#define VIP_INFINITE (~(VIP_ULONG) 0)

#define VIP_SMI_AUTODISCOVERY ((VIP_ULONG) 1)

#define VIP_DESCRIPTOR_ALIGNMENT 64


/* Reliability level values */
#define VIP_SERVICE_UNRELIABLE          0x01

#define VIP_SERVICE_RELIABLE_DELIVERY   0x02

#define VIP_SERVICE_RELIABLE_RECEPTION  0x04


/* Descriptor Control field */
#define VIP_CONTROL_OP_SENDRECV         0x0000

#define VIP_CONTROL_OP_RDMAWRITE        0x0001

#define VIP_CONTROL_OP_RDMAREAD         0x0002

#define VIP_CONTROL_OP_RESERVED         0x0003

#define VIP_CONTROL_OP_MASK             0x0003

#define VIP_CONTROL_IMMEDIATE           0x0004

#define VIP_CONTROL_QFENCE              0x0008

#define VIP_CONTROL_RESERVED            0xFFF0


/* Descriptor Status field */
#define VIP_STATUS_DONE                 0x00000001

#define VIP_STATUS_FORMAT_ERROR         0x00000002

#define VIP_STATUS_PROTECTION_ERROR     0x00000004

#define VIP_STATUS_LENGTH_ERROR         0x00000008

#define VIP_STATUS_PARTIAL_ERROR        0x00000010

#define VIP_STATUS_DESC_FLUSHED_ERROR   0x00000020

#define VIP_STATUS_TRANSPORT_ERROR      0x00000040

#define VIP_STATUS_RDMA_PROT_ERROR      0x00000080

#define VIP_STATUS_REMOTE_DESC_ERROR    0x00000100

#define VIP_STATUS_ERROR_MASK           0x000001FE

#define VIP_STATUS_OP_SEND              0x00000000

#define VIP_STATUS_OP_RECEIVE           0x00010000

#define VIP_STATUS_OP_RDMA_WRITE        0x00020000

#define VIP_STATUS_OP_REMOTE_RDMA_WRITE 0x00030000

#define VIP_STATUS_OP_RDMA_READ         0x00040000

#define VIP_STATUS_OP_MASK              0x00070000

#define VIP_STATUS_IMMEDIATE            0x00080000

#define VIP_STATUS_RESERVED             0xFFF0FE00



/********************************************************
 *                                                      *
 *                    VIPL Data Types                   *
 *                                                      *
 ********************************************************/


/* Generic types for portability */
typedef void *VIP_PVOID;
typedef int VIP_BOOLEAN;
typedef char VIP_CHAR;
typedef unsigned char VIP_UCHAR;
typedef unsigned short VIP_USHORT;
typedef unsigned long VIP_ULONG;

/* GM specific types */
typedef gm_u8_t VIP_UINT8;
typedef gm_u16_t VIP_UINT16;
typedef gm_u32_t VIP_UINT32;
typedef gm_u64_t VIP_UINT64;


/* Handles for opaque objects */
typedef VIP_PVOID VIP_NIC_HANDLE;
typedef VIP_PVOID VIP_VI_HANDLE;
typedef VIP_PVOID VIP_PROTECTION_HANDLE;
typedef VIP_PVOID VIP_CONN_HANDLE;
typedef VIP_PVOID VIP_CQ_HANDLE;


/* Misc */
typedef VIP_UINT32 VIP_MEM_HANDLE;
typedef VIP_PVOID VIP_QOS;


typedef struct VIP_NET_ADDRESS
{
  VIP_UINT16 HostAddressLen;
  VIP_UINT16 DiscriminatorLen;
  VIP_UINT8 HostAddress[1];
}
VIP_NET_ADDRESS;


typedef VIP_USHORT VIP_RELIABILITY_LEVEL;

typedef struct VIP_NIC_ATTRIBUTES
{
  VIP_CHAR Name[64];
  VIP_ULONG HardwareVersion;
  VIP_ULONG ProviderVersion;
  VIP_UINT16 NicAddressLen;
  const VIP_UINT8 *LocalNicAddress;
  VIP_BOOLEAN ThreadSafe;
  VIP_UINT16 MaxDiscriminatorLen;
  VIP_ULONG MaxRegisterBytes;
  VIP_ULONG MaxRegisterRegions;
  VIP_ULONG MaxRegisterBlockBytes;
  VIP_ULONG MaxVI;
  VIP_ULONG MaxDescriptorsPerQueue;
  VIP_ULONG MaxSegmentsPerDesc;
  VIP_ULONG MaxCQ;
  VIP_ULONG MaxCQEntries;
  VIP_ULONG MaxTransferSize;
  VIP_ULONG NativeMTU;
  VIP_ULONG MaxPtags;
  VIP_RELIABILITY_LEVEL ReliabilityLevelSupport;
  VIP_RELIABILITY_LEVEL RDMAReadSupport;
}
VIP_NIC_ATTRIBUTES;


typedef union VIP_PVOID64
{
  VIP_UINT64 AddressBits;
  VIP_PVOID Address;
}
VIP_PVOID64;


typedef struct VIP_CONTROL_SEGMENT
{
  VIP_PVOID64 Next;
  VIP_MEM_HANDLE NextHandle;
  VIP_UINT16 SegCount;
  VIP_UINT16 Control;
  VIP_UINT32 Reserved;
  VIP_UINT32 ImmediateData;
  VIP_UINT32 Length;
  VIP_UINT32 Status;
}
VIP_CONTROL_SEGMENT;


typedef struct VIP_ADDRESS_SEGMENT
{
  VIP_PVOID64 Data;
  VIP_MEM_HANDLE Handle;
  VIP_UINT32 Reserved;
}
VIP_ADDRESS_SEGMENT;


typedef struct VIP_DATA_SEGMENT
{
  VIP_PVOID64 Data;
  VIP_MEM_HANDLE Handle;
  VIP_UINT32 Length;
}
VIP_DATA_SEGMENT;


typedef union VIP_DESCRIPTOR_SEGMENT
{
  VIP_ADDRESS_SEGMENT Remote;
  VIP_DATA_SEGMENT Local;
}
VIP_DESCRIPTOR_SEGMENT;


typedef struct VIP_DESCRIPTOR
{
  VIP_CONTROL_SEGMENT CS;
  VIP_DESCRIPTOR_SEGMENT DS[2];
}
VIP_DESCRIPTOR;


typedef enum VIP_VI_STATE
{
  VIP_STATE_IDLE,
  VIP_STATE_CONNECTED,
  VIP_STATE_CONNECT_PENDING,
  VIP_STATE_ERROR
}
VIP_VI_STATE;


typedef struct VIP_VI_ATTRIBUTES
{
  VIP_RELIABILITY_LEVEL ReliabilityLevel;
  VIP_ULONG MaxTransferSize;
  VIP_QOS QoS;
  VIP_PROTECTION_HANDLE Ptag;
  VIP_BOOLEAN EnableRdmaWrite;
  VIP_BOOLEAN EnableRdmaRead;
}
VIP_VI_ATTRIBUTES;


typedef struct VIP_MEM_ATTRIBUTES
{
  VIP_PROTECTION_HANDLE Ptag;
  VIP_BOOLEAN EnableRdmaWrite;
  VIP_BOOLEAN EnableRdmaRead;
}
VIP_MEM_ATTRIBUTES;


typedef struct
{
  VIP_ULONG NumberOfHops;
  VIP_NET_ADDRESS **ADAddrArray;
  VIP_ULONG NumAdAddrs;
}
VIP_AUTODISCOVERY_LIST;


typedef enum VIP_ERROR_CODE
{
  VIP_ERROR_POST_DESC,
  VIP_ERROR_CONN_LOST,
  VIP_ERROR_RECVQ_EMPTY,
  VIP_ERROR_VI_OVERRUN,
  VIP_ERROR_RDMAW_PROT,
  VIP_ERROR_RDMAW_DATA,
  VIP_ERROR_RDMAW_ABORT,
  VIP_ERROR_RDMAR_PROT,
  VIP_ERROR_COMP_PROT,
  VIP_ERROR_RDMA_TRANSPORT,
  VIP_ERROR_CATASTROPHIC
}
VIP_ERROR_CODE;


typedef enum VIP_RESOURCE_CODE
{
  VIP_RESOURCE_NIC,
  VIP_RESOURCE_VI,
  VIP_RESOURCE_CQ,
  VIP_RESOURCE_DESCRIPTOR
}
VIP_RESOURCE_CODE;


typedef struct VIP_ERROR_DESCRIPTOR
{
  VIP_NIC_HANDLE NicHandle;
  VIP_VI_HANDLE ViHandle;
  VIP_CQ_HANDLE CQHandle;
  VIP_DESCRIPTOR *DescriptorPtr;
  VIP_ULONG OpCode;
  VIP_RESOURCE_CODE ResourceCode;
  VIP_ERROR_CODE ErrorCode;
}
VIP_ERROR_DESCRIPTOR;


/* Functions return codes */
enum VIP_RETURN
{
  VIP_SUCCESS,
  VIP_NOT_DONE,
  VIP_INVALID_PARAMETER,
  VIP_ERROR_RESOURCE,
  VIP_TIMEOUT,
  VIP_REJECT,
  VIP_INVALID_RELIABILITY_LEVEL,
  VIP_INVALID_MTU,
  VIP_INVALID_QOS,
  VIP_INVALID_PTAG,
  VIP_INVALID_RDMAREAD,
  VIP_DESCRIPTOR_ERROR,
  VIP_INVALID_STATE,
  VIP_ERROR_NAMESERVICE,
  VIP_NO_MATCH,
  VIP_NOT_REACHABLE
};

typedef enum VIP_RETURN VIP_RETURN;


/********************************************************
 *                                                      *
 *                    VIPL prototypes                   *
 *                                                      *
 ********************************************************/

#ifndef WIN32

#  define VIP_ENTRY_POINT
#else
#  ifdef VIP_BUILD_DLL

#    define VIP_ENTRY_POINT __declspec (dllexport)
#  else

#    define VIP_ENTRY_POINT __declspec (dllimport)
#  endif
#endif

VIP_ENTRY_POINT extern VIP_RETURN
VipOpenNic (IN const VIP_CHAR * DeviceName, 
            OUT VIP_NIC_HANDLE * NicHandle);

VIP_ENTRY_POINT extern VIP_RETURN 
VipCloseNic (IN VIP_NIC_HANDLE NicHandle);

VIP_ENTRY_POINT extern VIP_RETURN
VipCreateVi (IN VIP_NIC_HANDLE NicHandle,
             IN VIP_VI_ATTRIBUTES * ViAttribs,
             IN VIP_CQ_HANDLE SendCQHandle,
             IN VIP_CQ_HANDLE RecvCQHandle, 
             OUT VIP_VI_HANDLE * ViHandle);

VIP_ENTRY_POINT extern VIP_RETURN
VipDestroyVi (IN VIP_VI_HANDLE ViHandle);

VIP_ENTRY_POINT extern VIP_RETURN
VipConnectWait (IN VIP_NIC_HANDLE NicHandle,
                IN VIP_NET_ADDRESS * LocalAddr,
                IN VIP_ULONG Timeout,
                OUT VIP_NET_ADDRESS * RemoteAddr,
                OUT VIP_VI_ATTRIBUTES * RemoteViAttribs,
                OUT VIP_CONN_HANDLE * ConnHandle);

VIP_ENTRY_POINT extern VIP_RETURN
VipConnectAccept (IN VIP_CONN_HANDLE ConnHandle, 
                  IN VIP_VI_HANDLE ViHandle);

VIP_ENTRY_POINT extern VIP_RETURN 
VipConnectReject (IN VIP_CONN_HANDLE ConnHandle);

VIP_ENTRY_POINT extern VIP_RETURN
VipConnectRequest (IN VIP_VI_HANDLE ViHandle,
                   IN VIP_NET_ADDRESS * LocalAddr,
                   IN VIP_NET_ADDRESS * RemoteAddr,
                   IN VIP_ULONG Timeout,
                   OUT VIP_VI_ATTRIBUTES * RemoteViAttribs);

VIP_ENTRY_POINT extern VIP_RETURN 
VipDisconnect (IN VIP_VI_HANDLE ViHandle);

VIP_ENTRY_POINT extern VIP_RETURN
VipCreatePtag (IN VIP_NIC_HANDLE NicHandle, 
               OUT VIP_PROTECTION_HANDLE * Ptag);

VIP_ENTRY_POINT extern VIP_RETURN
VipDestroyPtag (IN VIP_NIC_HANDLE NicHandle, 
                IN VIP_PROTECTION_HANDLE Ptag);

VIP_ENTRY_POINT extern VIP_RETURN
VipRegisterMem (IN VIP_NIC_HANDLE NicHandle,
                IN VIP_PVOID VirtualAddress,
                IN VIP_ULONG Length,
                IN VIP_MEM_ATTRIBUTES * MemAttribs,
                OUT VIP_MEM_HANDLE * MemoryHandle);

VIP_ENTRY_POINT extern VIP_RETURN
VipDeregisterMem (IN VIP_NIC_HANDLE NicHandle,
                  IN VIP_PVOID VirtualAddress,
                  IN VIP_MEM_HANDLE MemoryHandle);

VIP_ENTRY_POINT extern VIP_RETURN
VipPostSend (IN VIP_VI_HANDLE ViHandle,
             IN VIP_DESCRIPTOR * DescriptorPtr,
             IN VIP_MEM_HANDLE MemoryHandle);

VIP_ENTRY_POINT extern VIP_RETURN
VipSendDone (IN VIP_VI_HANDLE ViHandle, 
             OUT VIP_DESCRIPTOR ** DescriptorPtr);

VIP_ENTRY_POINT extern VIP_RETURN
VipSendWait (IN VIP_VI_HANDLE ViHandle,
             IN VIP_ULONG Timeout, 
             OUT VIP_DESCRIPTOR ** DescriptorPtr);

VIP_ENTRY_POINT extern VIP_RETURN
VipPostRecv (IN VIP_VI_HANDLE ViHandle,
             IN VIP_DESCRIPTOR * DescriptorPtr,
             IN VIP_MEM_HANDLE MemoryHandle);

VIP_ENTRY_POINT extern VIP_RETURN
VipRecvDone (IN VIP_VI_HANDLE ViHandle, 
             OUT VIP_DESCRIPTOR ** DescriptorPtr);

VIP_ENTRY_POINT extern VIP_RETURN
VipRecvWait (IN VIP_VI_HANDLE ViHandle,
             IN VIP_ULONG Timeout, 
             OUT VIP_DESCRIPTOR ** DescriptorPtr);

VIP_ENTRY_POINT extern VIP_RETURN
VipCQDone (IN VIP_CQ_HANDLE CQHandle,
           OUT VIP_VI_HANDLE * ViHandle, 
           OUT VIP_BOOLEAN * RecvQueue);

VIP_ENTRY_POINT extern VIP_RETURN
VipCQWait (IN VIP_CQ_HANDLE CQHandle,
           IN VIP_ULONG Timeout,
           OUT VIP_VI_HANDLE * ViHandle, 
           OUT VIP_BOOLEAN * RecvQueue);

VIP_ENTRY_POINT extern VIP_RETURN
VipSendNotify (IN VIP_VI_HANDLE ViHandle,
               IN VIP_PVOID Context,
               IN void (*Handler) (IN VIP_PVOID Context,
                                   IN VIP_NIC_HANDLE NicHandle,
                                   IN VIP_VI_HANDLE ViHandle,
                                   IN VIP_DESCRIPTOR * DescriptorPtr));

VIP_ENTRY_POINT extern VIP_RETURN
VipRecvNotify (IN VIP_VI_HANDLE ViHandle,
               IN VIP_PVOID Context,
               IN void (*Handler) (IN VIP_PVOID Context,
                                   IN VIP_NIC_HANDLE NicHandle,
                                   IN VIP_VI_HANDLE ViHandle,
                                   IN VIP_DESCRIPTOR * DescriptorPtr));

VIP_ENTRY_POINT extern VIP_RETURN
VipCQNotify (IN VIP_CQ_HANDLE CQHandle,
             IN VIP_PVOID Context,
             IN void (*Handler) (IN VIP_PVOID Context,
                                 IN VIP_NIC_HANDLE NicHandle,
                                 IN VIP_VI_HANDLE ViHandle,
                                 IN VIP_BOOLEAN RecvQueue));

VIP_ENTRY_POINT extern VIP_RETURN
VipCreateCQ (IN VIP_NIC_HANDLE NicHandle,
             IN VIP_ULONG EntryCount, OUT VIP_CQ_HANDLE * CQHandle);

VIP_ENTRY_POINT extern VIP_RETURN
VipDestroyCQ (IN VIP_CQ_HANDLE CQHandle);

VIP_ENTRY_POINT extern VIP_RETURN
VipResizeCQ (IN VIP_CQ_HANDLE CQHandle, IN VIP_ULONG EntryCount);

VIP_ENTRY_POINT extern VIP_RETURN
VipQueryNic (IN VIP_NIC_HANDLE NicHandle,
             OUT VIP_NIC_ATTRIBUTES * NicAttribs);

VIP_ENTRY_POINT extern VIP_RETURN
VipSetViAttributes (IN VIP_VI_HANDLE ViHandle,
                    IN VIP_VI_ATTRIBUTES * ViAttribs);

VIP_ENTRY_POINT extern VIP_RETURN
VipQueryVi (IN VIP_VI_HANDLE ViHandle,
            OUT VIP_VI_STATE * State,
            OUT VIP_VI_ATTRIBUTES * ViAttribs,
            OUT VIP_BOOLEAN * ViSendQEmpty, 
            OUT VIP_BOOLEAN * ViRecvQEmpty);

VIP_ENTRY_POINT extern VIP_RETURN
VipSetMemAttributes (IN VIP_NIC_HANDLE NicHandle,
                     IN VIP_PVOID Address,
                     IN VIP_MEM_HANDLE MemHandle,
                     IN VIP_MEM_ATTRIBUTES * MemAttribs);

VIP_ENTRY_POINT extern VIP_RETURN
VipQueryMem (IN VIP_NIC_HANDLE NicHandle,
             IN VIP_PVOID Address,
             IN VIP_MEM_HANDLE MemHandle,
             OUT VIP_MEM_ATTRIBUTES * MemAttribs);

VIP_ENTRY_POINT extern VIP_RETURN 
VipQuerySystemManagementInfo (IN VIP_NIC_HANDLE NicHandle,
                              IN VIP_ULONG InfoType,
                              OUT VIP_PVOID SysManInfo);

VIP_ENTRY_POINT extern VIP_RETURN
VipErrorCallback (IN VIP_NIC_HANDLE NicHandle,
                  IN VIP_PVOID Context,
                  IN void (*Handler) (IN VIP_PVOID Context,
                                      IN VIP_ERROR_DESCRIPTOR * ErrorDesc));


/**********************************************************************
 * Peer-to-Peer Connection Model APIs
 *********************************************************************/

VIP_ENTRY_POINT extern VIP_RETURN
VipConnectPeerRequest (IN VIP_VI_HANDLE ViHandle,
                       IN VIP_NET_ADDRESS * LocalAddr,
                       IN VIP_NET_ADDRESS * RemoteAddr, 
                       IN VIP_ULONG Timeout);

VIP_ENTRY_POINT extern VIP_RETURN
VipConnectPeerDone (IN VIP_VI_HANDLE ViHandle,
                    OUT VIP_VI_ATTRIBUTES * RemoteViAttribs);

VIP_ENTRY_POINT extern VIP_RETURN
VipConnectPeerWait (IN VIP_VI_HANDLE ViHandle,
                    OUT VIP_VI_ATTRIBUTES * RemoteViAttribs);


/**********************************************************************
 * Name service APIs
 *********************************************************************/

VIP_ENTRY_POINT extern VIP_RETURN
VipNSInit (IN VIP_NIC_HANDLE NicHandle, 
           IN VIP_PVOID NSInitInfo);

VIP_ENTRY_POINT extern VIP_RETURN
VipNSGetHostByName (IN VIP_NIC_HANDLE NicHandle,
                    IN VIP_CHAR * Name,
                    OUT VIP_NET_ADDRESS * Address, 
                    IN VIP_ULONG NameIndex);

VIP_ENTRY_POINT extern VIP_RETURN
VipNSGetHostByAddr (IN VIP_NIC_HANDLE NicHandle,
                    IN VIP_NET_ADDRESS * Address,
                    OUT VIP_CHAR * Name, 
                    IN OUT VIP_ULONG * NameLen);

VIP_ENTRY_POINT extern VIP_RETURN 
VipNSShutdown (IN VIP_NIC_HANDLE NicHandle);


#endif