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.