xprtrdma: Refresh the documenting comment in frwr_ops.c

/* Lightweight memory registration using Fast Registration Work

 * Requests (FRWR).

 *

 * FRWR features ordered asynchronous registration and deregistration

 * of arbitrarily sized memory regions. This is the fastest and safest

 * FRWR features ordered asynchronous registration and invalidation

 * of arbitrarily-sized memory regions. This is the fastest and safest

 * but most complex memory registration mode.

 */

/* Normal operation

 *

 * A Memory Region is prepared for RDMA READ or WRITE using a FAST_REG

 * A Memory Region is prepared for RDMA Read or Write using a FAST_REG

 * Work Request (frwr_map). When the RDMA operation is finished, this

 * Memory Region is invalidated using a LOCAL_INV Work Request

 * (frwr_unmap_sync).

 * (frwr_unmap_async and frwr_unmap_sync).

 *

 * Typically these Work Requests are not signaled, and neither are RDMA

 * SEND Work Requests (with the exception of signaling occasionally to

 * prevent provider work queue overflows). This greatly reduces HCA

 * Typically FAST_REG Work Requests are not signaled, and neither are

 * RDMA Send Work Requests (with the exception of signaling occasionally

 * to prevent provider work queue overflows). This greatly reduces HCA

 * interrupt workload.

 *

 * As an optimization, frwr_unmap marks MRs INVALID before the

 * LOCAL_INV WR is posted. If posting succeeds, the MR is placed on

 * rb_mrs immediately so that no work (like managing a linked list

 * under a spinlock) is needed in the completion upcall.

 *

 * But this means that frwr_map() can occasionally encounter an MR

 * that is INVALID but the LOCAL_INV WR has not completed. Work Queue

 * ordering prevents a subsequent FAST_REG WR from executing against

 * that MR while it is still being invalidated.

 */

/* Transport recovery

 *

 * ->op_map and the transport connect worker cannot run at the same

 * time, but ->op_unmap can fire while the transport connect worker

 * is running. Thus MR recovery is handled in ->op_map, to guarantee

 * that recovered MRs are owned by a sending RPC, and not one where

 * ->op_unmap could fire at the same time transport reconnect is

 * being done.

 *

 * When the underlying transport disconnects, MRs are left in one of

 * four states:

 *

 * INVALID:	The MR was not in use before the QP entered ERROR state.

 *

 * VALID:	The MR was registered before the QP entered ERROR state.

 *

 * FLUSHED_FR:	The MR was being registered when the QP entered ERROR

 *		state, and the pending WR was flushed.

 *

 * FLUSHED_LI:	The MR was being invalidated when the QP entered ERROR

 *		state, and the pending WR was flushed.

 *

 * When frwr_map encounters FLUSHED and VALID MRs, they are recovered

 * with ib_dereg_mr and then are re-initialized. Because MR recovery

 * allocates fresh resources, it is deferred to a workqueue, and the

 * recovered MRs are placed back on the rb_mrs list when recovery is

 * complete. frwr_map allocates another MR for the current RPC while

 * the broken MR is reset.

 *

 * To ensure that frwr_map doesn't encounter an MR that is marked

 * INVALID but that is about to be flushed due to a previous transport

 * disconnect, the transport connect worker attempts to drain all

 * pending send queue WRs before the transport is reconnected.

 * frwr_map and frwr_unmap_* cannot run at the same time the transport

 * connect worker is running. The connect worker holds the transport

 * send lock, just as ->send_request does. This prevents frwr_map and

 * the connect worker from running concurrently. When a connection is

 * closed, the Receive completion queue is drained before the allowing

 * the connect worker to get control. This prevents frwr_unmap and the

 * connect worker from running concurrently.

 *

 * When the underlying transport disconnects, MRs that are in flight

 * are flushed and are likely unusable. Thus all flushed MRs are

 * destroyed. New MRs are created on demand.

 */

#include <linux/sunrpc/rpc_rdma.h>