RX_CONTEXT and IRP Management

The RX_CONTEXT structure is one of the fundamental data structures used by RDBSS and network mini-redirectors to manage an I/O request packet (IRP). An RX_CONTEXT structure describes an IRP while it is being processed and contains state information that allows global resources to be released as the IRP is completed. The RX_CONTEXT data structure encapsulates an IRP for use by RDBSS, network mini-redirectors, and the file system. An RX_CONTEXT structure includes a pointer to a single IRP and all of the context required to process the IRP.

An RX_CONTEXT structure is sometimes referred to as an IRP Context or RxContext in the Windows Driver Kit (WDK) header files and other resources used for developing network mini-redirector drivers.

The RX_CONTEXT is a data structure to which additional information provided by the various network mini redirectors is attached. From a design standpoint, this additional information can be handled in one of several ways:

• Allow for context pointers to be defined as part of RX_CONTEXT, which network mini-redirectors use to store away their information. This implies that every time an RX_CONTEXT structure is allocated and destroyed, the network mini-redirector driver must perform a separate associated allocation or destruction of the memory block that contains the additional network mini-redirector information. Since RX_CONTEXT structures are created and destroyed in large numbers, this is not an acceptable solution from a performance standpoint.

• Another approach consists of over allocating the size of each RX_CONTEXT structure by a pre-specified amount for each network mini redirector, which is then reserved for use by the mini redirector. Such an approach avoids the additional allocation and destruction but complicates the RX_CONTEXT management code in RDBSS.

• The third approach consists of allocating a pre-specified area, which is the same for all network mini redirectors as part of each RX_CONTEXT. This is an unformatted area on top of which any desired structure can be imposed by the various network mini redirectors. Such an approach overcomes the disadvantages associated with previous approaches. This is the approach currently implemented in RDBSS.

The third approach is the scheme used by RDBSS. Consequently, developers of network mini-redirector drivers should try and define the associated private context to fit into this pre-specified area defined in the RX_CONTEXT data structure. Network mini-redirector drivers that violate this rule will incur a significant performance penalty.

Many RDBSS routines and routines exported by a network mini-redirector make reference to RX_CONTEXT structures in either the initiating thread or in some other thread used by the routine. Thus, the RX_CONTEXT structures are reference counted to manage their use for asynchronous operations. When the reference count goes to zero, the RX_CONTEXT structure can be finalized and released on the last dereference operation.

RDBSS provides a number of routines that are used to manipulate an RX_CONTEXT structure and the associated IRP. These routines are used to allocate, initialize, and delete an RX_CONTEXT structure. These routines are also used to complete the IRP associated with an RX_CONTEXT and set up a cancel routine for an RX_CONTEXT.

The following routines manipulate RX_CONTEXT structures:

Routine	Description
RxCompleteRequest	This routine is used to complete an IRP associated with an RX_CONTEXT structure. This routine is used internally by RDBSS and should not be used by network mini-redirectors.
RxCompleteRequest_Real	This routine is used to complete an IRP associated with an RX_CONTEXT structure. This routine is used internally by RDBSS and should not be used by network mini-redirectors.
RxCreateRxContext	This routine allocates a new RX_CONTEXT structure and initializes the data structure.
RxDereferenceAndDeleteRxContext_Real	This routine dereferences an RX_CONTEXT structure, and if the reference count goes to zero, then it deallocates and removes the specified RX_CONTEXT structure from the RDBSS in-memory data structures.
RxInitializeContext	This routine initializes a newly allocated RX_CONTEXT structure.
RxPrepareContextForReuse	This routine prepares an RX_CONTEXT structure for reuse by resetting all operation-specific allocations and acquisitions previously made. The parameters obtained from the IRP are not modified. This routine is used internally by RDBSS and should not be used by network mini-redirectors.
RxResumeBlockedOperations_Serially	This routine wakes up the next waiting thread, if any, on the serialized blocking I/O queue.
RxSetMinirdrCancelRoutine	The routine sets up a network mini-redirector cancel routine for an RX_CONTEXT structure.
__RxSynchronizeBlockingOperations	This routine is used to synchronize blocking I/O to the same work queue. This routine is used internally by RDBSS to synchronize named pipe operations. This routine may be used by a network mini-redirector to synchronize operations on a separate queue that is maintained by the network mini-redirector. The routine is only available on Windows Server 2003.
__RxSynchronizeBlockingOperationsMaybeDroppingFcbLock	This routine is used to synchronize blocking I/O to the same work queue. This routine is used internally by RDBSS to synchronize named pipe operations. This routine may be used by a network mini-redirector to synchronize operations on a separate queue that is maintained by the network mini-redirector. The routine is only available on Windows XP and Windows 2000.

The following macros are defined in the rxcontx.h header file that call the routines listed in the previous table. These macros are normally used instead of calling these routines directly.

Macro	Description
RxSynchronizeBlockingOperations(RXCONTEXT,FCB,IOQUEUE)	This macro synchronizes blocking I/O requests to the same work queue. On Windows Server 2003, this macro calls the __RxSynchronizeBlockingOperations routine with the DropFcbLock parameter set to FALSE. On Windows XP and Windows 2000, this macro calls the __RxSynchronizeBlockingOperationsMaybeDroppingFcbLock routine with the DropFcbLock parameter set to FALSE.
RxSynchronizeBlockingOperations(RXCONTEXT,FCB,IOQUEUE)	This macro synchronizes blocking I/O requests to the same work queue. On Windows Server 2003, this macro calls the __RxSynchronizeBlockingOperations routine with the DropFcbLock parameter set to TRUE. On Windows XP and Windows 2000, this macro calls the __RxSynchronizeBlockingOperationsMaybeDroppingFcbLock routine with the DropFcbLock parameter set to TRUE.