Skip to content

Latest commit

 

History

History
705 lines (455 loc) · 33.5 KB

IND2Adapter.md

File metadata and controls

705 lines (455 loc) · 33.5 KB

IND2Adapter interface

Use to manage a NetworkDirect adapter. The IND2Provider::OpenAdapter method returns this interface.

The IND2Adapter interface inherits from IUnknown interface. In addition, IND2Adapter defines the following methods:

IND2Adapter::CreateOverlappedFile

Creates a file handle that will be used to process overlapped requests on interfaces derived from IND2Overlapped.

HRESULT CreateOverlappedFile(
 [out] HANDLE *phOverlappedFile
);

Parameters:

  • phOverlappedFile [out]

    A file handle used for performing overlapped requests on the adapter or its resources. The returned file handle must have been opened for overlapped I/O.

Return Value:

When you implement this method, you should return the following return values. If you return others, try to use well-known values to aid in debugging issues.

  • ND_SUCCESS - The operation completed successfully.
  • ND_NO_MEMORY - There was not enough memory to create the overlapped target.
  • ND_DEVICE_REMOVED - The underlying NetworkDirect adapter was removed from the system. Only cleanup operations on the NetworkDirect adapter will succeed.

Implementation Notes:

Providers must ensure that a misbehaved client that calls CloseHandle on the returned handle does not leak system resources or cause adverse effects on system stability or on another application's ability to use the adapter.

The returned file handle must have the following flags set through the Win32 SetFileCompletionNotificationModes API:

  • FILE_SKIP_COMPLETION_PORT_ON_SUCCESS
  • FILE_SKIP_SET_EVENT_ON_HANDLE

When an overlapped operation completes immediately (returns ND_SUCCESS), providers are not required to modify the OVERLAPPED structure that is associated with the request.

Exposing the file handle is simpler than wrapping all possible functions that a user might want to take on a file handle.

Remarks:

You could use the handle to perform the following tasks:

  • Bind to an I/O completion port if you want to get notification of overlapped operations (for example, memory registration or completion queue notification) delivered to an I/O completion port.
  • Associate the handle with the system thread pool by using the BindIoCompletionCallback function.

ND2_ADAPTER_INFO structure

Describes the capabilities and limits of the NetworkDirect adapter.

typedef struct _ND2_ADAPTER_INFO {
    ULONG   InfoVersion;
    
    UINT16  VendorId;
    UINT16  DeviceId;
    UINT64  AdapterId;
    
    SIZE_T  MaxRegistrationSize;
    SIZE_T  MaxWindowSize;
    
    ULONG   MaxInitiatorSge;
    ULONG   MaxReceiveSge;
    ULONG   MaxReadSge;
    
    ULONG   MaxTransferLength;
    ULONG   MaxInlineDataSize;
    
    ULONG   MaxInboundReadLimit;
    ULONG   MaxOutboundReadLimit;
    
    ULONG   MaxReceiveQueueDepth;
    ULONG   MaxInitiatorQueueDepth;
    ULONG   MaxSharedReceiveQueueDepth;
    ULONG   MaxCompletionQueueDepth;
    
    ULONG   InlineRequestThreshold;
    ULONG   LargeRequestThreshold;
    
    ULONG   MaxCallerData;
    ULONG   MaxCalleeData;
    
    ULONG   AdapterFlags;
} ND2_ADAPTER_INFO;

