PALLOCATE_ADAPTER_CHANNEL callback function (wdm.h)
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.
Syntax
PALLOCATE_ADAPTER_CHANNEL PallocateAdapterChannel;
NTSTATUS PallocateAdapterChannel(
[in] PDMA_ADAPTER DmaAdapter,
[in] PDEVICE_OBJECT DeviceObject,
[in] ULONG NumberOfMapRegisters,
[in] PDRIVER_CONTROL ExecutionRoutine,
[in] PVOID Context
)
{...}
Parameters
[in] DmaAdapter
Pointer to the DMA_ADAPTER structure returned by IoGetDmaAdapter that represents the bus-master adapter or DMA controller.
[in] DeviceObject
Pointer to the device object that represents the target device for a requested DMA operation.
[in] NumberOfMapRegisters
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.
[in] ExecutionRoutine
Pointer to a driver-supplied AdapterControl routine. The routine is called when the system DMA controller or bus-master adapter becomes available.
[in] Context
Pointer to the driver-determined context to be passed to the AdapterControl routine.
Return value
This routine can return one of the following NTSTATUS values.
| Return code | Description |
|---|---|
|
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. |
Remarks
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.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Available starting with Windows 2000. |
| Target Platform | Desktop |
| Header | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| IRQL | DISPATCH_LEVEL |
| DDI compliance rules | IrqlDispatch(storport), IrqlDispatch(storport), IrqlDispatch(wdm) |