HalGetAdapter

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.

Parameters

DeviceDescription

Points to the following structure that describes the attributes of the device.

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;

NumberOfMapRegisters

Returns the maximum number of map registers the device driver can allocate for any DMA transfer operation. The MaximumLength specified in the DeviceDescription effectively constrains the input value to no more than (MaximumLength / PAGE_SIZE + 1). On return, the updated value of this parameter can be less than the maximum possible input value.

Return Value

HalGetAdapter returns a pointer to the requested adapter object, or it returns NULL if an adapter object could not be created.

Comments

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.

See Also

HalAllocateCommonBuffer, HalGetDmaAlignmentRequirement, IoAllocateAdapterChannel