IoAllocateAdapterChannel

IoAllocateAdapterChannel

NTSTATUS
IoAllocateAdapterChannel(
IN PADAPTER_OBJECT AdapterObject,
IN PDEVICE_OBJECT DeviceObject,
IN ULONG NumberOfMapRegisters,
IN PDRIVER_CONTROL ExecutionRoutine,
IN PVOID Context
);

IoAllocateAdapterChannel allocates an adapter object for a DMA operation on the target device object and calls a driver-supplied routine to carry out an I/O operation through the system DMA controller or a busmaster adapter as soon as the appropriate DMA channel is available and/or any necessary map registers are available.

Parameters

AdapterObject

Points to an adapter object, representing the adapter channel or busmaster adapter to be allocated. The driver obtained this pointer by calling HalGetAdapter.

DeviceObject

Points to the device object, representing the target device for a requested DMA operation.

NumberOfMapRegisters

Specifies the number of map registers. This value is the lesser of (the number of map registers needed to satisfy the current transfer request) or (the number of available map registers returned when the driver called HalGetAdapter).

ExecutionRoutine

Points to a driver-supplied AdapterControl routine to be called as soon the system DMA controller or busmaster adapter is available. This routine is declared as follows:

IO_ALLOCATION_ACTION

(*PDRIVER_CONTROL)(

IN PDEVICE_OBJECT DeviceObject,

IN PIRP Irp,

IN PVOID MapRegisterBase,

IN PVOID Context

);

Context

Points to the driver-determined context passed to the driver’s AdapterControl routine when it is called.

Return Value

This routine can return one of the following NTSTATUS values:

Value	Meaning
STATUS_SUCCESS	The adapter object has been allocated.
STATUS_INSUFFICIENT_RESOURCES	The NumberOfMapRegisters is larger than the value returned by HalGetAdapter.

Comments

This routine reserves exclusive access to a DMA controller channel and/or map registers for the one or more DMA operations required to satisfy the current IRP’s transfer request for the specified device.

If the system DMA controller or busmaster adapter is already busy, the driver-supplied AdapterControl routine is queued. Otherwise, the driver supplied AdapterControl routine is called immediately.

IoAllocateAdapterChannel passes an Irp to the caller’s AdapterControl routine only if this routine is called from the StartIo routine to process the same IRP passed in to the StartIo routine. Otherwise, the Irp has no meaning, and a driver should consider the Irp a system-reserved parameter to its AdaperControl routine.

The return value of the AdapterControl routine depends on whether the device is a busmaster or uses system DMA. Drivers of busmaster devices return DeallocateObjectKeepRegisters; drivers of slave devices return KeepObject.

Callers of IoAllocateAdapterChannel must be running at IRQL DISPATCH_LEVEL.