NdisMSetAttributesEx

NdisMSetAttributesEx

VOID
NdisMSetAttributesEx(
IN NDIS_HANDLE MiniportAdapterHandle,
IN NDIS_HANDLE MiniportAdapterContext,
IN UINT CheckForHangTimeInSeconds OPTIONAL,
IN ULONG AttributeFlags,
IN NDIS_INTERFACE_TYPE AdapterType
);

NdisMSetAttributesEx informs the NDIS library about significant features of the caller's NIC or virtual NIC during initialization.

Parameters

MiniportAdapterHandle

Specifies the handle input to MiniportInitialize.

MiniportAdapterContext

Specifies a handle for a resident context area allocated by MiniportInitialize.

CheckForHangTimeInSeconds

Specifies the interval in seconds at which NDIS should call the MiniportCheckForHang function, if any. Specifying zero for this parameter indicates that NDIS should call MiniportCheckForHang at NDIS's default two-second interval and that NDIS should call the MiniportReset function at the default four-second time-out interval for pending sends and requests that NDIS holds queued to the caller subsequently.

Specifying a value greater than two extends both the check-for-hang and time-out intervals. NDIS uses double the specified check-for-hang interval as its time-out interval for the caller.

AttributeFlags

Specifies a bitmask that can be set with one or more (ORed) of the following flags:

NDIS_ATTRIBUTE_BUS_MASTER

Set if the caller's NIC is a busmaster DMA device.

NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT

Set if NDIS should not attempt to time-out pending send packets that it holds queued to the caller. Intermediate drivers should set this flag, but NIC drivers should not.

NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT

Set if NDIS should not attempt to time-out pending query and set requests that it holds queued to the caller. Intermediate drivers should set this flag, but NIC drivers should not.

NDIS_ATTRIBUTE_INTERMEDIATE_DRIVER

Set if the caller is an intermediate driver.

NDIS_ATTRIBUTE_IGNORE_TOKEN_RING_ERRORS

Set if NDIS should not call a Token Ring NIC driver's MiniportReset function if Token Ring errors are indicated.

AdapterType

Specifies the I/O bus interface type of the caller's NIC, which usually is the type of I/O bus on which the NIC is connected, as one of the following:

NdisInterfaceInternal

Specifies a host-specific internal interface.

NdisInterfaceIsa

Specifies the ISA interface.

NdisInterfaceEisa

Specifies the extended ISA (EISA) interface.

NdisInterfaceMca

Specifies the MicroChannel architecture interface.

NdisInterfaceTurboChannel

Specifies the Turbo Channel interface.

NdisInterfacePci

Specifies the Peripheral Component Interconnect (PCI) interface.

NdisInterfacePcMcia

Specifies the Personal Computer Memory Card International Association (PCMCIA) interface.

This parameter is irrelevant for intermediate drivers shich should pass zero for this argument to NdisMSetAttributesEx.

Comments

A MiniportInitialize function must call NdisMSetAttributesEx (or NdisMSetAttributes) before calling any other NdisMRegisterXxx or NdisXxx function that depends on the information supplied to NdisMSetAttributesEx. For example, a NIC driver's call to NdisMAllocateMapRegisters will fail if MiniportInitialize has not yet called NdisMSetAttributesEx with the AttributeFlags set with NDIS_ATTRIBUTE_BUS_MASTER.

Intermediate drivers must call NdisMSetAttributesEx, rather than NdisMSetAttributes, and they must set the NDIS_ATTRIBUTE_INTERMEDIATE_DRIVER in the AttributeFlags. Setting this flag causes NDIS to treat an intermediate driver as a full-duplex miniport, which prevents rare but intermittant deadlocks from occurring in the intermediate driver. Consequently, every intermediate driver must be capable of handling concurrent sends and indications.

NIC drivers can call either of these functions from MiniportInitialize, but NdisMSetAttributes does not allow its caller to adjust the interval at which a NIC driver's MiniportCheckForHang and/or MiniportReset function(s) are called.

The value of CheckForHangTimeInSeconds determines the NDIS library's time-out interval on sends and requests it holds queued to the caller. By default, NDIS times out queued sends and requests at twice the check-for-hang interval, after which it calls the MiniportReset function, unless the driver sets AttributeFlags with NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT and NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT when it calls NdisMSetAttributesEx. Intermediate drivers should set these flags when calling NdisMSetAttributesEx because such a driver cannot determine or control when the underlying device driver will process sends and requests.

NIC drivers should not set the NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT and NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT flags, although NDIS will honor such a specification by a NIC driver. However, NIC drivers can adjust the time-out interval at which their MiniportReset functions are called by specifying an explicit CheckForHangTimeInSeconds. For example, a NIC driver that emulates Ethernet over a modem might not complete every packet within the default time-out interval of the NDIS library. Whenever a packet appeared to time out on such a NIC, NDIS would assume that the NIC was no longer operating correctly and call the driver's MiniportReset function. For the driver of such a NIC, calling NdisMSetAttributesEx with a CheckForHangTimeInSeconds set to something greater than two both prevents unnecessary resets and extends the interval at which its MiniportCheckForHang function, if any, is called to test the operational state of the NIC.

In general, a NIC driver must call NdisMSetAttributesEx before it calls any NdisXxx function that claims hardware resources in the registry for its NIC, because NDIS must have the AttributeFlags value before such a call is made and because the driver usually needs the memory at MiniportAdapterContext to store information for these calls. This restriction implies that a NIC driver's MiniportInitialize function cannot call the following NdisXxx before it calls NdisMSetAttributesEx:

·NdisMPciAssignResources

·NdisMAllocateMapRegisters and NdisMAllocateSharedMemory

·NdisMMapIoSpace and, consequently, the Ndis..RegisterXxx functions

·NdisMRegisterDmaChannel

·NdisMRegisterInterrupt

·NdisMRegisterIoPortRange and, consequently, the NdisRaw..PortXxx functions

However, before calling NdisMSetAttributesEx, any driver's MiniportInitialize function can call the Ndis..Configuration functions to retrieve configuration information installed in the registry. Before calling NdisMSetAttributesEx, a NIC driver can call the NdisImmediateXxx, such as NdisImmediateReadPciSlotInformation or NdisImmediateReadSharedMemory, as well as the NdisImmediate..PortXxx functions. MiniportInitialize also can call the bus-type-specific NdisReadXxx functions, such as NdisReadPciSlotInformation, as long as the installed registry entry for the driver's interface type matches the bus-type-specific NdisReadXxx MiniportInitialize calls.

The MiniportAdapterContext handle supplied to NdisMSetAttributesEx becomes an input parameter to all MiniportXxx functions that were registered, along with MiniportInitialize, in the call to NdisMRegisterMiniport or NdisIMRegisterLayeredMiniport. Usually, this handle is a pointer to resident memory, allocated by MiniportInitialize, in which the driver maintains NIC-specific runtime state.

Callers of NdisMSetAttributesEx run at IRQL PASSIVE_LEVEL.