Members:

  • InfoVersion

    The version of this structure, currently 1.

  • VendorId

    The vendor ID, which is typically the vendor's organizational unique identifier (OUI).

  • DeviceId

    Vendor defined device ID of the adapter.

  • AdapterId

    Vendor defined unique ID of the adapter (similar to a MAC address for an Ethernet network adapter).

  • MaxRegistrationSize

    The maximum size, in bytes, of an application-defined buffer that you can register using IND2MemoryRegion::Register. This is the maximum size of a single registration that the adapter can address.

    Note that since each SGE of a request references a memory registration, a single request could transfer more than this limit.

  • MaxWindowSize

    Not used

  • MaxInitiatorSge

    The maximum number of scatter/gather entries that a queue pair supports for Send and Write requests.

  • MaxReceiveSge

    The maximum number of scatter/gather entries that a queue pair supports for Receive requests.

  • MaxReadSge

    The maximum number of scatter/gather entries that a queue pair supports for Read requests. Must be less than or equal to the MaxInitiatorSge value.

  • MaxTransferLength

    The maximum length, in bytes, that can be referenced by all the scatter/gather entries for a request that is issued to a queue pair.

  • MaxInlineDataSize

    The amount of data that a QueuePair can transfer directly to the device as part of a Send or Write request without further DMA operations.

  • MaxInboundReadLimit

    The maximum number of in-progress Read operations with a local queue pair as target.

  • MaxOutboundReadLimit

    The maximum number of in-progress Read operations with a local queue pair as initiator.

  • MaxReceiveQueueDepth

    The maximum number of outstanding Receive requests for a queue pair.

  • MaxInitiatorQueueDepth

    The maximum number of outstanding Send, Bind, Invalidate, Read, and Write requests for a queue pair.

  • MaxSharedReceiveQueueDepth

    Maximum number of Receive requests that can be outstanding on a shared receive queue at a time. May be zero if the adapter does not support shared receive queues.

  • MaxCompletionQueueDepth

    The maximum number of queue pair operation completions that can be queued to a completion queue.

  • InlineRequestThreshold

    Transfer size, in bytes, below which inline Send and Write operations will yield better results than DMA out of preregistered buffers.

  • LargeRequestThreshold

    The data size, in bytes, above which Read and Write operations will yield better results than Send and Receive operations.

  • MaxCallerData

    The maximum size, in bytes, of the private data that can be sent when calling the IND2Connector::Connect method.

  • MaxCalleeData

    The maximum size, in bytes, of the private data that can be sent when calling the IND2Connector::Accept method or the IND2Connector::Reject method.

  • AdapterFlags

    Flags indicating adapter capabilities

    • ND_ADAPTER_FLAG_IN_ORDER_DMA_SUPPORTED

      Flag indicating whether the adapter places the data in memory in order. May allow some optimization in data transfers, although care must be taken in platforms where DMA controllers can buffer or reorder memory writes.

    • ND_ADAPTER_FLAG_CQ_INTERRUPT_MODERATION_SUPPORTED

      Flag indicating support for completion queue moderation.

    • ND_ADAPTER_FLAG_MULTI_ENGINE_SUPPORTED

      Flag indicating whether the adapter supports progressing completion queues in parallel.

    • ND_ADAPTER_FLAG_CQ_RESIZE_SUPPORTED

      Flag indicating whether the provider supports programmatically controlled interrupt moderation for each completion queue.

    • ND_ADAPTER_FLAG_LOOPBACK_CONNECTIONS_SUPPORTED

      Flag indicating whether the adapter supports loopback connections.

Implementation Notes:

Inline data is no longer per-SGE, but rather per request. Clients are provided with the capability to size their QueuePairs as required to support their usage model.

Remarks: This structure defines the standard parameters of all NetworkDirect adapters. Only Send and Write requests can use inline data functionality.

See also NDK_ADAPTER_INFO structure.

IND2Adapter::Query

Retrieves the capabilities and limits of the NetworkDirect adapter.

HRESULT Query(
 [in, out, optional] ND2_ADAPTER_INFO *pInfo,
 [in, out] ULONG *pcbInfo
);

Parameters:

  • pInfo [in, out, optional]

    An ND2_ADAPTER_INFO structure that will contain the NetworkDirect adapter's information. May be nullptr if *pcbInfo is zero. If non-nullptr, the InfoVersion member must be set on input.

  • pcbInfo [in, out]

    The size, in bytes, of the pInfo buffer. If the buffer is too small to hold the information, the method fails with ND_BUFFER_OVERFLOW, and it sets this parameter to the required buffer size. If the buffer is too big on input, the method sets this parameter to the size used.

Return Value:

When you implement this method, you should return the following return values. If you return others, try to use well-known values to aid in debugging issues.

  • ND_SUCCESS - The adapter information was retrieved.
  • ND_BUFFER_OVERFLOW - The pInfo buffer is not large enough to hold the adapter information,and the buffer was not modified. The pcbInfo parameter is updated with the required buffer size.

