NdisMRegisterDmaChannel function (ndis.h)
The NdisMRegisterDmaChannel function claims a system DMA controller channel during initialization for DMA operations on a subordinate NIC or on an ISA bus-master NIC.
Syntax
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
);
Parameters
[out] MiniportDmaHandle
A pointer to a caller-supplied variable in which this function returns a handle the miniport driver uses in subsequent calls to the NdisMXxx system DMA functions.
[in] MiniportAdapterHandle
The miniport adapter handle input to the MiniportInitializeEx function.
[in] DmaChannel
Ignored. Set the DMA channel, if any, at DmaDescription .
[in] Dma32BitAddresses
A boolean value that is TRUE if the NIC has 32 address lines. Otherwise, it is FALSE.
[in] DmaDescription
A pointer 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
A boolean value that is TRUE if the subordinate NIC uses the system DMA controller's demand mode. Otherwise, it is FALSE.
AutoInitialize
A boolean value that is TRUE if the subordinate NIC uses the system DMA controller's autoinitialize mode. Otherwise, it is FALSE.
DmaChannelSpecified
A boolean value that is TRUE if DmaChannel is set to the bus-relative value of the system DMA controller channel used by the NIC. Otherwise, it is FALSE.
DmaWidth
The transfer width for DMA operations, one of Width8Bits, Width16Bits, or Width32Bits.
DmaSpeed
The DMA speed as one of Compatible, TypeA, TypeB, or TypeC.
DmaPort
This member refers to the MCA bus, which is no longer supported. This member must be zero.
DmaChannel
The bus-relative number of the system DMA controller channel used by the NIC.
[in] MaximumLength
The maximum number of bytes that 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:
| Return code | Description |
|---|---|
|
NDIS claimed the specified DMA channel in the registry for the caller's NIC and set up necessary resources for subsequent DMA operations by the miniport driver. |
|
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 could not allocate the system resources it needs to support DMA operations by this miniport driver. |
|
Either the bus type or bus number is out of range or the driver declared the NIC to be a bus master on an I/O bus other than ISA. |
Remarks
A driver of a subordinate-DMA NIC must call NdisMRegisterDmaChannel from its MiniportInitializeEx function to reserve system resources for subsequent DMA operations and to claim them in the registry.
The driver of an ISA bus-master NIC also must call NdisMRegisterDmaChannel from MiniportInitializeEx to claim a system DMA controller channel for the NIC in the registry.
MiniportInitializeEx must call the NdisMSetMiniportAttributes function before calling NdisMRegisterDmaChannel.
MiniportInitializeEx obtained the bus-relative values passed to NdisMRegisterDmaChannel either from the registry or by calling the NdisMGetBusData function.
If such a driver cannot allocate the system DMA resources that its device needs, MiniportInitializeEx should release all resources it already allocated for the NIC and, then, fail initialization for that NIC.
If the driver successfully registers the DMA channel, it must later call the NdisMDeregisterDmaChannel function to deregister the DMA channel.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Supported for NDIS 6.0 and NDIS 5.1 drivers (see NdisMRegisterDmaChannel (NDIS 5.1)) in Windows Vista. Supported for NDIS 5.1 drivers (see NdisMRegisterDmaChannel (NDIS 5.1)) in Windows XP. |
| Target Platform | Universal |
| Header | ndis.h (include Ndis.h) |
| Library | Ndis.lib |
| IRQL | PASSIVE_LEVEL |
| DDI compliance rules | Irql_Miniport_Driver_Function(ndis) |