EVT_SERCX2_SYSTEM_DMA_RECEIVE_CONFIGURE_DMA_CHANNEL Rückruffunktion (sercx.h)

Artikel
02/29/2024

Die EvtSerCx2SystemDmaReceiveConfigureDmaChannel-Ereignisrückruffunktion wird von Version 2 der Serial Framework-Erweiterung (SerCx2) aufgerufen, damit der Treiber des seriellen Controllers jede benutzerdefinierte Konfiguration des DMA-Adapters ausführen kann, die vor dem Start jeder Übertragung in einer System-DMA-Receive-Transaktion erforderlich ist.

Syntax

EVT_SERCX2_SYSTEM_DMA_RECEIVE_CONFIGURE_DMA_CHANNEL EvtSercx2SystemDmaReceiveConfigureDmaChannel;

NTSTATUS EvtSercx2SystemDmaReceiveConfigureDmaChannel(
  [in] SERCX2SYSTEMDMARECEIVE SystemDmaReceive,
  [in] PMDL Mdl,
  [in] ULONG Offset,
  [in] ULONG Length
)
{...}

Parameter

[in] SystemDmaReceive

Ein SERCX2SYSTEMDMARECEIVE Handle für ein System-DMA-Receive-Objekt. Der serielle Controllertreiber hat zuvor die SerCx2SystemDmaReceiveCreate-Methode aufgerufen, um dieses Objekt zu erstellen.

[in] Mdl

Ein Zeiger auf eine MDL , der die Speicherseiten beschreibt, die vom Lesepuffer für die System-DMA-receive-Transaktion überspannt werden. Die Scatter/Gather-Liste für die DMA-Übertragung verwendet den Bereich dieses Arbeitsspeichers, der durch die Parameter Offset und Length angegeben wird.

[in] Offset

Der Startoffset für die Datenübertragung. Dieser Parameter ist ein Byteoffset vom Anfang des Pufferbereichs, der von der MDL beschrieben wird. Wenn die MDL insgesamt N Bytes Pufferspeicher angibt, liegen die möglichen Werte von Offset im Bereich 0 bis N–1.

[in] Length

Die Größe der Datenübertragung in Bytes. Wenn die MDL eine Summe von N Bytes Pufferraum angibt, liegen die möglichen Werte von Length im Bereich von 1 bis N–Offset.

Rückgabewert

Die EvtSerCx2SystemDmaReceiveConfigureDmaChannel-Funktion gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich ist. Andernfalls wird ein entsprechender Fehler status Code zurückgegeben.

Hinweise

Ihr serieller Controllertreiber kann diese Funktion optional implementieren. Bei Implementierung registriert der Treiber die Funktion im SerCx2SystemDmaReceiveCreate-Aufruf , der das system-DMA-receive-Objekt erstellt.

Vor dem Initiieren einer System-DMA-receive-Transaktion ruft SerCx2 die EvtSerCx2SystemDmaReceiveConfigureDmaChannel-Funktion auf, sofern sie implementiert ist. Diese Funktion führt eine spezielle Konfiguration des System-DMA-Controllers aus, die möglicherweise erforderlich ist, bevor SerCx2 die Transaktion system-DMA-receive startet.

Der serielle Controllertreiber kann eine Methode wie SerCx2SystemDmaReceiveGetDmaEnabler aufrufen, um die DMA-Aktivierung für den System-DMA-Controller abzurufen, der für System-DMA-Receive-Transaktionen verwendet wird.

Weitere Informationen finden Sie unter SerCx2 System-DMA-Receive Transactions.

Beispiele

Um eine EvtSerCx2SystemDmaReceiveConfigureDmaChannel-Rückruffunktion zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der von Ihnen definierten Rückruffunktion identifiziert. Windows bietet eine Reihe von Rückruffunktionstypen für Treiber. Das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen hilft der Codeanalyse für Treiber, der statischen Treiberüberprüfung (Static Driver Verifier , SDV) und anderen Überprüfungstools, Fehler zu finden, und es ist eine Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine EvtSerCx2SystemDmaReceiveConfigureDmaChannel-Rückruffunktion mit dem Namen MySystemDmaReceiveConfigureDmaChannelzu definieren, verwenden Sie den EVT_SERCX2_SYSTEM_DMA_RECEIVE_CONFIGURE_DMA_CHANNEL Funktionstyp, wie in diesem Codebeispiel gezeigt:

EVT_SERCX2_SYSTEM_DMA_RECEIVE_CONFIGURE_DMA_CHANNEL  MySystemDmaReceiveConfigureDmaChannel;

Implementieren Sie dann Ihre Rückruffunktion wie folgt:

_Use_decl_annotations_
NTSTATUS
  MySystemDmaReceiveConfigureDmaChannel(
    SERCX2SYSTEMDMARECEIVE SystemDmaReceive,
    PMDL Mdl,
    ULONG Offset,
    ULONG Length
    )
  {...}

Der EVT_SERCX2_SYSTEM_DMA_RECEIVE_CONFIGURE_DMA_CHANNEL Funktionstyp ist in der Headerdatei Sercx.h definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, fügen Sie der Funktionsdefinition die Use_decl_annotations Anmerkung hinzu. Die Use_decl_annotations Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den EVT_SERCX2_SYSTEM_DMA_RECEIVE_CONFIGURE_DMA_CHANNEL Funktionstyp in der Headerdatei angewendet werden. Weitere Informationen zu den Anforderungen für Funktionsdeklarationen finden Sie unter Deklarieren von Funktionen mithilfe von Funktionsrollentypen für KMDF-Treiber. Weitere Informationen zu Use_decl_annotations finden Sie unter Verhalten von Funktionen mit Anmerkungen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar ab Windows 8.1.
Zielplattform	Desktop
Kopfzeile	sercx.h
IRQL	Wird unter IRQL <= DISPATCH_LEVEL aufgerufen.