Mellanox WinOF VPI Documentation v5.50.53000
Linux Kernel Upstream Release Notes v6.5

RDMA Features

IND2ProviderControl Interface

Instantiating a NetworkDirect Provider Control

To use the new API call, the library's DllGetClassObject entry point must instantiate the IND2ProviderControl interface, using the IID_IND2ProviderControl iid.

Example:Disabling Mellanox Device while NetworkDirect Applications are Running

Copy
Copied!
            

AutoRef<IClassFactory> aClassFactory; //…..// AutoRef<IND2ProviderControl> aProviderControl; hr = aClassFactory->CreateInstance(NULL, IID_IND2ProviderControl, (void**)&aProvider-Control); RETURN_IF_FAILED(hr);

ND2RegisterForAdapterStatus

Once an IND2ProviderControl instance is instantiated, the following function can be called to register an adapter into the provider status mechanism:

Syntax:

Copy
Copied!
            

HRESULT Nd2RegisterForAdapterStatus( __in IND2ProviderControl* pCtrl, __in IND2_FN_ADAPTER_STATUS* pfnCallback, __in void* pvContext, __in_bcount(cbAddress) const struct sockaddr* pAddress, __in ULONG cbAddress, __deref_out void** ppHandle )

Parameters:

The IND2ProviderControl instance is created by the IClassFactory::CreateInstance function.

  • IND2ProviderControl [in]: The function callback that is called once a status change is detected for the specific adapter, detailed for the function parameters.

  • pvContext [in]: A context value to associate with the registered adapter.

  • pAddress [in]: A sockaddr buffer that specifies the local address to use for the shared endpoint. Typically, this is a sockaddr_in structure for IPv4 addresses and a sockaddr_in6 structure for IPv6 addresses.
    If the sin_port or sin6_port member is specified as zero, the provider assigns a unique port number to the application from the ephemeral port range.

  • cbAddress [in]: The size, in bytes, of the pAddress buffer.

  • ppHandle [out]: The handle of the registered adapter. This parameter must be called with Nd2DeregisterForAdapterStatus before the final release of the Nd2RegisterForAdapterStatus instance.

Return value:

Return Code

Description

ND_SUCCESS

The operation succeeded.

IND2_FN_ADAPTER_STATUS

The following is the function callback signature that must be provided to the Nd2RegisterForAdapterStatus function to be called upon an adapter status change:

Syntax:

Copy
Copied!
            

void CALLBACK IND2_FN_ADAPTER_STATUS( __in void* pvContext, __in_bcount(cbAddress) const struct sockaddr* pAddress, __in ULONG cbAddress, __in DWORD dwStatusFlags );

Parameters:

  • pvContext [in]: A context value to associate with the registered adapter.

  • pAddress [in]: A sockaddr buffer that specifies the local address to use for the shared endpoint. Typically, this is a sockaddr_in structure for IPv4 addresses and a sockaddr_in6 structure for IPv6 addresses.
    If the sin_port or sin6_port member is specified as zero, the provider assigns a unique port number to the application from the ephemeral port range.

  • cbAddress [in]: The size, in bytes, of the pAddress buffer.

  • dwStatusFlags [in]: The state flag of the new adapter status. Could be a single state flag or a combination of the following:

New Adapter Status State Flag Return Value:

Value

Meaning

0

The adapter is up and running

ND_ADAPTER_FLAG_ADAPTER_IS_DOWN

The adapter is down.

ND_ADAPTER_FLAG_ADAPTER_RDMA_DISBALED

RoCE mode is disabled In the adapter

Nd2DeregisterForAdapterStatus

The Nd2DeregisterForAdapterStatus function must be called to deregister a registered adapter from the IND2ProviderControl. Failing to call the function will result in unreleased allocated memory.

Syntax:

Copy
Copied!
            

HRESULT Nd2DeregisterForAdapterStatus( __in IND2ProviderControl* pCtrl, __in void* pHandle )

Parameters:

  • IND2ProviderControl [in]: The IND2ProviderControl created by the IClassFactory::CreateInstance function.

  • pHandle [in]: The handle of the deregistered adapter.

Return value:

Return Code

Description

ND_SUCCESS

The operation succeeded.

Sample Code - Register:

Copy
Copied!
            

static void CALLBACK OnAdapterStatus( __in void* pvContext, __in_bcount(cbAddress) const struct sockaddr* pAddress, __in ULONG cbAddress, __in DWORD dwStatusFlags ){ //….. // printf("flags = %x\n", dwStatusFlags); //Print the new adapter status }     AutoRef<INetworkAddressInfo> aAddressInfo; // INetworkAddressInfo Object //…. //CreateNetworkAddressInfo with aAddressInfo //…. DWORD aContext; //Context for the specific adapter being registerd void* pvNd2RegisterForAdapterStatus = NULL; //AdapterStatus     hr = Nd2RegisterForAdapterStatus( aProviderControl, OnAdapterStatus, &aContext, aAddressInfo->GetAddr(), aAddressInfo->Length(), & pvNd2RegisterForAdapterStatus); RETURN_IF_FAILED(hr); //………………………………………………………………………….// //………………………………………………………………………………….// if (pvNd2RegisterForAdapterStatus) { hr = Nd2DeregisterForAdapterStatus(aProviderControl, pvNd2RegisterForAdapter- Status); } return hr;

Mellanox’s NIC device can be disabled at any time. When the device is disabled while NetworkDirect (ND) applications are running, the following will occur:

  • Any new request or operation that is executed by the ND application will fail explicitly

  • All pending overlapped requests will be canceled

  • All pending send requests will be completed with error (flush with error)

  • All RDMA resources will be released

  • The device will be marked as disabled

© Copyright 2023, NVIDIA. Last updated on May 23, 2023.