Edit

NdisScheduleWorkItem function (ndis.h)

  • Article

Note   NDIS 5. x has been deprecated and is superseded by NDIS 6. x. For new NDIS driver development, see Network Drivers Starting with Windows Vista. For information about porting NDIS 5. x drivers to NDIS 6. x, see Porting NDIS 5.x Drivers to NDIS 6.0.

NdisScheduleWorkItem inserts a given work item into a queue from which a system worker thread removes the item and gives control to the callback function that the driver previously supplied to NdisInitializeWorkItem.

Syntax

NDIS_STATUS NdisScheduleWorkItem(
  [in] __drv_aliasesMem PNDIS_WORK_ITEM WorkItem
);

Parameters

[in] WorkItem

Pointer to the work item that was set up by a preceding call to NdisInitializeWorkItem.

Return value

NdisScheduleWorkItem always succeeds and therefore always returns NDIS_STATUS_SUCCESS.

Remarks

A call to NdisScheduleWorkItem allows an NDIS driver to defer some driver-determined operation that could or should be done at a lower IRQL than the raised IRQL at which it is currently running to its worker-thread callback function.

The driver's callback is run within a system thread context at IRQL = PASSIVE_LEVEL later. This caller-supplied function is responsible for reclaiming the storage that the driver allocated for WorkItem. For example, if the driver called NdisAllocateMemoryWithTag to provide a context area to NdisInitializeWorkItem, its callback function should make the reciprocal call to NdisFreeMemory with WorkItem before it returns control.

A driver must not wait for its callback routine to complete an operation if it is already holding one synchronization object and might attempt to acquire another. For example, a NDIS driver should release any currently held spin lock(s), and so forth before it calls NdisScheduleWorkItem. A highest level NDIS protocol driver also must release any currently held semaphores, mutexes, resource variables, and so forth before it calls NdisScheduleWorkItem. Releasing all synchronization resources before queuing a synchronous worker-thread operation prevents deadlocks.

A serialized miniport driver should never attempt to queue a worker-thread callback routine, because there is no way for such a driver to synchronize access to its NIC context area(s) with a worker-thread callback. Consequently, such a serialized NDIS driver cannot share anything in its per-adapter context area with a worker-thread callback function without causing intermittent system crashes.

  • Target platform: Universal
  • Version: Not supported for NDIS 6.0 drivers in Windows Vista. Use NdisQueueIoWorkIteminstead. Supported for NDIS 5.1 drivers in Windows Vista and Windows XP.

Requirements

Requirement Value
Header ndis.h (include Ndis.h)
IRQL IRQL <= DISPATCH_LEVEL

See also