PALLOCATE_ADAPTER_CHANNEL funzione di callback (wdm.h)

Articolo
02/27/2024

La routine AllocateAdapterChannel prepara il sistema per un'operazione DMA per conto dell'oggetto dispositivo di destinazione e quindi chiama la routine AdapterControl fornita dal driver per eseguire l'operazione DMA.

Sintassi

PALLOCATE_ADAPTER_CHANNEL PallocateAdapterChannel;

NTSTATUS PallocateAdapterChannel(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] PDEVICE_OBJECT DeviceObject,
  [in] ULONG NumberOfMapRegisters,
  [in] PDRIVER_CONTROL ExecutionRoutine,
  [in] PVOID Context
)
{...}

Parametri

[in] DmaAdapter

Puntatore alla struttura DMA_ADAPTER restituita da IoGetDmaAdapter che rappresenta l'adattatore master del bus o il controller DMA.

[in] DeviceObject

Puntatore all'oggetto dispositivo che rappresenta il dispositivo di destinazione per un'operazione DMA richiesta.

[in] NumberOfMapRegisters

Specifica il numero di registri mappa da usare nel trasferimento. Questo valore è minore del numero di registri mappa necessari per soddisfare la richiesta di trasferimento corrente e il numero di registri mappa disponibili restituiti da IoGetDmaAdapter.

[in] ExecutionRoutine

Puntatore a una routine AdapterControl fornita dal driver. La routine viene chiamata quando il controller DMA di sistema o la scheda master del bus diventa disponibile.

[in] Context

Puntatore al contesto determinato dal driver da passare alla routine AdapterControl .

Valore restituito

Questa routine può restituire uno dei valori NTSTATUS seguenti.

Codice restituito	Descrizione
STATUS_SUCCESS	Il canale della scheda è stato allocato. Il sistema chiamerà la routine AdapterControl dopo l'avvio dell'operazione DMA.
STATUS_INSUFFICIENT_RESOURCES	NumberOfMapRegisters è maggiore del valore restituito da IoGetDmaAdapter. La routine AdapterControl non verrà chiamata.

Commenti

AllocateAdapterChannel non è una routine di sistema che può essere chiamata direttamente per nome. Questa routine è chiamabile solo per puntatore dall'indirizzo restituito in una struttura di DMA_OPERATIONS . I driver ottengono l'indirizzo di questa routine chiamando IoGetDmaAdapter.

Un driver chiama la routine AllocateAdapterControl per registrare una routine AdapterControl che esegue un'operazione DMA per il driver. La routine AdapterControl esegue un'operazione DMA usando il controller DMA di sistema o una scheda master del bus.

Se l'operazione DMA può essere eseguita immediatamente, il sistema chiama immediatamente AdapterControl. Se il controller DMA di sistema o la scheda master del bus è attualmente in uso, AllocateAdapterChannel accoda AdapterControl fino a quando la scheda non diventa disponibile. In entrambi i casi , AllocateAdapterChannel restituisce STATUS_SUCCESS.

Se il sistema non dispone delle risorse per eseguire l'operazione DMA, AllocateAdapterChannel restituisce STATUS_INSUFFICIENT_RESOURCES. In tal caso AdapterControl non viene accodato e il driver deve completare l'IRP corrente con il codice di errore appropriato, ad esempio STATUS_INSUFFICIENT_RESOURCES.

Questa routine riserva l'accesso esclusivo a un canale controller DMA e esegue il mapping dei registri per le operazioni DMA necessarie per soddisfare la richiesta di trasferimento di IRP corrente per il dispositivo specificato.

È possibile accodare una sola richiesta DMA per un oggetto dispositivo in qualsiasi momento. Pertanto, il driver non deve chiamare di nuovo AllocateAdapterChannel per un'altra operazione DMA nello stesso oggetto dispositivo fino al completamento dell'esecuzione della routine AdapterControl . Inoltre, un driver non deve chiamare AllocateAdapterChannel all'interno della routine AdapterControl .

Il sistema passa il valore del membro CurrentIrp di DeviceObject come parametro Irp di AdapterControl. Se AllocateAdapterChannel viene chiamato dalla routine StartIo di un driver, questo è garantito puntare all'IRP chiamato StartIo per elaborare. In caso contrario, per usare il parametro Irp di AdapterControl, il driver deve impostare CurrentIrp per puntare all'IRP corrente prima di chiamare AllocateAdapterChannel.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile a partire da Windows 2000.
Piattaforma di destinazione	Desktop
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	DISPATCH_LEVEL
Regole di conformità DDI	IrqlDispatch(storport), IrqlDispatch(storport), IrqlDispatch(wdm)