NAME¶

RDS zerocopy - Interface for RDMA over RDS

DESCRIPTION¶

This manual page describes the zerocopy interface of RDS, which was added in RDSv3. For a description of the basic RDS interface, please refer to rds(7).

The principal mode of operation for RDS zerocopy is like this: one participant (the client) wishes to initiate a direct transfer to or from some area of memory in its process address space. This memory does not have to be aligned.

The client obtains a handle for this region of memory, and passes it to the other participant (the server). This is called the RDMA cookie. To the application, the cookie is an opaque 64bit data type.

The client sends this handle to the server application, along with other details of the RDMA request (such as which data to transfer to that memory area). Throughout the following discussion, we will refer to this message as the RDMA request.

The server uses this RDMA cookie to initiate the requested RDMA transfer. The RDMA transfer is combined atomically with a normal RDS message, which is delivered to the client. This message is called the RDMA ACK throughout the following. Atomic in this context means that either both the RDMA succeeds and the RDMA ACK is delivered, or neither succeeds.

Thus, when the client receives the RDMA ACK, it knows that the RDMA has completed successfully. It can then release the RDMA cookie for this memory region, if it wishes to.

RDMA operations are not reliable, in the sense that unlike normal RDS messages, RDS RDMA operations may fail, and get dropped.

INTERFACE¶

The interface is currently based on control messages (ancillary data) sent or received via the sendmsg(2) and recvmsg(2) system calls. Optionally, an older interface can be used that is based on the setsockopt(2) system call. However, we recommend using control messages, as this reduces the number of system calls required.

RDMA MACROS AND TYPES¶

RDMA cookie

typedef u_int64_t       rds_rdma_cookie_t

This encapsulates a memory location in the client process. In the current implementation, it contains the R_Key of the remote memory region, and the offset into it (so that the application does not have to worry about alignment.

The RDMA cookie is used in several struct types described below. The RDS_CMSG_RDMA_DEST control message contains a rds_rdma_cookie_t all by itself as payload.

Mapping arguments

The following data type is used with RDS_CMSG_RDMA_MAP control messages and with the RDS_GET_MR socket option:

struct rds_iovec {


        u_int64_t       addr;


        u_int64_t       bytes;
};
struct rds_get_mr_args {


        struct rds_iovec vec;


        u_int64_t       cookie_addr;


        uint64_t        flags;
};

The cookie_addr specifies a memory location where to store the RDMA cookie.

The flags value is a bitwise OR of any of the following flags:

RDMA Operation

RDMA operations are initiated by the server using the RDS_CMSG_RDMA_ARGS control message, which takes the following data as payload:

struct rds_rdma_args {


        rds_rdma_cookie_t cookie;


        struct rds_iovec remote_vec;


        u_int64_t       local_vec_addr;


        u_int64_t       nr_local;


        u_int64_t       flags;


        u_int32_t       user_token;
};

The cookie argument contains the RDMA cookie received from the client. The local memory is given via an array of rds_iovecs. The array address is given in local_vec_addr, and its number of elements is given in nr_local.

The struct member remote_vec specifies a location relative to the memory area identified by the cookie: remote_vec.addr is an offset into that region, and remote_vec.bytes is the length of the memory window to copy to/from. This length must match the size of the local memory area, i.e. the sum of bytes in all members of the local iovec.

The flags field contains the bitwise OR of any of the following flags:

The user_token can be used to pass an application specific identifier to the kernel. This token is returned to the application when a status notification is generated (see the following section).

RDMA Notification

The RDS kernel code is able to notify the server application when an RDMA operation completes. These notifications are delivered via RDS_CMSG_RDMA_STATUS control messages.

By default, no notifications are generated. There are two ways an application can request them. On one hand, status notifications can be enabled on a per-operation basis by setting the RDS_RDMA_NOTIFY_ME flag in the RDMA arguments. On the other hand, the application can request notifications for all RDMA operations that fail by setting the RDS_RECVERR socket option (see below). In both cases, the format of the notification is the same; and at most one notification will be sent per completed operation.

The message format is this:

struct rds_rdma_notify {


        u_int32_t       user_token;


        int32_t         status;
};

The user_token field contains the value previously given to the kernel in the RDS_CMSG_RDMA_ARGS control message. The status field contains a status value, with 0 indicating success, and non-zero indicating an error.

The following status codes are currently defined:

RDMA setsockopt arguments

When using the RDS_GET_MR socket option to register a memory range, the application passes a pointer to a struct rds_get_mr_args variable, described above.

The RDS_FREE_MR call takes an argument of type struct rds_free_mr_args:

struct rds_free_mr_args {


        rds_rdma_cookie_t cookie;


        u_int64_t       flags;
};

cookie specifies the RDMA cookie to be released. RDMA access to the memory range will usually not be invoked instantly, because the operation is rather costly. However, if the flags argument contains RDS_RDMA_INVALIDATE, RDS will invalidate the indicated mapping immediately, as described in section Mapping arguments above.

If the cookie argument is 0, and RDS_RDMA_INVALIDATE is set, RDS will invalidate old memory mappings on all devices.

ERRORS¶

In addition to the usual error codes returned by sendmsg, recvmsg and setsockopt, RDS returns the following error codes:

EAGAIN

RDS was unable to map a memory range because the limit was exceeded (returned by RDS_CMSG_RDMA_MAP and RDS_GET_MR).

EINVAL

When sending a message, there were were conflicting control messages (e.g. two RDMA_MAP messages, or a RDMA_MAP and a RDMA_DEST message).

In a RDS_CMSG_RDMA_MAP or RDS_GET_MR operation, the application specified memory range greater than the maximum size supported.

When setting up an RDMA operation with RDS_CMSG_RDMA_ARGS, the size of the local memory (given in the rds_iovec) did not match the size of the remote memory range.

EBUSY

RDS was unable to obtain a DMA mapping for the indicated memory.

LIMITS¶

Currently, the following limits apply

• The maximum size of a zerocopy transfer is 1MB. This can be adjusted via the fmr_message_size module parameter.
• The maximum number of memory ranges that can be mapped is limited to 2048 at the moment. This can be adjusted via the fmr_pool_size module parameter. However, the actual limit imposed by the hardware may in fact be lower.

AUTHORS¶

RDS was written and is Copyright (C) 2007-2008 by Oracle, Inc.