Implementation Notes:

A query for the capabilities must return ND_SUCCESS if the input buffer size is sizeof(ND2_ADAPTER_INFO), even if there is additional vendor-specific data that isn’t returned.

Remarks:

To determine the required buffer size, you can set pInfo to nullptr and the value pointed to by pcbInfo to zero. Then, call this method and use the returned value pointed to by pcbInfo to allocate the pInfo buffer.

The limits are provided by the NetworkDirect adapter hardware, which are independent of actual system resource limits such as available memory. The maximum limits reported may not be realized due to system load.

Getting the limits before you create a queue pair or completion queue or before you register memory will let you know if your application can run within the limits of hardware.

  • You can use the LargeRequestThreshold member of ND2_ADAPTER_INFO to determine when Read and Write operations will yield better results than using Send and Receive.
  • You can use the InlineRequestThreshold member of ND2_ADAPTER_INFO to determine when inline Send and Write operations will yield better results than using traditional DMA.

Implementation Note:

The LargeRequestThreshold and InlineRequestThreshold values should be dynamically determined by providers whenever possible.

IND2Adapter::QueryAddressList

Retrieves a list of local addresses that the adapter supports.

HRESULT QueryAddressList(
 [in, out, optional] SOCKET_ADDRESS_LIST *pAddressList,
 [in, out] ULONG *pcbAddressList
);

