WSPRegisterRdmaMemory function

Article
06/19/2017

WSPRegisterRdmaMemory registers an RDMA buffer that can be used as either the target buffer in a WSPRdmaWrite call or the source buffer in a WSPRdmaRead call.

Syntax

int WSPRegisterRdmaMemory(
  _In_    SOCKET  s,
  _In_    PVOID   lpBuffer,
  _In_    DWORD   dwBufferLength,
  _In_    DWORD   dwFlags,
  _Out_   LPVOID  lpRdmaBufferDescriptor,
  _Inout_ LPDWORD lpdwDescriptorLength,
  _Out_   LPINT   lpErrno
);

Parameters

s [in]
Descriptor that identifies a connected socket.
lpBuffer [in]
Pointer to the RDMA buffer to register.
dwBufferLength [in]
Size, in bytes, of the RDMA buffer at lpBuffer.
dwFlags [in]
Set of flags that specify supplementary information about the RDMA buffer and registration options.
lpRdmaBufferDescriptor [out]
Pointer to a memory block that receives a descriptor that identifies the RDMA buffer at lpBuffer.
lpdwDescriptorLength [in, out]
Pointer to a variable that contains the size, in bytes, of the memory block at lpRdmaBufferDescriptor. The switch allocates this memory block to receive the RDMA-buffer descriptor and specifies the initial size of the memory block. The SAN service provider returns either the size of the descriptor that it actually stored or the size that it requires.
lpErrno [out]
Pointer to a variable that receives the error code.

Return value

Returns zero if successful; otherwise, returns SOCKET_ERROR and, at lpErrno, one of the following error codes:

Return code	Description
WSANOBUFS	No memory resources available.
WSAEFAULT	lpBuffer is not contained completely within a valid part of the user address space, or the size of lpRdmaDescriptorBuffer is insufficient to contain the descriptor. Note that if lpRdmaDescriptorBuffer is insufficient to contain the descriptor, the SAN service provider must store the required size at lpdwDescriptorLength. If lpBuffer is not contained completely within a valid part of the user address space, the SAN service provider must not overwrite the initial value that the switch supplied.
WSAEINVAL	Invalid flags specified.
WSAENOTCONN	Socket is not connected (connection-oriented sockets only).

Remarks

The Windows Sockets switch calls WSPRegisterRdmaMemory to register an RDMA buffer that a specific socket and the remote peer connected to that socket can access. The returned descriptor for the RDMA buffer is valid for RDMA data transfer operations that the remote peer initiates in the context of the peer's connection to the socket.

The switch can call the WSPRegisterRdmaMemory function more than once to register the same RDMA buffer for use by any number of sockets. When this occurs, a SAN service provider is not required to return a different descriptor for the RDMA buffer. However, the SAN service provider should maintain an internal reference count of the number of registered instances of that RDMA buffer. Each time that a SAN service provider's WSPDeregisterRdmaMemory function is called, it should decrement this internal reference count. Only the final WSPDeregisterRdmaMemory call, which decrements the internal reference count to zero, releases all resources that the SAN service provider consumed to register the RDMA buffer.

The switch specifies how the registered memory in dwFlags is to be accessed by specifying one of the following flags:

MEM_READ
Read access
MEM_WRITE
Write access
MEM_READWRITE
Both read and write access

The SAN service provider must obtain memory that can be accessed as specified in dwFlags.

The local switch requires that the memory it registers with a WSPRegisterRdmaMemory call has write access if the switch at the remote peer connection subsequently uses this memory as the target in a call to the SAN service provider's WSPRdmaWrite function. Read access is required for memory that is used as the source in a WSPRdmaRead call.

If the switch did not specify a sufficient size at lpdwDescriptorLength for the memory block at lpRdmaBufferDescriptor, the SAN service provider must return the WSAEFAULT error code at lpErrno and store the required size at lpdwDescriptorLength. The switch allocates the memory block at lpRdmaBufferDescriptor to receive the descriptor that identifies the memory buffer.

A SAN service provider must prevent unauthorized access to an RDMA buffer. Only the connection (process) on which that RDMA buffer is registered can have access, as either the process that called WSPRegisterRdmaMemory to register memory, or the process for the remote peer connection to the socket.

Memory that supports both local and remote access must be accessible only when registered and while the connection is established. A SAN service provider must ensure that it does not inadvertently make such memory accessible to other processes running on the same computer, on the remote peer's computer, or on other computers on the SAN. Memory registered only for remote read access must not be available for remote write access. Memory registered only for remote write access must not be available for remote read access.

Requirements

Target platform	Desktop
Version	Requires Windows Sockets version 2.2.
Header	Ws2san.h (include Ws2san.h)

Share via