NdisMRegisterDmaChannel

NdisMRegisterDmaChannel

NDIS_STATUS
   NdisMRegisterDmaChannel(
       OUT PNDIS_HANDLE MiniportDmaHandle,
       IN NDIS_HANDLE MiniportAdapterHandle,
       IN UINT DmaChannel,
       IN BOOLEAN Dma32BitAddresses,
       IN PNDIS_DMA_DESCRIPTION DmaDescription,
       IN ULONG MaximumLength
       );

NdisMRegisterDmaChannel claims a system DMA controller channel during initialization for DMA operations on a slave NIC or on an ISA busmaster NIC.

Parameters

MiniportDmaHandle

Points to a caller-supplied variable in which this function returns a handle the miniport uses in subsequent calls to the NdisMXxx system DMA functions.

MiniportAdapterHandle

Specifies the handle input to MiniportInitialize.

DmaChannel

Ignored. Set the DMA channel, if any, at DmaDescription.

Dma32BitAddresses

Specifies TRUE if the NIC has 32 address lines.

DmaDescription

Points to an NDIS_DMA_DESCRIPTION structure filled in by the caller. This structure is defined as follows:

typedef struct _NDIS_DMA_DESCRIPTION {

BOOLEAN DemandMode;

BOOLEAN AutoInitialize;

BOOLEAN DmaChannelSpecified;

DMA_WIDTH DmaWidth;

DMA_SPEED DmaSpeed;

ULONG DmaPort;

ULONG DmaChannel;

} NDIS_DMA_DESCRIPTION, *PNDIS_DMA_DESCRIPTION;

The driver should initialize this structure with zeros before filling in the following members:

DemandMode

Specifies TRUE if the slave NIC uses the system DMA controller’s demand mode.

AutoInitialize

Specifies TRUE if the slave NIC uses the system DMA controller’s autoinitialize mode.

DmaChannelSpecified

Specifies TRUE if DmaChannel is set to the bus-relative value of the system DMA controller channel used by the NIC.

DmaWidth

Specifies the transfer width for DMA operations, one of Width8Bits, Width16Bits, or Width32Bits.

DmaSpeed

Specifies one of Compatible, TypeA, TypeB, or TypeC.

DmaPort

Specifies the bus-relative port number if the NIC is on an MCA bus; otherwise, specifies zero.

DmaChannel

Specifies the bus-relative number of the system DMA controller channel used by the NIC.

MaximumLength

Specifies the maximum number of bytes the NIC can transfer in a single DMA operation. If the NIC has unlimited transfer capacity,set this parameter to -1.

Return Value

NdisMRegisterDmaChannel can return one of the following status values:

NDIS_STATUS_SUCCESS

NDIS claimed the specified DMA channel in the registry for the caller’s NIC and set up necessary resources for subsequentl DMA operations by the miniport.

NDIS_STATUS_RESOURCE_CONFLICT

An attempt to claim the DMA channel in the registry has failed, possibly because another driver has already claimed that channel for its device. NdisMRegisterDmaChannel logs an error if this occurs.

NDIS_STATUS_RESOURCES

NDIS could not allocate the system resources it needs to support DMA operations by this NIC driver.

NDIS_STATUS_FAILURE

Either the bus type or bus number is out of range or the driver declared its NIC a busmaster on an I/O bus other than ISA.

Comments

A driver of a slave-DMA NIC must call NdisMRegisterDmaChannel from its MiniportInitialize function to reserve system resources for subsequent DMA operations and to claim them in the registry.

The driver of an ISA busmaster NIC also must call NdisMRegisterDmaChannel from MiniportInitialize to claim a system DMA controller channel for its NIC in the registry.

MiniportInitialize must call NdisMSetAttributes or NdisMSetAttributesEx before calling NdisMRegisterDmaChannel.

MiniportInitialize obtained the bus-relative values passed to NdisMRegisterDmaChannel either from the registry or by calling a bus-type-specific NdisXxx configuration function.

If such a driver cannot allocate the system DMA resources that its device needs, MiniportInitialize should release all resources it already allocated for its NIC and, then, fail initialization for that NIC.

Callers of NdisMRegisterDmaChannel run at IRQL PASSIVE_LEVEL.