Parameters:

  • pAddressList [in, out, optional]

    A list of addresses that the NetworkDirect adapters support. (For details of the list, see the SOCKET_ADDRESS_LIST structure. May be nullptr if pcbAddressList is zero.

  • pcbAddressList [in, out]

    The size, in bytes, of the pAddressList buffer. If the buffer is too small to hold the addresses, the method fails with ND_BUFFER_OVERFLOW and sets this parameter to the required buffer size. If the buffer is too big, the method sets this parameter to the size used on output.

Return Value:

When you implement this method, you should return the following return values. If you return others, try to use well-known values to aid in debugging issues.

  • ND_SUCCESS - All addresses supported by NetworkDirect adapters were returned in pAddressList.
  • ND_BUFFER_OVERFLOW- The pAddressList buffer is not large enough to hold the addresses, and the buffer was not modified. The pBufferSize parameter is updated with the required buffer size.

Remarks:

To determine the required buffer size, set pAddressList to nullptr and pcbAddressList to zero. Then call this method and use the value returned in the pcbAddressList parameter to allocate the pAddressList buffer. You should perform these calls in a loop because the size could change between calls.

IND2Adapter::CreateCompletionQueue

Allocates a completion queue.

HRESULT CreateCompletionQueue(
 [in]  REFIID iid,
 [in]  HANDLE hOverlappedFile,
 [in]  ULONG queueDepth,
 [in]  USHORT group,
 [in]  KAFFINITY affinity, 
 [out] void **ppCompletionQueue
);

Parameters:

  • iid [in]

    The IID of the completion queue interface requested. IID_IND2CompletionQueue must be supported, but other IIDs may be supported as new interfaces are defined.

  • hOverlappedFile [in]

    Handle returned by a previous call to IND2Adapter::CreateOverlappedFile, on which overlapped operations on this completion queue should be performed.

  • queueDepth [in]

    The number of completion queue entries to support. The value must be greater than zero and less than the MaxCqDepth member of the ND2_ADAPTER_INFO structure.

  • group [in]

    Processor group number for the requested affinity. This value must be 0 if the operating system does not support processor groups.

  • affinity [in]

    A bitmap that specifies the processor affinity on which notifications should be processed by the hardware if possible. If affinity cannot be set for completion queue notifications, this value is silently ignored. Set to 0 if no specific affinity is requested.

  • ppCompletionQueue [out]

    An IND2CompletionQueue interface to the completion queue.

Return Value:

When you implement this method, you should return the following return values. If you return others, try to use well-known values to aid in debugging issues.

  • ND_SUCCESS - The operation completed successfully.
  • ND_NO_MEMORY - There was not enough memory to create the completion queue.
  • ND_INSUFFICIENT_RESOURCES - There were not enough hardware resources to create the completion queue.
  • ND_INVALID_PARAMETER_3 - The adapter cannot support the requested number of entries.
  • ND_DEVICE_REMOVED - The underlying NetworkDirect adapter was removed from the system. Only cleanup operations on the NetworkDirect adapter will succeed.

Implementation Notes:

Provider implementations should set the notify affinity (including interrupt affinity if applicable) to one or more of the specified processors in the following order: requested affinity, calling thread affinity, preferably the calling thread’s ideal processor, or process affinity. If none of these can be supported, the providers should attempt to set affinity to the closest processor to the requested settings, in the same order: requested affinity, calling thread affinity, process affinity.

Remarks:

You must create at least one completion queue. You can create one for inbound requests and another for outbound requests, or you can use the same queue for both. You specify the completion queue when you call IND2Adapter::CreateQueuePair to create a queue pair. More than one queue pair can specify the same completion queue.

IND2Adapter::CreateMemoryRegion

Allocates a memory region.

HRESULT CreateMemoryRegion(
 [in]  REFIID iid, 
 [in]  HANDLE hOverlappedFile,
 [out] void **ppMemoryRegion
);

Parameters:

  • iid [in]

    The IID of the memory region interface requested. IID_IND2MemoryRegion must be supported, but other IIDs may be supported as new interfaces are defined.

  • hOverlappedFile [in]

    Handle returned by a previous call to IND2Adapter::CreateOverlappedFile, on which overlapped operations on this memory region should be performed.

  • ppMemoryRegion [out]

    An IND2MemoryRegion interface to the memory region.

Return Value:

When you implement this method, you should return the following return values. If you return others, try to use well-known values to aid in debugging issues.

  • ND_SUCCESS - The operation completed successfully.
  • ND_NO_MEMORY - There was not enough memory to create the memory region.
  • ND_INSUFFICIENT_RESOURCES - There was not enough hardware resources to create the memory region.
  • ND_DEVICE_REMOVED - The underlying NetworkDirect adapter was removed from the system. Only cleanup operations on the NetworkDirect adapter will succeed.

Remarks

You must create memory regions to reference memory in data transfer operations.

IND2Adapter::CreateMemoryWindow

Creates an uninitialized memory window.

HRESULT CreateMemoryWindow(
 [in] REFIID iid, 
 [out] void **ppMemoryWindow
);

Parameters:

  • iid [in]

    The IID of the memory window interface requested. IID_IND2MemoryWindow must be supported, but other IIDs may be supported as new interfaces are defined.

  • ppMemoryWindow [out]

    An INDMemoryWindow interface.

Return Value:

When you implement this method, you should return the following return values. If you return others, try to use well-known values to aid in debugging issues.

  • ND_SUCCESS - The operation completed successfully.
  • ND_INSUFFICIENT_RESOURCES - There was not enough hardware resources to create the memory window.
  • ND_DEVICE_REMOVED - The underlying NetworkDirect adapter was removed from the system. Only cleanup operations on the NetworkDirect adapter will succeed.

Remarks:

You need to create a memory window and bind it to registered memory only if the connected peer is going to perform Read and Write operations and you want fine-grained access control to a long-lived memory registration. The side issuing the Read and Write requests does not create the memory window.

The memory window becomes valid when you bind it to registered memory. For more information, see IND2Adapter::CreateMemoryRegion method.

To bind the window to registered memory, call the IND2QueuePair::Bind method. The window can be bound to only a single queue pair at one time. However, the window could be bound to a different queue pair after being invalidated.

To invalidate the window, call the IND2QueuePair::Invalidate method. You should not invalidate the window unless you receive a message from the connected peer indicating that the connected peer is done accessing the window.

IND2Adapter::CreateSharedReceiveQueue

Allocates a shared receive queue.

HRESULT CreateSharedReceiveQueue(
 [in]  REFIID iid, 
 [in]  HANDLE hOverlappedFile,
 [in]  ULONG queueDepth,
 [in]  ULONG maxRequestSge,
 [in]  ULONG notifyThreshold,
 [in]  USHORT group,
 [in]  KAFFINITY affinity,
 [out] void **ppSharedReceiveQueue
);

Parameters:

  • iid [in]

    The IID of the shared receive queue interface requested. IID_IND2SharedReceiveQueue must be supported, but other IIDs may be supported as new interfaces are defined.

  • hOverlappedFile [in]

    Handle returned by a previous call to IND2Adapter::CreateOverlappedFile, on which overlapped operations on this shared receive queue should be performed.

  • queueDepth [in]

    The maximum number of outstanding Receive requests.

  • maxRequestSge [in]

    The maximum number of scatter/gather entries to support for Receive requests.

  • notifyThreshold [in]

    The number of outstanding Receive requests below which the shared receive queue will complete any Notify requests in order for the application to post more buffers. May be zero to disable notifications.

  • group [in]

    Processor group number for the requested affinity. This value must be 0 if the operating system does not support processor groups.

  • affinity [in]

    A bitmap that specifies the processor affinity on which notifications should be processed by the hardware if possible. If affinity cannot be set for shared receive queue notifications, this value is silently ignored. Set to 0 if no specific affinity is requested.

  • ppSharedReceiveQueue [out]

    An IND2SharedReceiveQueue interface to the shared receive queue.

Return Value:

When you implement this method, you should return the following return values. If you return others, try to use well-known values to aid in debugging issues.

  • ND_SUCCESS - The operation completed successfully.
  • ND_NO_MEMORY - There was not enough memory to create the completion queue.
  • ND_INSUFFICIENT_RESOURCES - There was not enough hardware resources to create the completion queue.
  • ND_INVALID_PARAMETER_3 - The adapter cannot support the requested number of entries.
  • ND_INVALID_PARAMETER_4 - The adapter cannot support the requested number of scatter/gather entries.
  • ND_DEVICE_REMOVED - The underlying NetworkDirect adapter was removed from the system. Only cleanup operations on the NetworkDirect adapter will succeed.

Implementation Notes:

Provider implementations should set the notify affinity (including interrupt affinity if applicable) to one or more of the specified processors in the following order: requested affinity, calling thread affinity, preferably the calling thread’s ideal processor, or process affinity. If none of these can be supported, the providers should attempt to set affinity to the closest processor to the requested settings, in the same order: requested affinity, calling thread affinity, process affinity.

Remarks:

Shared receive queues allow pooling receive buffers between multiple queue pairs. To use a shared receive queue, you must create queue pairs by using IND2Adapter::CreateQueuePairWithSrq method.

IND2Adapter::CreateQueuePair

Creates a queue pair to use for data transfers.

HRESULT CreateQueuePair(
 [in]  REFIID iid, 
 [in]  IUnknown *pReceiveCompletionQueue,
 [in]  IUnknown *pInitiatorCompletionQueue,
 [in]  void *context,
 [in]  ULONG receiveQueueDepth,
 [in]  ULONG initiatorQueueDepth,
 [in]  ULONG maxReceiveRequestSge,
 [in]  ULONG maxInitiatorRequestSge,
 [in]  ULONG inlineDataSize,
 [out] void **ppQueuePair
);

Parameters:

  • iid [in]

    The IID of the queue pair interface requested. IID_IND2QueuePair must be supported, but other IIDs may be supported as new interfaces are defined.

  • pReceiveCompletionQueue [in]

    An IND2CompletionQueue interface. The interface is used to queue Receive request results.

  • pInitiatorCompletionQueue [in]

    An IND2CompletionQueue interface. The interface is used to queue Send, Bind, Invalidate, Read, and Write request results.

  • context [in]

    Context value to associate with the queue pair, returned in the RequestContext member of the ND2_RESULT structure when calling IND2CompletionQueue::GetResults.

  • receiveQueueDepth [in]

    The maximum number of outstanding Receive requests.

  • initiatorQueueDepth [in]

    The maximum number of outstanding Send, Bind, Invalidate, Read, and Write requests.

  • maxReceiveRequestSge [in]

    The maximum number of scatter/gather entries supported for Receive requests.

  • maxInitiatorRequestSge [in]

    The maximum number of scatter/gather entries supported for Send, Read, and Write requests.

  • inlineDataSize [in]

    The maximum inline data size supported for Send and Write requests.

  • ppQueuePair [out]

    An IND2QueuePair interface.

Return Value:

When you implement this method, you should return the following return values. If you return others, try to use well-known values to aid in debugging issues.

  • ND_SUCCESS - The operation completed successfully.
  • ND_INVALID_PARAMETER_2 - The pReceiveCompletionQueue parameter was not valid.
  • ND_INVALID_PARAMETER_3 - The pInitiatorCompletionQueue parameter was not valid.
  • ND_INVALID_PARAMETER_5 - The receiveQueueDepth parameter exceeded the limits of the NetworkDirect adapter.
  • ND_INVALID_PARAMETER_6 - The initiatorQueueDepth parameter exceeded the limits of the NetworkDirect adapter.
  • ND_INVALID_PARAMETER_7 - The maxReceiveRequestSge parameter exceeded the limits of the NetworkDirect adapter.
  • ND_INVALID_PARAMETER_8 - The maxInitiatorRequestSge parameter exceeded the limits of the NetworkDirect adapter.
  • ND_INVALID_PARAMETER_9 - The inlineDataSize parameter exceeded the limits of the NetworkDirect adapter.
  • ND_INSUFFICIENT_RESOURCES - There were not enough hardware resources to create the queue pair.
  • ND_DEVICE_REMOVED - The underlying NetworkDirect adapter was removed from the system. Only cleanup operations on the NetworkDirect adapter will succeed.

Implementation Notes:

NetworkDirect service providers are free to return more resources than requested, but there are no mechanisms to advertise the excess. It is not possible to change these parameters after a queue pair is created.

Remarks

To get the limits that are supported by the NetworkDirect adapter, call the IND2Adapter::Query method.

You can specify the same completion queue for both pReceiveCompletionQueue and pInitiatorCompletionQueue. The initiator completion queue reports completions for all requests other than Receive requests.

An instance of the IND2Connector interface can have only a single queue pair associated with it at a time. To disassociate the queue pair from the connector, the queue pair must be disconnected.

IND2Adapter::CreateQueuePairWithSrq

Creates a queue pair to use for data transfers that are associated with a shared receive queue.

HRESULT CreateQueuePairWithSrq(
 [in]  REFIID iid, 
 [in]  IUnknown *pReceiveCompletionQueue,
 [in]  IUnknown *pInitiatorCompletionQueue,
 [in]  IUnknown *pSharedReceiveQueue,
 [in]  void *context,
 [in]  ULONG initiatorQueueDepth,
 [in]  ULONG maxInitiatorRequestSge,
 [in]  ULONG inlineDataSize,
 [out] void **ppQueuePair
);

Parameters:

  • iid [in]

    The IID of the queue pair interface requested. IID_IND2QueuePair must be supported, but other IIDs may be supported as new interfaces are defined.

  • pReceiveCompletionQueue [in]

    An IND2CompletionQueue interface. The interface is used to queue Receive request results.

  • pInitiatorCompletionQueue [in]

    An IND2CompletionQueue interface. The interface is used to queue Send, Bind, Invalidate, Read, and Write request results.

  • pSharedReceiveQueue [in]

    An IND2SharedReceiveQueue interface. The interface is used to issue Receive requests.

  • context [in]

    Context value to associate with the queue pair, returned in the RequestContext member of the ND2_RESULT structure when calling IND2CompletionQueue::GetResults.

  • initiatorQueueDepth [in]

    The maximum number of outstanding Send, Bind, Invalidate, Read, and Write requests.

  • maxInitiatorRequestSge [in]

    The maximum number of scatter/gather entries supported for Send, Read, and Write requests.

  • inlineDataSize [in]

    The maximum inline data size supported for Send and Write requests.

  • ppQueuePair [out]

    An IND2QueuePair interface.

Return Value:

When you implement this method, you should return the following return values. If you return others, try to use well-known values to aid in debugging issues.

  • ND_SUCCESS - The operation completed successfully.
  • ND_NOT_SUPPORTED - Shared receive queue functionality is not supported by the adapter.
  • ND_INVALID_PARAMETER_2 - The pReceiveCompletionQueue parameter was not valid.
  • ND_INVALID_PARAMETER_3 - The pInitiatorCompletionQueue parameter was not valid.
  • ND_INVALID_PARAMETER_4 - The pSharedReceiveQueue parameter was not valid.
  • ND_INVALID_PARAMETER_6 - The initiatorQueueDepth parameter exceeded the limits of the NetworkDirect adapter.
  • ND_INVALID_PARAMETER_7 - The maxInitiatorRequestSge parameter exceeded the limits of the NetworkDirect adapter.
  • ND_INVALID_PARAMETER_8 - The inlineDataSize parameter exceeded the limits of the NetworkDirect adapter.
  • ND_INSUFFICIENT_RESOURCES - There were not enough hardware resources to create the queue pair.
  • ND_DEVICE_REMOVED- The underlying NetworkDirect adapter was removed from the system. Only cleanup operations on the NetworkDirect adapter will succeed.

Implementation Notes:

NetworkDirect providers are free to return more resources than requested, but there are no mechanisms to advertise the excess. It is not possible to change these parameters after a queue pair is created.

Providers must ensure that a Send request that arrives at a queue pair that is bound to an empty shared receive queue does not cause the connection to fail.

Remarks:

To get the limits that are supported by the NetworkDirect adapter, call the IND2Adapter::Query method.

You can specify the same completion queue for both pReceiveCompletionQueue and pInitiatorCompletionQueue. The initiator completion queue reports completions for all requests other than Receive requests.

An instance of the IND2Connector interface can have only a single queue pair bound to it at a time. To unbind the queue pair from the connector, the queue pair must be disconnected.

When using a shared receive queue, client applications cannot depend on credit flow control. Flow control in this case is managed by the hardware.

IND2Adapter::CreateConnector

Creates a new IND2Connector instance.

HRESULT CreateConnector(
 [in]  REFIID iid, 
 [in]  HANDLE hOverlappedFile,
 [out] void **ppConnector
);

Parameters:

  • iid [in]

    The IID of the connector interface requested. IID_IND2Connector must be supported, but other IIDs may be supported as new interfaces are defined.

  • hOverlappedFile [in]

    Handle returned by a previous call to IND2Adapter::CreateOverlappedFile, on which overlapped operations on this connector should be performed.

  • ppConnector [out]

    The requested interface that you use to connect to a remote peer.

Return Value:

When you implement this method, you should return the following return values. If you return others, try to use well-known values to aid in debugging issues.

  • ND_SUCCESS - The operation completed successfully.
  • ND_NO_MEMORY - There was not enough memory to create the connector.
  • ND_INSUFFICIENT_RESOURCES - There was not enough hardware resources to create the connector.
  • ND_DEVICE_REMOVED - The underlying NetworkDirect adapter was removed from the system. Only cleanup operations on the NetworkDirect adapter will succeed.

IND2Adapter::CreateListener

Creates a new IND2Listener instance.

HRESULT CreateListener(
 [in]  REFIID iid, 
 [in]  HANDLE hOverlappedFile,
 [out] void **ppListener
);

Parameters:

  • iid [in]

    The IID of the listener interface requested. IID_IND2Listener must be supported, but other IIDs may be supported as new interfaces are defined.

  • hOverlappedFile [in]

    Handle returned by a previous call to IND2Adapter::CreateOverlappedFile, on which overlapped operations on this listen should be performed.

  • ppListener [out]

    The requested interface that you use to listen for connection requests.

Return Value:

When you implement this method, you should return the following return values. If you return others, try to use well-known values to aid in debugging issues.

  • ND_SUCCESS - The operation completed successfully.
  • ND_NO_MEMORY - There was not enough memory to create the connector.
  • ND_INSUFFICIENT_RESOURCES - There was not enough hardware resources to create the connector.
  • ND_DEVICE_REMOVED - The underlying NetworkDirect adapter was removed from the system. Only cleanup operations on the NetworkDirect adapter will succeed.