[Openib-windows] [RFC] Kernel Async Verbs
Fab Tillier
ftillier at silverstorm.com
Fri Sep 16 14:44:08 PDT 2005
Folks,
Just an update on the work going to define a verb interface that supports client
calls at DISPATCH_LEVEL.
Following Tzachi's request, this interface is defined as a direct call interface
for use by kernel clients. User-mode IOCTLs would be translated by the kernel
proxy into these calls, leaving the complexity of IOCTL handling to the kernel
proxy. This interface is retrieved by the standard IRP_MN_QUERY_INTEFACE
mechanism.
I've converted tabs to spaces for the code below just for readability's sake in
the email. Attached are the source files that have the tabs preserved.
I only have CA, PD, CQ, and QP operations defined for now but will continue to
work on defining the rest.
Please let me know if you have any comments or issues with the design.
I'd like opinions on whether the dispatch structure concept seems OK or not,
versus passing in callbacks individually. I modeled the dispatch table after
the WSK API, but I don't know if it makes that much sense for what we're doing
here since a good number of the dispatch structures only have a single field.
Only the CA and CQ objects have a dispatch table with two handlers.
Thanks,
- Fab
Index: inc/iba/ibdef.h
===================================================================
/*
* Copyright (c) 2005 SilverStorm Technologies. All rights reserved.
*
* This software is available to you under the OpenIB.org BSD license
* below:
*
* Redistribution and use in source and binary forms, with or
* without modification, are permitted provided that the following
* conditions are met:
*
* - Redistributions of source code must retain the above
* copyright notice, this list of conditions and the following
* disclaimer.
*
* - Redistributions in binary form must reproduce the above
* copyright notice, this list of conditions and the following
* disclaimer in the documentation and/or other materials
* provided with the distribution.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*
* $Id$
*/
#pragma once
#ifndef _IBDEFS_
#define _IBDEFS_
typedef struct _IB_CA *IB_CA_HANDLE, * __ptr64 IB_CA_HANDLE64;
typedef struct _IB_PD *IB_PD_HANDLE, * __ptr64 IB_PD_HANDLE64;
typedef struct _IB_CQ *IB_CQ_HANDLE, * __ptr64 IB_CQ_HANDLE64;
typedef struct _IB_QP *IB_QP_HANDLE, * __ptr64 IB_QP_HANDLE64;
typedef struct _IB_AH *IB_ADDR_HANDLE, * __ptr64 IB_ADDR_HANDLE64;
typedef struct _IB_MR *IB_MR_HANDLE, * __ptr64 IB_MR_HANDLE64;
typedef struct _IB_MW *IB_MW_HANDLE, * __ptr64 IB_MW_HANDLE64;
#pragma pack(push, 1)
typedef union _IB_GID
{
UCHAR Raw[16];
struct _IB_GID_UNICAST
{
UINT64 Prefix;
UINT64 InterfaceId;
} Unicast;
struct _IB_GID_MULTICAST
{
UCHAR Header[2];
UCHAR RawGroupId[14];
} Multicast;
} IB_GID;
#pragma pack(pop)
typedef enum _IB_MTU
{
IB_MTU_256 = 1,
IB_MTU_512 = 2,
IB_MTU_1024 = 3,
IB_MTU_2048 = 4,
IB_MTU_4096 = 5
} IB_MTU;
typedef enum _IB_LINK_STATE
{
IB_LINK_NO_CHANGE = 0,
IB_LINK_DOWN = 1,
IB_LINK_INIT = 2,
IB_LINK_ARMED = 3,
IB_LINK_ACTIVE = 4,
IB_LINK_ACT_DEFER = 5
} IB_LINK_STATE;
typedef enum _IB_LINK_WIDTH
{
IB_LINK_WIDTH_1X = 1,
IB_LINK_WIDTH_4X = 2,
IB_LINK_WIDTH_8X = 4,
IB_LINK_WIDTH_12X = 8
} IB_LINK_WIDTH;
typedef enum _IB_LINK_SPEED
{
IB_LINK_SPEED_2_5_GBS = 1,
IB_LINK_SPEED_5_GBS = 2,
IB_LINK_SPEED_10_GBS = 4
} IB_LINK_SPEED;
enum IB_PORT_CAP_FLAGS
{
IB_PORT_CAP_IS_SM = (1<<1),
IB_PORT_CAP_NOTICE_SUP = (1<<2),
IB_PORT_CAP_TRAP_SUP = (1<<3),
IB_PORT_CAP_OPT_IPD_SUP = (1<<4),
IB_PORT_CAP_APM_SUP = (1<<5),
IB_PORT_CAP_SL_MAP_SUP = (1<<6),
IB_PORT_CAP_MKEY_NVRAM = (1<<7),
IB_PORT_CAP_PKEY_NVRAM = (1<<8),
IB_PORT_CAP_LED_INFO_SUP = (1<<9),
IB_PORT_CAP_IS_SM_DISABLED = (1<<10),
IB_PORT_CAP_SYS_IMAGE_GUID_SUP = (1<<11),
IB_PORT_CAP_PKEY_SW_EXT_PORT_TRAP_SUP = (1<<12),
IB_PORT_CAP_CM_SUP = (1<<16),
IB_PORT_CAP_SNMP_TUNNEL_SUP = (1<<17),
IB_PORT_CAP_REINIT_SUP = (1<<18),
IB_PORT_CAP_DEVICE_MGMT_SUP = (1<<19),
IB_PORT_CAP_VENDOR_CLASS_SUP = (1<<20),
IB_PORT_CAP_DR_NOTICE_SUP = (1<<21),
IB_PORT_CAP_CAP_MASK_NOTICE_SUP = (1<<22),
IB_PORT_CAP_BOOT_MGMT_SUP = (1<<23),
IB_PORT_CAP_LINK_LATENCY_SUP = (1<<24),
IB_PORT_CAP_CLIENT_REG_SUP = (1<<25)
};
enum _IB_INIT_TYPE
{
IB_INIT_TYPE_NO_LOAD = 1,
IB_INIT_TYPE_PRESERVE_CONTENT = (1<<1),
IB_INIT_TYPE_PRESERVE_PRESENCE = (1<<2),
IB_INIT_TYPE_DO_NOT_RESUSCITATE = (1<<3)
};
typedef __declspec(align(8)) struct _IB_PORT_ATTR
{
ULONG Size;
/** Combination of IB_PORT_CAP_FLAGS values. */
ULONG CapabilitiesFlags;
/** GUID are in network byte order. */
UINT64 PortGuid;
IB_LINK_STATE LinkState;
IB_LINK_WIDTH LinkWidth;
IB_LINK_SPEED LinkSpeed;
IB_MTU Mtu;
UINT64 MaxMsgSize;
USHORT NumGids;
USHORT NumPkeys;
/** Offsets are from beginning of structure. */
ULONG NextPortAttrOffset;
ULONG GidTblOffset;
ULONG PkeyTblOffset;
USHORT PkeyViolations;
USHORT QkeyViolations;
USHORT BaseLid;
USHORT SmLid;
USHORT MaxVls;
UCHAR Lmc;
UCHAR PortNum;
UCHAR InitTypeReply;
/** The maximum expected subnet propagation delay to reach any port on
* the subnet. This value also determines the rate at which traps can
* be generated from this node. The value is expressed as
* timeout = 4.096 microseconds * 2^subnet_timeout
*/
UCHAR SubnetTimeout;
UCHAR SmSvcLvl;
} IB_PORT_ATTR;
enum IB_MODIFY_PORT_FLAGS
{
IB_MOD_PORT_SHUTDOWN = (1<<0),
IB_MOD_PORT_INIT_REPLY = (1<<1),
IB_MOD_PORT_RESET_QKEY_VIOLATIONS = (1<<2)
};
typedef struct _IB_MODIFY_PORT
{
/** Combination of IB_PORT_CAP_FLAGS */
ULONG SetCapabilites;
ULONG ClearCapabilites;
UCHAR InitTypeReply;
} IB_MODIFY_PORT;
enum IB_CA_CAP_FLAGS
{
IB_CA_CAP_RESIZE_MAX_WR = (1<<0),
IB_CA_CAP_BAD_PKEY_CNTR = (1<<1),
IB_CA_CAP_BAD_QKEY_CNTR = (1<<2),
IB_CA_CAP_AUTO_PATH_MIG = (1<<3),
IB_CA_CAP_CHANGE_PHY_PORT = (1<<4),
IB_CA_CAP_AH_PORT_ENFORCE = (1<<5),
IB_CA_CAP_CURR_QP_STATE_MOD = (1<<6),
IB_CA_CAP_SHUTDOWN_PORT = (1<<7),
IB_CA_CAP_INIT_TYPE = (1<<8),
IB_CA_CAP_PORT_ACTIVE_EVENT = (1<<9),
IB_CA_CAP_SYS_IMAGE_GUID = (1<<10),
IB_CA_CAP_RC_RNR_NAK_GEN = (1<<11),
IB_CA_CAP_N_NOTIFY_CQ = (1<<12),
IB_CA_CAP_SRQ_RESIZE = (1<<13)
};
typedef enum _IB_ATOMIC_CAP
{
IB_ATOMIC_NONE,
IB_ATOMIC_LOCAL,
IB_ATOMIC_GLOBAL
} IB_ATOMIC_CAP;
typedef __declspec(align(8)) struct _IB_CA_ATTR
{
ULONG Size;
UINT32 VendorId;
UINT16 DeviceId;
UINT16 DeviceRev;
UINT32 FwVersion;
/** GUIDs are in network byte order. */
UINT64 CaGuid;
UINT64 SystemImageGuid;
/** Byte offset from the beginning of this structure to the first
* IB_PORT_ATTR structure for the HCA.
*/
ULONG PortAttrOffset;
UINT8 NumPorts;
UINT8 MaxQpReadAtomic;
UINT8 MaxReadAtomic;
UINT8 MaxQpInitReadAtomic;
/** Each bit in PageSizeSupport indicates a 2^n page size supported
* by the HCA, where bit locations are 1-based. The minimum page
* size that can be supported is thus 2 bytes, and the largest 2^64.
*/
UINT64 PageSizeSupport;
/** Combination of IB_CA_CAP_FLAGS values. */
ULONG CapabilitiesFlags;
IB_ATOMIC_CAP AtomicCap;
ULONG MaxQp;
ULONG MaxQpWr;
ULONG MaxQpSge;
ULONG MaxCq;
ULONG MaxCqe;
ULONG MaxPd;
ULONG MaxAh;
ULONG MaxMr;
UINT64 MaxMrSize;
ULONG MaxMw;
ULONG MaxMcastGrp;
ULONG MaxMcastQp;
ULONG MaxMcastQpPerGrp;
ULONG MaxSrq;
ULONG MaxSrqWr;
ULONG MaxSrqSge;
UINT16 MaxPKeys;
UINT8 LocalAckDelay;
} IB_CA_ATTR;
enum IB_MODIFY_CA_FLAGS
{
IB_MODIFY_CA_SYS_IMAGE_GUID = (1<<0)
};
typedef struct _IB_MODIFY_CA
{
UINT64 SystemImageGuid;
} IB_MODIFY_CA;
typedef enum _IB_WC_STATUS
{
IB_WCS_SUCCESS,
IB_WCS_LOCAL_LEN_ERR,
IB_WCS_LOCAL_OP_ERR,
IB_WCS_LOCAL_PROTECTION_ERR,
IB_WCS_WR_FLUSHED_ERR,
IB_WCS_MW_BIND_ERR,
IB_WCS_REM_ACCESS_ERR,
IB_WCS_REM_OP_ERR,
IB_WCS_RNR_RETRY_ERR,
IB_WCS_TIMEOUT_RETRY_ERR,
IB_WCS_REM_INVALID_REQ_ERR,
IB_WCS_UNMATCHED_RESPONSE, /* InfiniBand Access Layer */
IB_WCS_CANCELED, /* InfiniBand Access Layer */
IB_WCS_UNKNOWN /* Must be last. */
} IB_WC_STATUS;
typedef enum _IB_WC_TYPE
{
IB_WC_SEND,
IB_WC_RDMA_WRITE,
IB_WC_RECV,
IB_WC_RDMA_READ,
IB_WC_MW_BIND,
IB_WC_FETCH_ADD,
IB_WC_COMPARE_SWAP,
IB_WC_RECV_RDMA_WRITE,
IB_WC_UNKNOWN
} IB_WC_TYPE;
enum _IB_WC_FLAGS
{
IB_WC_FLAG_IMMEDIATE = (1<<0),
IB_WC_FLAG_GRH = (1<<1),
/** Upper bits of WC flags are for vendor specific use. */
IB_WC_FLAG_VENDOR_MASK = 0xFFFF0000
}
typedef __declspec(align(8)) struct _IB_WC
{
IB_QP_HANDLE64 hQp;
UINT64 WrId;
IB_WC_STATUS Status;
IB_WC_TYPE Type;
ULONG VendorError;
ULONG Length;
/** OR'd IB_WC_FLAGS values. */
ULONG Flags;
ULONG ImmediateData;
struct _WC_UD
{
ULONG RemoteQp;
USHORT RemoteLid;
USHORT PkeyIndex;
UCHAR RemoteSl;
UCHAR PathBits;
} Ud;
} IB_WC;
Index: inc/iba/ibstatus.h
===================================================================
/*
* Copyright (c) 2005 SilverStorm Technologies. All rights reserved.
*
* This software is available to you under the OpenIB.org BSD license
* below:
*
* Redistribution and use in source and binary forms, with or
* without modification, are permitted provided that the following
* conditions are met:
*
* - Redistributions of source code must retain the above
* copyright notice, this list of conditions and the following
* disclaimer.
*
* - Redistributions in binary form must reproduce the above
* copyright notice, this list of conditions and the following
* disclaimer in the documentation and/or other materials
* provided with the distribution.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*
* $Id$
*/
#pragma once
#ifndef _IBSTATUS_
#define _IBSTATUS_
/* Defines IB-specific error values. */
/* Matches FILE_DEVICE_INFINIBAND */
#define FACILITY_INFINIBAND 0x3B
#define STATUS_INSUFFICIENT_WR ((NTSTATUS)0xE03B0001L)
#define STATUS_INSUFFICIENT_SGE ((NTSTATUS)0xE03B0002L)
#define STATUS_INVALID_WR_TYPE ((NTSTATUS)0xE03B0003L)
#define STATUS_INVALID_STATE ((NTSTATUS)0xE03B0004L)
#endif /* _IBSTATUS_ */
Index: inc/kernel/ibverbs.h
===================================================================
/*
* Copyright (c) 2005 SilverStorm Technologies. All rights reserved.
*
* This software is available to you under the OpenIB.org BSD license
* below:
*
* Redistribution and use in source and binary forms, with or
* without modification, are permitted provided that the following
* conditions are met:
*
* - Redistributions of source code must retain the above
* copyright notice, this list of conditions and the following
* disclaimer.
*
* - Redistributions in binary form must reproduce the above
* copyright notice, this list of conditions and the following
* disclaimer in the documentation and/or other materials
* provided with the distribution.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*
* $Id$
*/
#pragma once
#ifndef _IBVERBS_
#define _IBVERBS_
#include <ntddk.h>
#include <iba/ib_defs.h>
#include <iba/ibstatus.h>
/****s* Verbs/CI_UDATA
* NAME
* CI_UDATA
*
* DESCRIPTION
* Vendor specific structure to facilitate user mode IO
*
* This structure is provided to assist the vendor specific user mode
* library to exchange information with its kernel mode driver. The
* user mode InfiniBand(tm) Verbs will call the vendor specific
* module before a call is made to the kernel mode driver. The kernel mode
* driver is expected to know the format and data in the input and output
* buffers, and copy any necessary data that must be handed to the user
* mode vendor library.
*
* PURPOSE
* pInputBuffer
* UVP input buffer. May overlap the output buffer.
*
* pOutputBuffer
* UVP output buffer. NULL if no output buffer is provided.
* May overlap the input buffer.
*
* InputSize
* Size of UVP provided buffer. Zero if there is no input buffer.
*
* OutputSize
* The size of the UVP provided output buffer. Zero if no output
* buffer is provided. The kernel mode driver sets this to the exact
* size that needs to be returned to its user mode counterpart.
*
* SOURCE
*/
typedef struct _CI_UDATA
{
const VOID* __ptr64 const pInputBuffer;
VOID* __ptr64 const pOutputBuffer;
SIZE_T InputSize;
SIZE_T OutputSize;
} CI_UDATA;
/******/
typedef struct _IB_CA_EVENT_DISPATCH
{
VOID IB_API (*FatalEvent)(
IN IB_CA* const pCa,
IN VOID *CaContext );
VOID IB_API (*PortEvent)(
IN IB_CA* const pCa,
IN VOID *CaContext,
IN const UCHAR PortNumber,
IN IB_ASYNC_EVENT Event );
} IB_CA_EVENT_DISPATCH;
typedef struct _IB_CA
{
const IB_CA_EVENT_DISPATCH* const Dispatch;
} IB_CA;
/****f* Verbs/CiOpenCa
* DESCRIPTION
* Opens the HCA for client use.
*
* SYNOPSIS
*/
typedef NTSTATUS
(*IbOpenCa)(
IN VOID* const IfcContext,
IN VOID* const Context,
IN const IB_CA_DISPATCH* const Dispatch OPTIONAL,
IN OUT CI_UDATA* const pUserData,
IN IRP* const pIrp );
/*
* PARAMETERS
* IfcContext
* [in] Interface context returned in INTERFACE structure retrieved
* using IRP_MN_QUERY_INTERFACE.
*
* Context
* [in] A pointer to a caller-supplied context for the CA instance
* being created. The HCA driver passes this value to the client's
* event callback functions. If the client will not be using event
* callbacks, this value is unused.
*
* Dispatch
* [in] A pointer to a constant client IB_CA_DISPATCH structure. This
* structure is a dispatch table that contains pointers to the event
* callback functions for the new CA instance. Any members of the
* table can be NULL.
*
* pUserData
* [in] Descriptor for any data exchanged with the user-mode verb
* provider. The input and output buffers are shadowed by the
* access layer in non-paged pool. The HCA driver can only access
* further embedded pointers from the context of this call.
*
* pIrp
* [in] IRP that will be completed when the request completes.
* The IRP major and minor functions as well as the I/O stack must
* be preserved when the IRP is completed. The Irp.RequestorMode
* can be used to distinguish kernel and user clients.
*
* RETURN VALUES
* STATUS_SUCCESS
* The operation completed successfully. The IoStatus.Information
* field of the IRP contains a pointer to a CA instance structure,
* IB_CA, for the new CA instance.
*
* STATUS_PENDING
* The operation could not be completed immediately. The HCA driver
* will complete the IRP when the operation completes, at which point
* the status of the operation will be returned in the IoStatus.Status
* field of the IRP.
*
* Other status codes
* An error occurred. The IRP will be completed with failure status.
*
* NOTES
* This function can be invoked at IRQL <= DISPATCH_LEVEL.
*
* The HCA driver must call IoCallDriver for the input IRP so that it
* can call I/O complete request. The target of IoCallDriver must be
* the FDO of the HCA since the IRP will have only a single I/O stack
* location for the HCA to use. This implies that the IRP cannot be
* passed down a chain of layered drivers.
*********/
/****f* Verbs/CiCloseCa
* DESCRIPTION
* Closes an open instance of an HCA.
*
* SYNOPSIS
*/
typedef NTSTATUS
(*IbCloseCa)(
IN IB_CA* const pCa,
IN OUT CI_UDATA* const pUserData,
IN IRP* const pIrp );
/*
* PARAMETERS
* pCa
* [in] Pointer to an IB_CA structure previously created by a call to
* CiOpenCa.
*
* pUserData
* [in] Descriptor for any data exchanged with the user-mode verb
* provider. The input and output buffers are shadowed by the
* access layer in non-paged pool. The HCA driver can only access
* further embedded pointers from the context of this call.
*
* pIrp
* [in] IRP that will be completed when the request completes.
* The IRP major and minor functions as well as the I/O stack must
* be preserved when the IRP is completed. The Irp.RequestorMode
* can be used to distinguish kernel and user clients.
*
* RETURN VALUES
* STATUS_SUCCESS
* The CA instance was closed successfully. The IRP will be completed
* with success status.
*
* STATUS_PENDING
* The operation could not be completed immediately. The HCA driver
* will complete the IRP when the operation completes, at which point
* the status of the operation will be returned in the IoStatus.Status
* field of the IRP.
*
* STATUS_DEVICE_BUSY
* The operation could not complete because the CA instance has
* outstanding resources allocated.
*
* Other status codes
* An error occurred. The IRP will be completed with failure status.
*
* NOTES
* This function can be invoked at IRQL <= DISPATCH_LEVEL.
*
* The HCA driver must call IoCallDriver for the input IRP so that it
* can call I/O complete request. The target of IoCallDriver must be
* the FDO of the HCA since the IRP will have only a single I/O stack
* location for the HCA to use. This implies that the IRP cannot be
* passed down a chain of layered drivers.
*
* Any pending event notification IRPs will be completed with
* STATUS_CANCELLED before the function returns.
*********/
/****f* Verbs/CiGetCaFatalEvent
* DESCRIPTION
* Queues a request for HCA catastrophic error notification.
*
* SYNOPSIS
*/
typedef NTSTATUS
(*IbGetCaFatalEvent)(
IN IB_CA* const pCa,
IN IRP* const pIrp );
/*
* PARAMETERS
* pCa
* [in] Pointer to an IB_CA structure previously created by a call to
* CiOpenCa.
*
* pIrp
* [in] IRP that will be completed when a local catastrophic error
* occurs on the HCA. The IRP major and minor functions as well as
* the I/O stack must be preserved when the IRP is completed. The
* Irp.RequestorMode can be used to distinguish kernel and user clients.
*
* RETURN VALUES
* STATUS_SUCCESS
* The CA instance experienced a fatal error and should be closed.
* The IRP will be completed with success status.
*
* STATUS_PENDING
* The operation could not be completed immediately. The HCA driver
* will complete the IRP when the operation completes, at which point
* the status of the operation will be returned in the IoStatus.Status
* field of the IRP.
*
* Other status codes
* An error occurred. The IRP will be completed with failure status.
*
* NOTES
* This function can be invoked at IRQL <= DISPATCH_LEVEL.
*
* The HCA driver must call IoCallDriver for the input IRP so that it
* can call I/O complete request. The target of IoCallDriver must be
* the FDO of the HCA since the IRP will have only a single I/O stack
* location for the HCA to use. This implies that the IRP cannot be
* passed down a chain of layered drivers.
*
* The HCA driver must set a cancel routine to allow clients to cancel
* the notification request.
*
* A client can queue up mutiple requests for notification. Only one
* request is completed per event. All such requests are completed with
* STATUS_CANCELLED if the IB_CA instance is closed.
*********/
/****f* Verbs/CiGetCaPortEvent
* DESCRIPTION
* Queues a requests for port event notification.
*
* SYNOPSIS
*/
typedef NTSTATUS
(*IbGetCaPortEvent)(
IN IB_CA* const pCa,
IN const UCHAR PortNumber,
IN IRP* const pIrp );
/*
* PARAMETERS
* pCa
* [in] Pointer to an IB_CA structure previously created by a call to
* CiOpenCa.
*
* PortNumber
* [in] Port number to which the notification request is targetted.
*
* pIrp
* [in] IRP that will be completed when the request completes.
* The IRP major and minor functions as well as the I/O stack must
* be preserved when the IRP is completed. The Irp.RequestorMode
* can be used to distinguish kernel and user clients.
*
* RETURN VALUES
* STATUS_SUCCESS
* The CA instance experienced a port event. The IoStatus.Information
* member of the IRP is updated with the IB_ASYNC_EVENT value. The IRP
* will be completed with success status.
*
* STATUS_PENDING
* The operation could not be completed immediately. The HCA driver
* will complete the IRP when the operation completes, at which point
* the status of the operation will be returned in the IoStatus.Status
* field of the IRP and the IB_ASYNC_EVENT will be returned in the
* IoStatus.Information field of the IRP.
*
* Other status codes
* An error occurred. The IRP will be completed with failure status.
*
* NOTES
* This function can be invoked at IRQL <= DISPATCH_LEVEL.
*
* The HCA driver must call IoCallDriver for the input IRP so that it
* can call I/O complete request. The target of IoCallDriver must be
* the FDO of the HCA since the IRP will have only a single I/O stack
* location for the HCA to use. This implies that the IRP cannot be
* passed down a chain of layered drivers.
*
* The HCA driver must set a cancel routine to allow clients to cancel
* the notification request.
*
* A client can queue up mutiple requests for notification. Only one
* request is completed per event. All such requests are completed with
* STATUS_CANCELLED if the IB_CA instance is closed.
*********/
/****f* Verbs/CiQueryCa
* DESCRIPTION
* Queries an HCA for its attributes.
*
* SYNOPSIS
*/
typedef NTSTATUS
(*IbQueryCa)(
IN IB_CA* const pCa,
IN const SIZE_T AttrSize,
OUT IB_CA_ATTR* const pAttr,
IN IRP* const pIrp );
/*
* PARAMETERS
* pCa
* [in] Pointer to an IB_CA structure previously created by a call to
* CiOpenCa.
*
* pAttrSize
* [in] Size of the attributes buffer referenced by the pAttr parameter.
*
* pAttr
* [out] CA attribute of this Host Channel adapter.
*
* pIrp
* [in] IRP that will be completed when the request completes.
* The IRP major and minor functions as well as the I/O stack must
* be preserved when the IRP is completed. The Irp.RequestorMode
* can be used to distinguish kernel and user clients.
*
* RETURN VALUES
* STATUS_SUCCESS
* The full CA attributes, including port attributes and their GID
* and PKEY tables, were successfully copied to the attribute buffer.
* The IoStatus.Information field of the IRP is updated to indicate
* the number of bytes returned.
*
* STATUS_PENDING
* The operation could not be completed immediately. The HCA driver
* will complete the IRP when the operation completes, at which point
* the status of the operation will be returned in the IoStatus.Status
* field and the number of bytes returned in the IoStatus.Information
* field of the IRP.
*
* STATUS_BUFFER_OVERFLOW
* The operation completed but returned only partial attributes. Full
* attributes were not returned due to insufficient space. The size
* required to get the full attributes is returned in the Size field
* of the IB_CA_ATTR structure. The IoStatus.Information field of the
* IRP is updated to indicate the number of bytes returned.
*
* STATUS_BUFFER_TOO_SMALL
* The pAttr buffer was too small to return any information. At a
* minimum, the buffer must be the 4 bytes to allow the required
* size to be returned.
*
* STATUS_FILE_FORCED_CLOSED
* The CA is no longer functional. The IRP will be completed with
* failure status. The client must release all resources and close
* the CA as soon as possible.
*
* Other status codes
* An error occurred. The IRP will be completed with failure status.
*
* NOTES
* This function can be invoked at IRQL <= DISPATCH_LEVEL.
*
* The HCA driver must call IoCallDriver for the input IRP so that it
* can call I/O complete request. The target of IoCallDriver must be
* the FDO of the HCA since the IRP will have only a single I/O stack
* location for the HCA to use. This implies that the IRP cannot be
* passed down a chain of layered drivers.
*********/
/****f* Verbs/CiQueryPort
* DESCRIPTION
* Queries an HCA for one of its port attributes.
*
* SYNOPSIS
*/
typedef NTSTATUS
(*IbQueryPort)(
IN IB_CA* const pCa,
IN const UCHAR PortNumber,
IN const SIZE_T AttrSize,
OUT IB_PORT_ATTR* const pAttr,
IN IRP* const pIrp );
/*
* PARAMETERS
* pCa
* [in] Pointer to an IB_CA structure previously created by a call to
* CiOpenCa.
*
* PortNumber
* [in] 1-based port number targetted by this request.
*
* pAttrSize
* [in] Size of the attributes buffer referenced by the pAttr parameter.
*
* pAttr
* [out] CA attribute of this Host Channel adapter.
*
* pIrp
* [in] IRP that will be completed when the request completes.
* The IRP major and minor functions as well as the I/O stack must
* be preserved when the IRP is completed. The Irp.RequestorMode
* can be used to distinguish kernel and user clients.
*
* RETURN VALUES
* STATUS_SUCCESS
* The full port attributes, including the GID and PKEY tables, were
* successfully copied to the attribute buffer.
* The IoStatus.Information field of the IRP is updated to indicate
* the number of bytes returned.
*
* STATUS_PENDING
* The operation could not be completed immediately. The HCA driver
* will complete the IRP when the operation completes, at which point
* the status of the operation will be returned in the IoStatus.Status
* field and the number of bytes returned in the IoStatus.Information
* field of the IRP.
*
* STATUS_BUFFER_OVERFLOW
* The operation completed but returned only partial attributes. Full
* attributes were not returned due to insufficient space. The size
* required to get the full attributes is returned in the Size field
* of the IB_PORT_ATTR structure. The IoStatus.Information field of
* the IRP is updated to indicate the number of bytes returned.
*
* STATUS_BUFFER_TOO_SMALL
* The pAttr buffer was too small to return any information. At a
* minimum, the buffer must be the 4 bytes to allow the required
* size to be returned.
*
* STATUS_FILE_FORCED_CLOSED
* The CA is no longer functional. The IRP will be completed with
* failure status. The client must release all resources and close
* the CA as soon as possible.
*
* Other status codes
* An error occurred. The IRP will be completed with failure status.
*
* NOTES
* This function can be invoked at IRQL <= DISPATCH_LEVEL.
*
* The HCA driver must call IoCallDriver for the input IRP so that it
* can call I/O complete request. The target of IoCallDriver must be
* the FDO of the HCA since the IRP will have only a single I/O stack
* location for the HCA to use. This implies that the IRP cannot be
* passed down a chain of layered drivers.
*********/
/****f* Verbs/CiModifyCa
* DESCRIPTION
* Modify the attributes of a Channel Adapter.
*
* SYNOPSIS
*/
typedef NTSTATUS
(*IbModifyCa)(
IN IB_CA* const pCa,
IN const ULONG Flags,
IN const IB_MODIFY_CA* const pModify,
IN IRP* const pIrp );
/*
* PARAMETERS
* pCa
* [in] Pointer to an IB_CA structure previously created by a call to
* CiOpenCa.
*
* Flags
* [in] Combination of IB_MODIFY_CA_FLAGS values indicating which
* fields are valid in the IB_MODIFY_CA structure.
*
* pModify
* [in] Pointer to an IB_MODIFY_CA structure with the fields specified
* by the Flags parameter set to the desired values.
*
* pIrp
* [in] IRP that will be completed when the request completes.
* The IRP major and minor functions as well as the I/O stack must
* be preserved when the IRP is completed. The Irp.RequestorMode
* can be used to distinguish kernel and user clients.
*
* RETURN VALUES
* STATUS_SUCCESS
* The CA was modified successfully.
*
* STATUS_PENDING
* The operation could not be completed immediately. The HCA driver
* will complete the IRP when the operation completes, at which point
* the status of the operation will be returned in the IoStatus.Status
* field of the IRP.
*
* STATUS_FILE_FORCED_CLOSED
* The CA is no longer functional. The IRP will be completed with
* failure status. The client must release all resources and close
* the CA as soon as possible.
*
* Other status codes
* An error occurred. The IRP will be completed with failure status.
*
* NOTES
* This function can be invoked at IRQL <= DISPATCH_LEVEL.
*
* The HCA driver must call IoCallDriver for the input IRP so that it
* can call I/O complete request. The target of IoCallDriver must be
* the FDO of the HCA since the IRP will have only a single I/O stack
* location for the HCA to use. This implies that the IRP cannot be
* passed down a chain of layered drivers.
*********/
/****f* Verbs/CiModifyPort
* DESCRIPTION
* Modify the attributes of a Channel Adapter's port.
*
* SYNOPSIS
*/
typedef NTSTATUS
(*IbModifyPort)(
IN IB_CA* const pCa,
IN const UCHAR PortNumber,
IN const ULONG Flags,
IN const IB_MODIFY_PORT* const pModify,
IN IRP* const pIrp );
/*
* PARAMETERS
* pCa
* [in] Pointer to an IB_CA structure previously created by a call to
* CiOpenCa.
*
* PortNumber
* [in] 1-based port number targetted by this request.
*
* Flags
* [in] Combination of IB_MODIFY_CA_FLAGS values indicating which
* fields are valid in the IB_MODIFY_CA structure.
*
* pModify
* [in] Pointer to an IB_MODIFY_CA structure with the fields specified
* by the Flags parameter set to the desired values.
*
* pIrp
* [in] IRP that will be completed when the request completes.
* The IRP major and minor functions as well as the I/O stack must
* be preserved when the IRP is completed. The Irp.RequestorMode
* can be used to distinguish kernel and user clients.
*
* RETURN VALUES
* STATUS_SUCCESS
* The CA's port was modified successfully.
*
* STATUS_PENDING
* The operation could not be completed immediately. The HCA driver
* will complete the IRP when the operation completes, at which point
* the status of the operation will be returned in the IoStatus.Status
* field of the IRP.
*
* STATUS_FILE_LOCK_CONFLICT
* The requested capabilities conflict with existing capabilities.
* This can occur if multiple clients try to bits such as
* IB_PORT_CAP_IS_SM or IB_PORT_CAP_CM_SUP bits in the port
* capabilities.
*
* STATUS_FILE_FORCED_CLOSED
* The CA is no longer functional. The IRP will be completed with
* failure status. The client must release all resources and close
* the CA as soon as possible.
*
* Other status codes
* An error occurred. The IRP will be completed with failure status.
*
* NOTES
* This function can be invoked at IRQL <= DISPATCH_LEVEL.
*
* The HCA driver must call IoCallDriver for the input IRP so that it
* can call I/O complete request. The target of IoCallDriver must be
* the FDO of the HCA since the IRP will have only a single I/O stack
* location for the HCA to use. This implies that the IRP cannot be
* passed down a chain of layered drivers.
*********/
typedef struct _IB_CQ_EVENT_DISPATCH
{
VOID (*CompEvent)(
IN VOID *CqContext );
VOID (*AsyncEvent)(
IN VOID *CqContext,
IN IB_ASYNC_EVENT Event );
} IB_CQ_EVENT_DISPATCH;
typedef struct _IB_CQ
{
IB_CA *pCa;
const IB_CQ_DISPATCH* const Dispatch;
ULONG NumCqes;
} IB_CQ;
/****f* Verbs/CiCreateCq
* DESCRIPTION
* Create a Completion Queue.
*
* SYNOPSIS
*/
typedef NTSTATUS
(*IbCreateCq)(
IN IB_CA* const pCa,
IN ULONG const NumCqes,
IN VOID* const Context,
IN const IB_CQ_DISPATCH* const Dispatch OPTIONAL,
IN OUT CI_UDATA* const pUserData,
IN IRP* const pIrp );
/*
* PARAMETERS
* pCa
* [in] Pointer to an IB_CA structure previously created by a call to
* CiOpenCa.
*
* NumCqes
* [in] Number of CQ entries requested by the consumer.
*
* Context
* [in] A pointer to a caller-supplied context for the CQ being
* created. The HCA driver passes this value to the client's
* event callback functions. If the client will not be using event
* callbacks, this value is unused.
*
* Dispatch
* [in] A pointer to a constant client IB_CQ_DISPATCH structure. This
* structure is a dispatch table that contains pointers to the event
* callback functions for the new CQ instance. Any members of the
* table can be NULL.
*
* pUserData
* [in] Descriptor for any data exchanged with the user-mode verb
* provider. The input and output buffers are shadowed by the
* access layer in non-paged pool. The HCA driver can only access
* further embedded pointers from the context of this call.
*
* pIrp
* [in] IRP that will be completed when the request completes.
* The IRP major and minor functions as well as the I/O stack must
* be preserved when the IRP is completed. The Irp.RequestorMode
* can be used to distinguish kernel and user clients.
*
* RETURN VALUES
* STATUS_SUCCESS
* The CQ was created successfully. The IB_CQ structure is returned
* in the IoStatus.Information field of the IRP. The IB_CQ structure
* contains the actual number of CQ entries allocated for the CQ.
*
* STATUS_PENDING
* The operation could not be completed immediately. The HCA driver
* will complete the IRP when the operation completes, at which point
* the status of the operation will be returned in the IoStatus.Status
* field and the IB_CQ structure in the IoStatus.Information field of
* the IRP. The IB_CQ structure contains the actual number of CQ
* entries allocated for the CQ.
*
* STATUS_FILE_FORCED_CLOSED
* The CA is no longer functional. The IRP will be completed with
* failure status. The client must release all resources and close
* the CA as soon as possible.
*
* Other status codes
* An error occurred. The IRP will be completed with failure status.
*
* NOTES
* This function can be invoked at IRQL <= DISPATCH_LEVEL.
*
* The HCA driver must call IoCallDriver for the input IRP so that it
* can call I/O complete request. The target of IoCallDriver must be
* the FDO of the HCA since the IRP will have only a single I/O stack
* location for the HCA to use. This implies that the IRP cannot be
* passed down a chain of layered drivers.
*********/
/****f* Verbs/CiDestroyCq
* DESCRIPTION
* Destroy a Completion Queue.
*
* SYNOPSIS
*/
typedef NTSTATUS
(*IbDestroyCq)(
IN IB_CQ* const pCq,
IN OUT CI_UDATA* const pUserData,
IN IRP* const pIrp );
/*
* PARAMETERS
* pCq
* [in] Pointer to an IB_CQ structure previously created by a call to
* CiCreateCq.
*
* pUserData
* [in] Descriptor for any data exchanged with the user-mode verb
* provider. The input and output buffers are shadowed by the
* access layer in non-paged pool. The HCA driver can only access
* further embedded pointers from the context of this call.
*
* pIrp
* [in] IRP that will be completed when the request completes.
* The IRP major and minor functions as well as the I/O stack must
* be preserved when the IRP is completed. The Irp.RequestorMode
* can be used to distinguish kernel and user clients.
*
* RETURN VALUES
* STATUS_SUCCESS
* The CQ was destroyed successfully. No futher operations can be
* performed on the CQ.
*
* STATUS_PENDING
* The operation could not be completed immediately. The HCA driver
* will complete the IRP when the operation completes, at which point
* the status of the operation will be returned in the IoStatus.Status
* field of the IRP.
*
* STATUS_DEVICE_BUSY
* The operation could not complete because the CQ instance has
* outstanding references from bound queue pairs.
*
* Other status codes
* An error occurred. The IRP will be completed with failure status.
*
* NOTES
* This function can be invoked at IRQL <= DISPATCH_LEVEL.
*
* The HCA driver must call IoCallDriver for the input IRP so that it
* can call I/O complete request. The target of IoCallDriver must be
* the FDO of the HCA since the IRP will have only a single I/O stack
* location for the HCA to use. This implies that the IRP cannot be
* passed down a chain of layered drivers.
*********/
/****f* Verbs/CiResizeCq
* DESCRIPTION
* Change the number of CQEs supported by a Completion Queue.
*
* SYNOPSIS
*/
typedef NTSTATUS
(*IbResizeCq)(
IN IB_CQ* const pCq,
IN ULONG const NumCqes,
IN OUT CI_UDATA* const pUserData,
IN IRP* const pIrp );
/*
* PARAMETERS
* pCq
* [in] Pointer to an IB_CQ structure previously created by a call to
* CiCreateCq.
*
* NumCqes
* [in] Number of CQ entries requested by the consumer.
*
* pUserData
* [in] Descriptor for any data exchanged with the user-mode verb
* provider. The input and output buffers are shadowed by the
* access layer in non-paged pool. The HCA driver can only access
* further embedded pointers from the context of this call.
*
* pIrp
* [in] IRP that will be completed when the request completes.
* The IRP major and minor functions as well as the I/O stack must
* be preserved when the IRP is completed. The Irp.RequestorMode
* can be used to distinguish kernel and user clients.
*
* RETURN VALUES
* STATUS_SUCCESS
* The CQ was resized successfully. The IB_CQ structure is updated
* with the actual number of CQ entries allocated for the CQ.
*
* STATUS_PENDING
* The operation could not be completed immediately. The HCA driver
* will complete the IRP when the operation completes, at which point
* the status of the operation will be returned in the IoStatus.Status
* field of the IRP. The IB_CQ structure is updated with the actual
* number of CQ entries allocated for the CQ.
*
* STATUS_FILE_FORCED_CLOSED
* The CA is no longer functional. The IRP will be completed with
* failure status. The client must release all resources and close
* the CA as soon as possible.
*
* Other status codes
* An error occurred. The IRP will be completed with failure status.
*
* NOTES
* This function can be invoked at IRQL <= DISPATCH_LEVEL.
*
* The HCA driver must call IoCallDriver for the input IRP so that it
* can call I/O complete request. The target of IoCallDriver must be
* the FDO of the HCA since the IRP will have only a single I/O stack
* location for the HCA to use. This implies that the IRP cannot be
* passed down a chain of layered drivers.
*********/
/****f* Verbs/CiRearmCq
* DESCRIPTION
* Requests that the completion queue generate a notifification when
* the next completion of the requested type is added.
*
* SYNOPSIS
*/
typedef NTSTATUS
(*IbRearmCq)(
IN IB_CQ* const pCq,
IN const BOOL Solicited );
/*
* PARAMETERS
* pCq
* [in] Pointer to an IB_CQ structure previously created by a call to
* CiCreateCq.
*
* Solicited
* [in] A flag indicating whether the request is to generate a
* notification on the next entry, if set to FALSE, or on the next
* solicited entry being added to the completion queue, if set to TRUE.
*
* RETURN VALUES
* STATUS_SUCCESS
* The CQ was rearmed successfully.
*
* Other status codes
* An error occurred.
*
* NOTES
* This function can be invoked at IRQL <= DISPATCH_LEVEL.
*********/
/****f* Verbs/CiRearmNCq
* DESCRIPTION
* Request that the completion queue generate a notification when
* the next N completions have been added to this CQ.
*
* SYNOPSIS
*/
typedef NTSTATUS
(*IbRearmNCq)(
IN IB_CQ* const pCq,
IN const ULONG NumCqes );
/*
* PARAMETERS
* pCq
* [in] Pointer to an IB_CQ structure previously created by a call to
* CiCreateCq.
*
* NumCqes
* [in] The number of completion queue entries to be added to the
* completion queue before notifying the client. This value must
* greater than or equal to one and less than or equal to the size
* of the completion queue.
*
* RETURN VALUES
* STATUS_SUCCESS
* The CQ was rearmed successfully.
*
* STATUS_INVALID_PARAMETER
* The requested number of completion queue entries was invalid.
*
* STATUS_NOT_SUPPORTED
* This operation is not supported by the channel adapter.
*
* Other status codes
* An error occurred.
*
* NOTES
* This function can be invoked at IRQL <= DISPATCH_LEVEL.
*********/
/****f* Verbs/CiResizeCq
* DESCRIPTION
* Poll a CQ for at most nCqe completions
*
* SYNOPSIS
*/
typedef NTSTATUS
(*IbPollCq)(
IN IB_CQ* const pCq,
IN const LONG NumCqes,
OUT IB_WC Wc[] );
/*
* PARAMETERS
* pCq
* [in] Pointer to an IB_CQ structure previously created by a call to
* CiCreateCq.
*
* NumCqes
* [in] Number of CQ entries requested by the consumer.
*
* Wc[]
* [in] Array of NumCqes IB_WC structures used to retrive completions
* from the completion queue. This buffer is resident and accessible
* from IQRL == DISPATCH_LEVEL.
*
* RETURN VALUES
* Returns a positive value indicating the number of CQEs polled,
* otherwise returns NTSTATUS error value.
*
* Other status codes
* An error occurred. The IRP will be completed with failure status.
*
* NOTES
* This function can be invoked at IRQL <= DISPATCH_LEVEL.
*********/
/****f* Verbs/CiResizeCq
* DESCRIPTION
* Peek a CQ and return the number of available work completions.
*
* SYNOPSIS
*/
typedef NTSTATUS
(*IbPeekCq)(
IN IB_CQ* const pCq );
/*
* PARAMETERS
* pCq
* [in] Pointer to an IB_CQ structure previously created by a call to
* CiCreateCq.
*
* RETURN VALUES
* Returns a positive value indicating the number of CQEs available,
* otherwise returns NTSTATUS error value.
*
* Other status codes
* An error occurred. The IRP will be completed with failure status.
*
* NOTES
* This function can be invoked at IRQL <= DISPATCH_LEVEL.
*********/
/****f* Verbs/CiGetCqCompEvent
* DESCRIPTION
* Queue a request for completion event notification.
*
* SYNOPSIS
*/
typedef NTSTATUS
(*IbGetCqCompEvent)(
IN IB_CQ* const pCq,
IN IRP* const pIrp );
/*
* PARAMETERS
* pCq
* [in] Pointer to an IB_CQ structure previously created by a call to
* CiCreateCq.
*
* pIrp
* [in] IRP that will be completed when the request completes.
* The IRP major and minor functions as well as the I/O stack must
* be preserved when the IRP is completed. The Irp.RequestorMode
* can be used to distinguish kernel and user clients.
*
* RETURN VALUES
* STATUS_SUCCESS
* The CQ experienced a completion event.
*
* STATUS_PENDING
* The operation could not be completed immediately. The HCA driver
* will complete the IRP upon the next completion event, at which point
* the status of the operation will be returned in the IoStatus.Status
* field of the IRP.
*
* STATUS_FILE_FORCED_CLOSED
* The CA is no longer functional. The IRP will be completed with
* failure status. The client must release all resources and close
* the CA as soon as possible.
*
* Other status codes
* An error occurred. The IRP will be completed with failure status.
*
* NOTES
* This function can be invoked at IRQL <= DISPATCH_LEVEL.
*
* The HCA driver must call IoCallDriver for the input IRP so that it
* can call I/O complete request. The target of IoCallDriver must be
* the FDO of the HCA since the IRP will have only a single I/O stack
* location for the HCA to use. This implies that the IRP cannot be
* passed down a chain of layered drivers.
*
* The HCA driver must set a cancel routine to allow clients to cancel
* the notification request.
*
* Only a single requests for notification can be queued at a time.
* Any previously queued request is completed with STATUS_CANCELLED.
* All such requests are completed with STATUS_CANCELLED if the IB_CQ
* instance is destroyed.
*********/
/****f* Verbs/CiGetCqAsyncEvent
* DESCRIPTION
* Queue a request for asynchronous event notification.
*
* SYNOPSIS
*/
typedef NTSTATUS
(*IbGetCqAsyncEvent)(
IN IB_CQ* const pCq,
IN IRP* const pIrp );
/*
* PARAMETERS
* pCq
* [in] Pointer to an IB_CQ structure previously created by a call to
* CiCreateCq.
*
* pIrp
* [in] IRP that will be completed when the request completes.
* The IRP major and minor functions as well as the I/O stack must
* be preserved when the IRP is completed. The Irp.RequestorMode
* can be used to distinguish kernel and user clients.
*
* RETURN VALUES
* STATUS_SUCCESS
* The CQ experienced an asynchronous event. The IoStatus.Information
* field of the IRP is updated with the IB_ASYNC_EVENT code.
*
* STATUS_PENDING
* The operation could not be completed immediately. The HCA driver
* will complete the IRP upon the next completion event, at which point
* the status of the operation will be returned in the IoStatus.Status
* and the IB_ASYNC_EVENT code is returned in the IoStatus.Information
* fields of the IRP.
*
* STATUS_FILE_FORCED_CLOSED
* The CA is no longer functional. The IRP will be completed with
* failure status. The client must release all resources and close
* the CA as soon as possible.
*
* Other status codes
* An error occurred. The IRP will be completed with failure status.
*
* NOTES
* This function can be invoked at IRQL <= DISPATCH_LEVEL.
*
* The HCA driver must call IoCallDriver for the input IRP so that it
* can call I/O complete request. The target of IoCallDriver must be
* the FDO of the HCA since the IRP will have only a single I/O stack
* location for the HCA to use. This implies that the IRP cannot be
* passed down a chain of layered drivers.
*
* The HCA driver must set a cancel routine to allow clients to cancel
* the notification request.
*
* A client can queue up mutiple requests for notification. Only one
* request is completed per event. All such requests are completed with
* STATUS_CANCELLED if the IB_CQ instance is destroyed.
*********/
typedef struct _IB_PD
{
IB_CA *pCa;
} IB_PD;
/****f* Verbs/CiCreatePd
* DESCRIPTION
* Create a Protection Domain.
*
* SYNOPSIS
*/
typedef NTSTATUS
(*IbCreatePd)(
IN IB_CA* const pCa,
IN OUT CI_UDATA* const pUserData,
IN IRP* const pIrp );
/*
* PARAMETERS
* pCa
* [in] Pointer to an IB_CA structure previously created by a call to
* CiOpenCa.
*
* pUserData
* [in] Descriptor for any data exchanged with the user-mode verb
* provider. The input and output buffers are shadowed by the
* access layer in non-paged pool. The HCA driver can only access
* further embedded pointers from the context of this call.
*
* pIrp
* [in] IRP that will be completed when the request completes.
* The IRP major and minor functions as well as the I/O stack must
* be preserved when the IRP is completed. The Irp.RequestorMode
* can be used to distinguish kernel and user clients.
*
* RETURN VALUES
* STATUS_SUCCESS
* The PD was created successfully. The IB_PD structure is returned
* in the IoStatus.Information field of the IRP.
*
* STATUS_PENDING
* The operation could not be completed immediately. The HCA driver
* will complete the IRP when the operation completes, at which point
* the status of the operation will be returned in the IoStatus.Status
* field and the IB_PD structure in the IoStatus.Information field of
* the IRP.
*
* STATUS_FILE_FORCED_CLOSED
* The CA is no longer functional. The IRP will be completed with
* failure status. The client must release all resources and close
* the CA as soon as possible.
*
* Other status codes
* An error occurred. The IRP will be completed with failure status.
*
* NOTES
* This function can be invoked at IRQL <= DISPATCH_LEVEL.
*
* The HCA driver must call IoCallDriver for the input IRP so that it
* can call I/O complete request. The target of IoCallDriver must be
* the FDO of the HCA since the IRP will have only a single I/O stack
* location for the HCA to use. This implies that the IRP cannot be
* passed down a chain of layered drivers.
*********/
/****f* Verbs/CiDestroyPd
* DESCRIPTION
* Destroy a Protection Domain.
*
* SYNOPSIS
*/
typedef NTSTATUS
(*IbDestroyPd)(
IN IB_PD* const pPd,
IN OUT CI_UDATA* const pUserData,
IN IRP* const pIrp );
/*
* PARAMETERS
* pPd
* [in] Pointer to an IB_PD structure previously created by a call to
* CiCreatePd.
*
* pUserData
* [in] Descriptor for any data exchanged with the user-mode verb
* provider. The input and output buffers are shadowed by the
* access layer in non-paged pool. The HCA driver can only access
* further embedded pointers from the context of this call.
*
* pIrp
* [in] IRP that will be completed when the request completes.
* The IRP major and minor functions as well as the I/O stack must
* be preserved when the IRP is completed. The Irp.RequestorMode
* can be used to distinguish kernel and user clients.
*
* RETURN VALUES
* STATUS_SUCCESS
* The PD was destroyed successfully. No futher operations can be
* performed on the PD.
*
* STATUS_PENDING
* The operation could not be completed immediately. The HCA driver
* will complete the IRP when the operation completes, at which point
* the status of the operation will be returned in the IoStatus.Status
* field of the IRP.
*
* STATUS_DEVICE_BUSY
* The operation could not complete because the CA instance has
* outstanding resources allocated.
*
* Other status codes
* An error occurred. The IRP will be completed with failure status.
*
* NOTES
* This function can be invoked at IRQL <= DISPATCH_LEVEL.
*
* The HCA driver must call IoCallDriver for the input IRP so that it
* can call I/O complete request. The target of IoCallDriver must be
* the FDO of the HCA since the IRP will have only a single I/O stack
* location for the HCA to use. This implies that the IRP cannot be
* passed down a chain of layered drivers.
*********/
typedef struct _IB_SRQ
{
IB_PD *pPd;
} IB_SRQ;
typedef NTSTATUS
(*IbPostSrqRecv)(
IN IB_SRQ* const pSrq,
IN const IB_RECV_WR* pRecvWr,
IN IB_RECV_WR** const ppFailedRecv );
typedef struct _IB_QP_EVENT_DISPATCH
{
VOID (*AsyncEvent)(
IN VOID *QpContext,
IN IB_ASYNC_EVENT Event );
} IB_QP_EVENT_DISPATCH;
typedef struct _IB_QP
{
const IB_QP_DISPATCH* const Dispatch;
IB_PD *pPd;
IB_CQ *pSendCq;
IB_CQ *pRecvCq;
IB_SRQ *pSrq;
IB_QP_TYPE Type;
ULONG Qpn;
ULONG SqDepth;
ULONG RqDepth;
ULONG SqSge;
ULONG RqSge;
ULONG SqMaxInline;
} IB_QP;
/****f* Verbs/CiCreateQp
* DESCRIPTION
* Create a Queue Pair.
*
* SYNOPSIS
*/
typedef NTSTATUS
(*IbCreateQp)(
IN IB_PD* const pPd,
IN IB_QP_CREATE* const pCreateQp,
IN VOID* const Context,
IN const IB_QP_DISPATCH* const Dispatch OPTIONAL,
IN OUT CI_UDATA* const pUserData,
IN IRP* const pIrp );
/*
* PARAMETERS
* pPd
* [in] Pointer to an IB_PD structure previously created by a call to
* CiCreatePd.
*
* pCreateAttr
* [in] Pointer to an IB_QP_CREATE structure containing the desired
* attributes for the newly created queue pair.
*
* Context
* [in] A pointer to a caller-supplied context for the QP being
* created. The HCA driver passes this value to the client's
* event callback functions. If the client will not be using event
* callbacks, this value is unused.
*
* Dispatch
* [in] A pointer to a constant client IB_QP_DISPATCH structure. This
* structure is a dispatch table that contains pointers to the event
* callback functions for the new QP instance. Any members of the
* table can be NULL.
*
* pUserData
* [in] Descriptor for any data exchanged with the user-mode verb
* provider. The input and output buffers are shadowed by the
* access layer in non-paged pool. The HCA driver can only access
* further embedded pointers from the context of this call.
*
* pIrp
* [in] IRP that will be completed when the request completes.
* The IRP major and minor functions as well as the I/O stack must
* be preserved when the IRP is completed. The Irp.RequestorMode
* can be used to distinguish kernel and user clients.
*
* RETURN VALUES
* STATUS_SUCCESS
* The QP was created successfully. The IB_QP structure is returned
* in the IoStatus.Information field of the IRP. The IB_QP structure
* contains the actual QP attributes allocated for the QP.
*
* STATUS_PENDING
* The operation could not be completed immediately. The HCA driver
* will complete the IRP when the operation completes, at which point
* the status of the operation will be returned in the IoStatus.Status
* field and the IB_QP structure in the IoStatus.Information field of
* the IRP. The IB_QP structure contains the actual QP attributes.
*
* STATUS_FILE_FORCED_CLOSED
* The CA is no longer functional. The IRP will be completed with
* failure status. The client must release all resources and close
* the CA as soon as possible.
*
* Other status codes
* An error occurred. The IRP will be completed with failure status.
*
* NOTES
* This function can be invoked at IRQL <= DISPATCH_LEVEL.
*
* The HCA driver must call IoCallDriver for the input IRP so that it
* can call I/O complete request. The target of IoCallDriver must be
* the FDO of the HCA since the IRP will have only a single I/O stack
* location for the HCA to use. This implies that the IRP cannot be
* passed down a chain of layered drivers.
*********/
/****f* Verbs/CiDestroyQp
* DESCRIPTION
* Destroy a Queue Pair.
*
* SYNOPSIS
*/
typedef NTSTATUS
(*IbDestroyQp)(
IN IB_QP* const pQp,
IN OUT CI_UDATA* const pUserData,
IN IRP* const pIrp );
/*
* PARAMETERS
* pQp
* [in] Pointer to an IB_QP structure previously created by a call to
* CiCreateQp.
*
* pUserData
* [in] Descriptor for any data exchanged with the user-mode verb
* provider. The input and output buffers are shadowed by the
* access layer in non-paged pool. The HCA driver can only access
* further embedded pointers from the context of this call.
*
* pIrp
* [in] IRP that will be completed when the request completes.
* The IRP major and minor functions as well as the I/O stack must
* be preserved when the IRP is completed. The Irp.RequestorMode
* can be used to distinguish kernel and user clients.
*
* RETURN VALUES
* STATUS_SUCCESS
* The QP was destroyed successfully. No futher operations can be
* performed on the QP.
*
* STATUS_PENDING
* The operation could not be completed immediately. The HCA driver
* will complete the IRP when the operation completes, at which point
* the status of the operation will be returned in the IoStatus.Status
* field of the IRP.
*
* STATUS_DEVICE_BUSY
* The operation could not complete because the QP instance has
* outstanding multicast memberships.
*
* Other status codes
* An error occurred. The IRP will be completed with failure status.
*
* NOTES
* This function can be invoked at IRQL <= DISPATCH_LEVEL.
*
* The HCA driver must call IoCallDriver for the input IRP so that it
* can call I/O complete request. The target of IoCallDriver must be
* the FDO of the HCA since the IRP will have only a single I/O stack
* location for the HCA to use. This implies that the IRP cannot be
* passed down a chain of layered drivers.
*********/
/****f* Verbs/CiModifyQp
* DESCRIPTION
* Modifies the attributes of a Queue Pair.
*
* SYNOPSIS
*/
typedef NTSTATUS
(*IbModifyQp)(
IN IB_QP* const pQp,
IN IB_QP_MODIFY* const pModify,
IN OUT CI_UDATA* const pUserData,
IN IRP* const pIrp );
/*
* PARAMETERS
* pQp
* [in] Pointer to an IB_QP structure previously created by a call to
* CiCreateQp.
*
* pModify
* [in] Specifies the attributes to modify and their requested values.
*
* pUserData
* [in] Descriptor for any data exchanged with the user-mode verb
* provider. The input and output buffers are shadowed by the
* access layer in non-paged pool. The HCA driver can only access
* further embedded pointers from the context of this call.
*
* pIrp
* [in] IRP that will be completed when the request completes.
* The IRP major and minor functions as well as the I/O stack must
* be preserved when the IRP is completed. The Irp.RequestorMode
* can be used to distinguish kernel and user clients.
*
* RETURN VALUES
* STATUS_SUCCESS
* The QP was modified successfully. The IB_QP structure is updated
* with the actual attributes.
*
* STATUS_PENDING
* The operation could not be completed immediately. The HCA driver
* will complete the IRP when the operation completes, at which point
* the status of the operation will be returned in the IoStatus.Status
* field of the IRP. The IB_QP structure is updated with the actual
* attribute.
*
* STATUS_FILE_FORCED_CLOSED
* The CA is no longer functional. The IRP will be completed with
* failure status. The client must release all resources and close
* the CA as soon as possible.
*
* Other status codes
* An error occurred. The IRP will be completed with failure status.
*
* NOTES
* This function can be invoked at IRQL <= DISPATCH_LEVEL.
*
* The HCA driver must call IoCallDriver for the input IRP so that it
* can call I/O complete request. The target of IoCallDriver must be
* the FDO of the HCA since the IRP will have only a single I/O stack
* location for the HCA to use. This implies that the IRP cannot be
* passed down a chain of layered drivers.
*********/
/****f* Verbs/CiQueryQp
* DESCRIPTION
* Modifies the attributes of a Queue Pair.
*
* SYNOPSIS
*/
typedef NTSTATUS
(*IbQueryQp)(
IN IB_QP* const pQp,
OUT IB_QP_ATTR* const pAttr,
IN OUT CI_UDATA* const pUserData,
IN IRP* const pIrp );
/*
* PARAMETERS
* pQp
* [in] Pointer to an IB_QP structure previously created by a call to
* CiCreateQp.
*
* pAttr
* [out] Pointer to an IB_QP_ATTR structure to update with the QP's
* attributes.
*
* pUserData
* [in] Descriptor for any data exchanged with the user-mode verb
* provider. The input and output buffers are shadowed by the
* access layer in non-paged pool. The HCA driver can only access
* further embedded pointers from the context of this call.
*
* pIrp
* [in] IRP that will be completed when the request completes.
* The IRP major and minor functions as well as the I/O stack must
* be preserved when the IRP is completed. The Irp.RequestorMode
* can be used to distinguish kernel and user clients.
*
* RETURN VALUES
* STATUS_SUCCESS
* The QP attributes were successfully retrieved.
*
* STATUS_PENDING
* The operation could not be completed immediately. The HCA driver
* will complete the IRP when the operation completes, at which point
* the status of the operation will be returned in the IoStatus.Status
* field of the IRP.
*
* STATUS_FILE_FORCED_CLOSED
* The CA is no longer functional. The IRP will be completed with
* failure status. The client must release all resources and close
* the CA as soon as possible.
*
* Other status codes
* An error occurred. The IRP will be completed with failure status.
*
* NOTES
* This function can be invoked at IRQL <= DISPATCH_LEVEL.
*
* The HCA driver must call IoCallDriver for the input IRP so that it
* can call I/O complete request. The target of IoCallDriver must be
* the FDO of the HCA since the IRP will have only a single I/O stack
* location for the HCA to use. This implies that the IRP cannot be
* passed down a chain of layered drivers.
*********/
/****f* Verbs/CiPostSend
* DESCRIPTION
* Posts a work request to the send queue of a queue pair.
*
* SYNOPSIS
*/
typedef NTSTATUS
(*IbPostSend)(
IN IB_QP* const pQp,
IN const IB_SEND_WR* pSendWr,
IN IB_SEND_WR** const ppFailedSend );
/*
* PARAMETERS
* pQp
* [in] Pointer to an IB_QP structure previously created by a call to
* CiCreateQp.
*
* pSendWr
* [in] A reference to the head of the send work request list. The list
* is resident and accessible from IRQL == DISPATCH_LEVEL.
*
* ppFailedSend
* [out] If the post send operation failed, this references the work
* request in the pSendWr list where the first failure occurred.
* This parameter may be NULL only if a single work request is being
* posted to the QP. The pointer is resident and accessible from
* IRQL == DISPATCH_LEVEL.
*
* RETURN VALUES
* STATUS_SUCCESS
* All work requests were successfully posted.
*
* STATUS_INVALID_PARAMETER
* A reference to the send work request list was not provided.
*
* STATUS_INSUFFICIENT_WR
* The number of posted work requests exceed the current depth available
* on the send queue.
*
* STATUS_INSUFFICIENT_SGE
* The number of scatter-gather entries referenced by the work request
* exceeded the send queue configuration.
*
* STATUS_INVALID_WR_TYPE
* The work request type was invalid.
*
* STATUS_INVALID_STATE
* The current queue pair state does not allow posting sends.
*
* STATUS_INVALID_OPERATION
* The requested operation is not supported by the queue pair.
*
* NOTES
* This function can be invoked at IRQL <= DISPATCH_LEVEL.
*****/
/****f* Verbs/CiPostRecv
* DESCRIPTION
* Posts a work request to the receive queue of a queue pair.
*
* SYNOPSIS
*/
typedef NTSTATUS
(*IbPostRecv)(
IN IB_QP* const pQp,
IN const IB_RECV_WR* pRecvWr,
IN IB_RECV_WR** const ppFailedRecv );
/*
* PARAMETERS
* pQp
* [in] Pointer to an IB_QP structure previously created by a call to
* CiCreateQp.
*
* pRecvWr
* [in] A reference to the head of the work request list.
*
* ppFailedRecv
* [out] If the post receive operation failed, this references the work
* request in the pRecvWr list where the first failure occurred.
* This parameter may be NULL only if a single work request is being
* posted to the QP.
*
* RETURN VALUES
* STATUS_SUCCESS
* All work requests were successfully posted.
*
* STATUS_INVALID_PARAMETER
* A reference to the send work request list was not provided.
*
* STATUS_INSUFFICIENT_WR
* The number of posted work requests exceed the current depth available
* on the send queue.
*
* STATUS_INSUFFICIENT_SGE
* The number of scatter-gather entries referenced by the work request
* exceeded the send queue configuration.
*
* STATUS_INVALID_WR_TYPE
* The work request type was invalid.
*
* STATUS_INVALID_STATE
* The current queue pair state does not allow posting sends.
*
* STATUS_INVALID_OPERATION
* The requested operation is not supported by the queue pair.
*
* NOTES
* This function can be invoked at IRQL <= DISPATCH_LEVEL.
*****/
/****f* Verbs/CiGetQpAsyncEvent
* DESCRIPTION
* Queue a request for asynchronous event notification.
*
* SYNOPSIS
*/
typedef NTSTATUS
(*IbGetQpAsyncEvent)(
IN IB_QP* const pQp,
IN IRP* const pIrp );
/*
* PARAMETERS
* pQp
* [in] Pointer to an IB_QP structure previously created by a call to
* CiCreateQp.
*
* pIrp
* [in] IRP that will be completed when the request completes.
* The IRP major and minor functions as well as the I/O stack must
* be preserved when the IRP is completed. The Irp.RequestorMode
* can be used to distinguish kernel and user clients.
*
* RETURN VALUES
* STATUS_SUCCESS
* The QP experienced an asynchronous event. The IoStatus.Information
* field of the IRP is updated with the IB_ASYNC_EVENT code.
*
* STATUS_PENDING
* The operation could not be completed immediately. The HCA driver
* will complete the IRP upon the next completion event, at which point
* the status of the operation will be returned in the IoStatus.Status
* and the IB_ASYNC_EVENT code is returned in the IoStatus.Information
* fields of the IRP.
*
* STATUS_FILE_FORCED_CLOSED
* The CA is no longer functional. The IRP will be completed with
* failure status. The client must release all resources and close
* the CA as soon as possible.
*
* Other status codes
* An error occurred. The IRP will be completed with failure status.
*
* NOTES
* This function can be invoked at IRQL <= DISPATCH_LEVEL.
*
* The HCA driver must call IoCallDriver for the input IRP so that it
* can call I/O complete request. The target of IoCallDriver must be
* the FDO of the HCA since the IRP will have only a single I/O stack
* location for the HCA to use. This implies that the IRP cannot be
* passed down a chain of layered drivers.
*
* The HCA driver must set a cancel routine to allow clients to cancel
* the notification request.
*
* A client can queue up mutiple requests for notification. Only one
* request is completed per event. All such requests are completed with
* STATUS_CANCELLED if the IB_QP instance is destroyed.
*********/
#define IB_VERBS_INTERFACE_VERSION (1)
typedef IB_VERBS_INTERFACE_STANDARD
{
INTERFACE wdm;
IbOpenCa OpenCa;
IbCloseCa CloseCa;
IbGetCaFatalEvent GetCaFatalEvent;
IbGetCaPortEvent GetCaPortEvent;
IbQueryCa QueryCa;
IbQueryPort QueryPort;
IbModifyCa ModifyCa;
IbModifyPort ModifyPort;
IbCreateCq CreateCq;
IbDestroyCq DestroyCq;
IbResizeCq ResizeCq;
IbRearmCq RearmCq;
IbRearmNCq RearmNCq;
IbPollCq PollCq;
IbPeekCq PeekCq;
IbGetCqCompEvent GetCqCompEvent;
IbGetCqAsyncEvent GetCqAsyncEvent;
IbCreatePd CreatePd;
IbDestroyPd DestroyPd;
//IbCreateSrq CreateSrq;
//IbDestroySrq DestroySrq;
//IbPostSrqRecv PostSrqRecv;
IbCreateQp CreateQp;
IbDestroyQp DestroyQp;
IbModifyQp ModifyQp;
IbQueryQp QueryQp;
IbPostSend PostSend;
IbPostRecv PostRecv;
}
#endif _IBVERBS_
/*
* CI interface GUID. The GUID is defined outside the conditional include
* on purpose so that it can be instantiated only once where it is actually
* needed. See the DDK docs section "Using GUIDs in Drivers" for more info.
*
* {B721E2B0-AF62-4320-A6AF-92F71F78789F}
*/
DEFINE_GUID(GUID_IB_VERBS_INTERFACE,
0xb721e2b0, 0xaf62, 0x4320, 0xa6, 0xaf, 0x92, 0xf7, 0x1f, 0x78, 0x78, 0x9f);
-------------- next part --------------
A non-text attachment was scrubbed...
Name: ibverbs.h
Type: application/octet-stream
Size: 54775 bytes
Desc: not available
URL: <http://lists.openfabrics.org/pipermail/ofw/attachments/20050916/e3abd2de/attachment.obj>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: ibdef.h
Type: application/octet-stream
Size: 8274 bytes
Desc: not available
URL: <http://lists.openfabrics.org/pipermail/ofw/attachments/20050916/e3abd2de/attachment-0001.obj>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: ibstatus.h
Type: application/octet-stream
Size: 1654 bytes
Desc: not available
URL: <http://lists.openfabrics.org/pipermail/ofw/attachments/20050916/e3abd2de/attachment-0002.obj>
More information about the ofw
mailing list