Skip to content

Latest commit

 

History

History
133 lines (85 loc) · 6.71 KB

IND2Provider.md

File metadata and controls

133 lines (85 loc) · 6.71 KB

IND2Provider interface

Use to discover the NetworkDirect adapters that the provider supports. For details on getting an instance of this interface, see Instantiating a NetworkDirect Provider. Note that NetworkDirect providers are not registered with the system by using COM registration, so you do not use the CoCreateInstance function to get this interface.

The IND2Provider interface inherits the methods of the IUnknown interface. In addition, IND2Provider defines the following methods:

  • QueryAddressList - Retrieves a list of local addresses that the provider supports.

  • ResolveAddress - Resolves a local IPv4 or IPv6 address to a unique adapter ID.

  • OpenAdapter - Retrieves an interface to a local NetworkDirect adapter.

Implementation Notes

Requirements for InfiniBand:

NetworkDirect providers use IP addresses to represent local and remote queue pairs, and it is the responsibility of the InfiniBand providers to manage mappings from these IP addresses to path records. Provides should use a distinct port space for RDMA connections, and only map to host TCP ports when absolutely necessary.

InfiniBand vendors should use the IP addressing annex to the IP specification for formatting the connection establishment messages. InfiniBand providers can use the TCP port space for connection management, but the port space should be managed separately from the host port space.

The InfiniBand 1.2 specification defines extensions to the architecture that provides matching semantics to iWARP. Specifically, the NetworkDirect SPI makes use of the following extensions:

  • Base Queue Management Extensions
  • Base Memory Management Extensions

Requirements for iWARP devices:

iWARP devices are expected to support establishing connections in RDMA mode without any streaming-mode support. RDMA read with local invalidate operations is not supported because the InfiniBand architecture does not support that capability.

Registration:

For details about how to register your provider, see the section Registering a NetworkDirect service provider.

IND2Provider::QueryAddressList

Retrieves a list of local addresses that the provider 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 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 that is 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 pAddressList buffer was not modified. The pcbAddressList parameter is updated with the required buffer size.

Remarks: To determine the required buffer size, set pAddressList to nullptr, and set the value that is pointed to by pcbAddressList to zero. Then, call this method and use the value that is returned in the pcbAddressList parameter to allocate the pAddressList buffer. You may need to perform these calls in a loop because the size could change between calls.

IND2Provider::ResolveAddress

Returns a provider-managed unique ID for an adapter when given a local IPv4 or IPv6 address.

HRESULT
ResolveAddress(
 [in]  const struct sockaddr *pAddress,
 [in]  ULONG cbAddress,
 [out] UINT64* pAdapterId
);

Parameters:

  • pAddress [in]

    A sockaddr structure that specifies the address of a local NetworkDirect adapter to open. Typically, this is a sockaddr_in structure for IPv4 addresses and a sockaddr_in6 structure for IPv6 addresses. The sin_port and sin6_port members are ignored for sockaddr_in and sockaddr_in6 address structures, respectively.

  • cbAddress [in]

    The size, in bytes, of the pAddress buffer.

  • pAdapterId [out]

    A unique identifier for the requested adapter.

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 call succeeded and the ID of the requested adapter is returned in the pAdapterId parameter.
  • ND_NO_MEMORY - There was not enough memory to resolve the address.
  • ND_INVALID_ADDRESS - The address specified by the pAddress parameter is not supported by the NetworkDirect provider.

Remarks:

A single NetworkDirect adapter can support more than a single IP address. By making the relationship between the addresses and the adapters explicit, this function allows sharing common resources such as completion queues and memory regions between connections that are active on different IP addresses of the same adapter.

IND2Provider::OpenAdapter

Retrieves an interface to a local NetworkDirect adapter.

HRESULT OpenAdapter(
 [in]  REFIID iid, 
 [in]  UINT64 adapterId,
 [out] void **ppAdapter
);

Parameters:

  • iid [in]

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

  • adapterId [in]

    ID returned by a previous call to the IND2Provider::ResolveAddress method.

  • ppAdapter [out]

    The requested interface to the opened adapter.

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 call succeeded and the handle to the opened adapter is returned in the ppAdapter parameter.
  • ND_NO_MEMORY - There was not enough memory to open the adapter.
  • ND_INVALID_PARAMETER - The adapterId specified is not valid.

Implementation Notes:

After getting an interface to the adapter, the application can release the IND2Provider interface. Providers must ensure that they remain loaded while resources are allocated.