PADAPTER_OBJECT
HalGetAdapter(
IN PDEVICE_DESCRIPTION DeviceDescription,
IN OUT PULONG NumberOfMapRegisters
);
HalGetAdapter returns a pointer to the adapter object for the DMA device defined in the device description structure.
typedef struct _DEVICE_DESCRIPTION { ULONG Version; //Currently, DEVICE_DESCRIPTION_VERSION or //DEVICE_DESCRIPTION_VERSION1 to use IgnoreCount BOOLEAN Master; //TRUE = busmaster adapter //FALSE = slave DMA device BOOLEAN ScatterGather; //Device supports scatter/gather BOOLEAN DemandMode; //Uses system DMA controller's demand mode BOOLEAN AutoInitialize; //Uses system DMA controller's autoinit mode BOOLEAN Dma32BitAddresses; BOOLEAN IgnoreCount; //DMA controller in this platform does not maintain //an accurate transfer counter, so requires workaround, //and Version must be DEVICE_DESCRIPTION_VERSION1 BOOLEAN Reserved1; BOOLEAN Reserved2; //Preceding Reserved members must be FALSE, and //Version must be DEVICE_DESCRIPTION_VERSION1 ULONG BusNumber; //System-assigned value for I/O bus ULONG DmaChannel; //Slave device attached to this number channel INTERFACE_TYPE InterfaceType; DMA_WIDTH DmaWidth; // 8-bit, 16-bit, etc. DMA_SPEED DmaSpeed; ULONG MaximumLength; //max number of bytes device can handle per DMA operation ULONG DmaPort; //MicroChannel-type bus port number } DEVICE_DESCRIPTION, *PDEVICE_DESCRIPTION;
HalGetAdapter returns a pointer to the requested adapter object, or it returns NULL if an adapter object could not be created.
The caller should fill in values for all members of the device-description structure that are pertinent to its device. All other members must be set to zero before calling HalGetAdapter.
The InterfaceType specifies the bus interface. Its value can be one of the following: Internal, Isa, Eisa, MicroChannel, TurboChannel, or PCIBus. However, additional types of buses will be supported in future versions of Windows NT. The upper bound on the types of buses supported is always MaximumInterfaceType.
The DmaWidth specifies one of the following: Width8Bits, Width16Bits, or Width32Bits. The DmaSpeed specifies one of the following: Compatible, TypeA, TypeB, or TypeC.
Setting Version to DEVICE_DESCRIPTION_VERSION1 and IgnoreCount to TRUE indicates that the current platform’s DMA controller cannot be relied on to maintain an accurate transfer counter. In platforms with such a DMA controller, the HAL ignores the DMA counter but must take extra precautions to maintain data integrity during transfer operations. Using this workaround to compensate for such a deficient DMA controller degrades the speed of DMA transfers.
A successful caller must save the returned adapter object pointer in resident memory because this pointer is a required parameter to the DMA support routines. Usually, device drivers save this pointer in their device extensions.
HalGetAdapter must only be called during initialization when the caller is running at IRQL PASSIVE_LEVEL.
HalAllocateCommonBuffer, HalGetDmaAlignmentRequirement, IoAllocateAdapterChannel