252 lines
8.7 KiB
C
252 lines
8.7 KiB
C
/*++
|
||
|
||
Copyright (c) 1994 Microsoft Corporation
|
||
|
||
Module Name:
|
||
|
||
rxworkq.h
|
||
|
||
Abstract:
|
||
|
||
This module defines the data structures required to implement the dispatching
|
||
mechanism in RDBSS for use by RDBSS as well as all the mini redirectors.
|
||
|
||
Author:
|
||
|
||
Balan Sethu Raman [SethuR] 20-Mar-96
|
||
|
||
--*/
|
||
|
||
#ifndef _RXWORKQ_H_
|
||
#define _RXWORKQ_H_
|
||
|
||
//
|
||
// The worker thread routine prototype definition.
|
||
//
|
||
|
||
typedef
|
||
VOID
|
||
(NTAPI *PRX_WORKERTHREAD_ROUTINE) (
|
||
IN PVOID Context
|
||
);
|
||
|
||
//
|
||
// The RDBSS needs to keep track of the work items on a per device object basis.
|
||
// This enables the race conditions associated with loading/unloading as well as
|
||
// a mechanism for preventing a single mini redirector from unfairly hogging all
|
||
// the resources.
|
||
//
|
||
|
||
#ifdef __cplusplus
|
||
typedef struct _RX_WORK_QUEUE_ITEM_ : public WORK_QUEUE_ITEM {
|
||
// the work queue item as defined in NTOS
|
||
#else // !__cplusplus
|
||
typedef struct _RX_WORK_QUEUE_ITEM_ {
|
||
WORK_QUEUE_ITEM; // the work queue item as defined in NTOS
|
||
#endif // __cplusplus
|
||
|
||
PRDBSS_DEVICE_OBJECT pDeviceObject;
|
||
} RX_WORK_QUEUE_ITEM, *PRX_WORK_QUEUE_ITEM;
|
||
|
||
//
|
||
// There are certain scenarios in which dispatching of work items is inevitable.
|
||
// In such instance the WORK_QUEUE_ITEM is allocated as part of another data
|
||
// structure to avoid frequent allocation/freeing. In other scenarios where
|
||
// dispatching is rare it pays to avoid the allocation of the memory till it
|
||
// is rquired. The RDBSS work queue implementations provide for both these
|
||
// scenarios in the form of dispatching and posting work queue requests. In
|
||
// the case of dispatching no memory for the WORK_QUEUE_ITEM need be allocated
|
||
// by the caller while for posting the memory for WORK_QUEUE_ITEM needs to be
|
||
// allocated by the caller.
|
||
//
|
||
|
||
typedef struct _RX_WORK_DISPATCH_ITEM_ {
|
||
RX_WORK_QUEUE_ITEM WorkQueueItem;
|
||
PRX_WORKERTHREAD_ROUTINE DispatchRoutine;
|
||
PVOID DispatchRoutineParameter;
|
||
} RX_WORK_DISPATCH_ITEM, *PRX_WORK_DISPATCH_ITEM;
|
||
|
||
//
|
||
// The work queues typically come up in a active state and continue till either
|
||
// a non recoverable situation is encountered ( lack of system resources ) when
|
||
// it transitions to the Inactive state. When a rundown is initiated it transitions
|
||
// to the rundown in progress state.
|
||
//
|
||
|
||
typedef enum _RX_WORK_QUEUE_STATE_ {
|
||
RxWorkQueueActive,
|
||
RxWorkQueueInactive,
|
||
RxWorkQueueRundownInProgress
|
||
} RX_WORK_QUEUE_STATE, *PRX_WORK_QUEUE_STATE;
|
||
|
||
//
|
||
// The rundown of work queues is not complete when the threads have been spun down.
|
||
// The termination of the threads needs to be ensured before the data structures
|
||
// can be torn down. The work queue implementation follows a protocol in which
|
||
// each of the threads being spundown stashes a reference to the thread object
|
||
// in the rundown context. The rundown issuing thread ( which does not belong to
|
||
// the work queue ) waits for the completion of all the threads spundown before
|
||
// tearing down the data structures.
|
||
//
|
||
|
||
typedef struct _RX_WORK_QUEUE_RUNDOWN_CONTEXT_ {
|
||
KEVENT RundownCompletionEvent;
|
||
LONG NumberOfThreadsSpunDown;
|
||
PETHREAD *ThreadPointers;
|
||
} RX_WORK_QUEUE_RUNDOWN_CONTEXT, *PRX_WORK_QUEUE_RUNDOWN_CONTEXT;
|
||
|
||
//
|
||
// The work queue implementation is built around a KQUEUE implementation. The
|
||
// additional support involves the regulation of number of threads that are
|
||
// actively waiting for the work items. Each work queue data structure is
|
||
// allocated in nonpaged pool and has its own synchronization mechanism ( spinlock).
|
||
//
|
||
// In addition to the bookkeeing information, i.e., state, type etc. it also includes
|
||
// statistics that are gathered over the lifetime of the queue. This will
|
||
// provide valuable information in tuning a work queue instance. The number of items
|
||
// that have been processed , the number of items that have to be processed and
|
||
// the cumulative queue length is recorded. The cumulative queue length is the
|
||
// intersiting metric, it is the sum of the number of items awaiting to be processed
|
||
// each time an additional work item was queued. The cumulative queue length
|
||
// divided by the sum of the total number of items processed and the anumber of
|
||
// items to be processed gives an indication of the average length of the
|
||
// queue. A value much greater than one signifies that the minimum number of
|
||
// worker threads associated with the work queue can be increased. A value much
|
||
// less than one signifies that the maximum number of work threads associated
|
||
// with the queue can be decreased.
|
||
//
|
||
|
||
typedef struct _RX_WORK_QUEUE_ {
|
||
USHORT State;
|
||
BOOLEAN SpinUpRequestPending;
|
||
UCHAR Type;
|
||
|
||
KSPIN_LOCK SpinLock;
|
||
|
||
PRX_WORK_QUEUE_RUNDOWN_CONTEXT pRundownContext;
|
||
|
||
LONG NumberOfWorkItemsDispatched;
|
||
LONG NumberOfWorkItemsToBeDispatched;
|
||
LONG CumulativeQueueLength;
|
||
|
||
LONG NumberOfSpinUpRequests;
|
||
LONG MaximumNumberOfWorkerThreads;
|
||
LONG MinimumNumberOfWorkerThreads;
|
||
LONG NumberOfActiveWorkerThreads;
|
||
LONG NumberOfIdleWorkerThreads;
|
||
LONG NumberOfFailedSpinUpRequests;
|
||
LONG WorkQueueItemForSpinUpWorkerThreadInUse;
|
||
|
||
RX_WORK_QUEUE_ITEM WorkQueueItemForTearDownWorkQueue;
|
||
RX_WORK_QUEUE_ITEM WorkQueueItemForSpinUpWorkerThread;
|
||
RX_WORK_QUEUE_ITEM WorkQueueItemForSpinDownWorkerThread;
|
||
|
||
KQUEUE Queue;
|
||
|
||
// The next field is for debugging purposes and will be removed from the
|
||
// FREE build.
|
||
PETHREAD *ThreadPointers;
|
||
|
||
} RX_WORK_QUEUE, *PRX_WORK_QUEUE;
|
||
|
||
//
|
||
// The dispatching mechanism in RDBSS provides for multiple levels of work queues
|
||
// on a per processor basis. There are three levels of work queues currently
|
||
// supported, Critical,Delayed and HyperCritical. The distinction between Critical
|
||
// and delayed is one of priority where as HyperCritical iss different from the
|
||
// other two in that the routines should not block, i.e., wait for any resource.
|
||
// This requirement cannot be enforced hence the effectiveness of the dispatching
|
||
// mechanism relies on the implicit cooperation of the clients.
|
||
//
|
||
|
||
typedef struct _RX_WORK_QUEUE_DISPATCHER_ {
|
||
RX_WORK_QUEUE WorkQueue[MaximumWorkQueue];
|
||
} RX_WORK_QUEUE_DISPATCHER, *PRX_WORK_QUEUE_DISPATCHER;
|
||
|
||
//
|
||
// The dispatcher typically come up in a active state and continue till either
|
||
// a non recoverable situation is encountered ( lack of system resources ) when
|
||
// it transitions to the Inactive state. When a rundown is initiated it transitions
|
||
// to the rundown in progress state.
|
||
//
|
||
|
||
typedef enum _RX_DISPATCHER_STATE_ {
|
||
RxDispatcherActive,
|
||
RxDispatcherInactive
|
||
} RX_DISPATCHER_STATE, *PRX_DISPATCHER_STATE;
|
||
|
||
|
||
//
|
||
// The RDBSS dispatching mechanism on any machine is an array of the dispatchers
|
||
// associated with each processor. When a work queue item is queued a best effort
|
||
// is made to contain the work emanating from a processor onto the same processor.
|
||
// This ensures that processor affinities setup by the NT dispatcher are not
|
||
// destroyed by the RDBSS dispatching mechanism as this could lead to excessive
|
||
// sloshing. When the work needs to be moved there are two metrics that will be
|
||
// useful in making the decision, teh amount of delay that will be experienced
|
||
// by the work item in the current queue and the effort involved in moving the
|
||
// work item to the other queue. It is very easy to quantify the former but very
|
||
// difficult to quantify the later.
|
||
//
|
||
|
||
typedef struct _RX_DISPATCHER_ {
|
||
LONG NumberOfProcessors;
|
||
PEPROCESS OwnerProcess;
|
||
PRX_WORK_QUEUE_DISPATCHER pWorkQueueDispatcher;
|
||
|
||
RX_DISPATCHER_STATE State;
|
||
|
||
LIST_ENTRY SpinUpRequests;
|
||
KSPIN_LOCK SpinUpRequestsLock;
|
||
KEVENT SpinUpRequestsEvent;
|
||
KEVENT SpinUpRequestsTearDownEvent;
|
||
} RX_DISPATCHER, *PRX_DISPATCHER;
|
||
|
||
//
|
||
// The function prototypes used for dispatching/posting work queue items
|
||
//
|
||
|
||
extern NTSTATUS
|
||
NTAPI
|
||
RxPostToWorkerThread (
|
||
IN PRDBSS_DEVICE_OBJECT pMRxDeviceObject,
|
||
IN WORK_QUEUE_TYPE WorkQueueType,
|
||
IN PRX_WORK_QUEUE_ITEM pWorkQueueItem,
|
||
IN PRX_WORKERTHREAD_ROUTINE Routine,
|
||
IN PVOID pContext
|
||
);
|
||
|
||
extern NTSTATUS
|
||
NTAPI
|
||
RxDispatchToWorkerThread(
|
||
IN PRDBSS_DEVICE_OBJECT pMRxDeviceObject,
|
||
IN WORK_QUEUE_TYPE WorkQueueType,
|
||
IN PRX_WORKERTHREAD_ROUTINE Routine,
|
||
IN PVOID pContext);
|
||
|
||
extern BOOLEAN //should only be called from raised IRQL
|
||
NTAPI
|
||
RxIsWorkItemQueued(
|
||
IN OUT PWORK_QUEUE_ITEM WorkItem
|
||
);
|
||
|
||
//
|
||
// The routines for initializing/tearing down the dispatching mechanism
|
||
//
|
||
|
||
extern NTSTATUS
|
||
RxInitializeDispatcher();
|
||
|
||
extern NTSTATUS
|
||
RxTearDownDispatcher();
|
||
|
||
extern NTSTATUS
|
||
RxInitializeMRxDispatcher(
|
||
IN OUT PRDBSS_DEVICE_OBJECT pMRxDeviceObject);
|
||
|
||
extern NTSTATUS
|
||
RxSpinDownMRxDispatcher(
|
||
IN OUT PRDBSS_DEVICE_OBJECT pMRxDeviceObject);
|
||
|
||
#endif _RXWORKQ_H_
|
||
|