The AllocateAdapterChannel routine prepares the system for a DMA operation on behalf of the target device object, and then calls the driver-supplied AdapterControl routine to carry out the DMA operation.
NTSTATUS AllocateAdapterChannel( _In_ PDMA_ADAPTER DmaAdapter, _In_ PDEVICE_OBJECT DeviceObject, _In_ ULONG NumberOfMapRegisters, _In_ PDRIVER_CONTROL ExecutionRoutine, _In_ PVOID Context );
- DmaAdapter [in]
- DeviceObject [in]
Pointer to the device object that represents the target device for a requested DMA operation.
- NumberOfMapRegisters [in]
Specifies the number of map registers to be used in the transfer. This value is the lesser of the number of map registers needed to satisfy the current transfer request, and the number of available map registers returned by IoGetDmaAdapter.
- ExecutionRoutine [in]
Pointer to a driver-supplied AdapterControl routine. The routine is called when the system DMA controller or bus-master adapter becomes available.
- Context [in]
Pointer to the driver-determined context to be passed to the AdapterControl routine.
This routine can return one of the following NTSTATUS values.
The adapter channel has been allocated. The system will call the AdapterControl routine once the DMA operation can begin.
The NumberOfMapRegisters is larger than the value returned by IoGetDmaAdapter. The AdapterControl routine will not be called.
AllocateAdapterChannel is not a system routine that can be called directly by name. This routine is callable only by pointer from the address returned in a DMA_OPERATIONS structure. Drivers obtain the address of this routine by calling IoGetDmaAdapter.
A driver calls the AllocateAdapterControl routine to register an AdapterControl routine that performs a DMA operation for the driver. The AdapterControl routine carries out a DMA operation using either the system DMA controller or a bus-master adapter.
If the DMA operation can be performed immediately, the system immediately calls AdapterControl. If the system DMA controller or bus-master adapter is currently in use, AllocateAdapterChannel queues the AdapterControl until the adapter becomes available. In either case, AllocateAdapterChannel returns STATUS_SUCCESS.
If the system lacks the resources to perform the DMA operation, AllocateAdapterChannel returns STATUS_INSUFFICIENT_RESOURCES. In that case, AdapterControl is not queued, and the driver should complete the current IRP with the appropriate error code (such as STATUS_INSUFFICIENT_RESOURCES).
This routine reserves exclusive access to a DMA controller channel and map registers for the one or more DMA operations that are required to satisfy the current IRP's transfer request for the specified device.
Only one DMA request can be queued for a device object at any one time. Therefore, the driver should not call AllocateAdapterChannel again for another DMA operation on the same device object until the AdapterControl routine has completed execution. In addition, a driver must not call AllocateAdapterChannel from within its AdapterControl routine.
The system passes the value of the CurrentIrp member of DeviceObject as the Irp parameter of AdapterControl. If AllocateAdapterChannel is called from a driver's StartIo routine, this is guaranteed to point to the IRP that StartIo was called to process. Otherwise, to use the Irp parameter of AdapterControl, the driver must set CurrentIrp to point to the current IRP before calling AllocateAdapterChannel.
|Available starting with Windows 2000.|
DDI compliance rules