SerCx2SystemDmaTransmitCreate-Funktion (sercx.h)

Artikel
10/30/2024

Die SerCx2SystemDmaTransmitCreate-Methode erstellt ein SerCx2 system-DMA-transmission-Objekt, das Version 2 der seriellen Framework-Erweiterung (SerCx2) zum Ausführen von System-DMA-transmission-Transaktionen verwendet.

Syntax

NTSTATUS SerCx2SystemDmaTransmitCreate(
  [in]           WDFDEVICE                          Device,
  [in]           PSERCX2_SYSTEM_DMA_TRANSMIT_CONFIG SystemDmaTransmitConfig,
  [in, optional] PWDF_OBJECT_ATTRIBUTES             Attributes,
  [out]          SERCX2SYSTEMDMATRANSMIT            *SystemDmaTransmit
);

Parameter

[in] Device

Ein WDFDEVICE-Handle für das Framework-Geräteobjekt, das den seriellen Controller darstellt. Der serielle Controllertreiber hat dieses Objekt in seiner EvtDriverDeviceAdd Rückruffunktion erstellt. Weitere Informationen finden Sie unter SerCx2InitializeDevice.

[in] SystemDmaTransmitConfig

Ein Zeiger auf eine SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG Struktur. Vor dem Aufrufen dieser Methode muss der Aufrufer die SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG_INIT-Funktion aufrufen, um die Struktur zu initialisieren. Diese Struktur enthält Zeiger auf eine Reihe von Ereignisrückrufroutinen, die vom seriellen Controllertreiber implementiert werden. SerCx2 ruft diese Funktionen zum Ausführen von System-DMA-Übertragungstransaktionen auf.

[in, optional] Attributes

Ein Zeiger auf eine WDF_OBJECT_ATTRIBUTES-Struktur, die die Attribute beschreibt, die dem neuen System-DMA-Übertragungsobjekt zugewiesen werden sollen. Vor dem Aufrufen dieser Methode muss der Aufrufer die WDF_OBJECT_ATTRIBUTES_INIT-Funktion aufrufen, um die Struktur zu initialisieren. Dieser Parameter ist optional und kann als WDF_NO_OBJECT_ATTRIBUTES angegeben werden, wenn der serielle Controllertreiber dem Objekt keine Attribute zuweisen muss. Weitere Informationen finden Sie in den Hinweisen.

[out] SystemDmaTransmit

Ein Zeiger auf eine Position, an die diese Methode ein SERCX2SYSTEMDMATRANSMIT Handle in das neu erstellte System-DMA-Übertragungsobjekt schreibt. SerCx2 und der serielle Controllertreiber verwenden dieses Handle in nachfolgenden Aufrufen, um auf dieses Objekt zu verweisen.

Rückgabewert

Diese Methode gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich ist. Mögliche Fehlerrückgabewerte sind die folgenden Statuscodes.

Rückgabecode	Beschreibung
STATUS_INVALID_DEVICE_REQUEST	Ein System-DMA-transmit-Objekt ist bereits aus einem vorherigen SerCx2SystemDmaTransmitCreate Aufruf vorhanden; oder ein benutzerdefiniertes Übertragungsobjekt ist aus einem vorherigen Aufruf der SerCx2CustomTransmitCreate-Methode vorhanden; oder ein objekt für den benutzerdefinierten Empfang ist aus einem vorherigen Aufruf der SerCx2CustomReceiveCreate-Methode vorhanden; oder SerCx2PioTransmitCreate wurde noch nicht aufgerufen, um ein PIO-Übertragungsobjekt zu erstellen.
STATUS_INFO_LENGTH_MISMATCH	Der Wert Config->Size entspricht nicht Sizeof(SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG).
STATUS_INVALID_PARAMETER	Ein Parameterwert ist ungültig.
STATUS_INSUFFICIENT_RESOURCES	Unzureichende Ressourcen stehen zum Erstellen des System-DMA-Übertragungsobjekts zur Verfügung.

Bemerkungen

Ihr serieller Controllertreiber kann diese Methode zum Erstellen eines System-DMA-Übertragungsobjekts verwenden. SerCx2 verwendet dieses Objekt zum Ausführen von System-DMA-Übertragungstransaktionen, bei denen es sich um Transaktionen handelt, die den System-DMA-Controller verwenden, um Daten in den seriellen Controller zu schreiben, der übertragen werden soll.

In der Regel ruft ein serieller Controllertreiber SerCx2SystemDmaTransmitCreate von der EvtDevicePrepareHardware Rückruffunktion auf. Diese Funktion empfängt eine Liste der Hardwareressourcen, die System-DMA-Kanäle enthalten können.

Der serielle Controllertreiber muss die methoden SerCx2InitializeDevice und SerCx2PioTransmitCreate Methoden aufrufen, bevor SerCx2SystemDmaTransmitCreateaufgerufen wird.

Vor dem Aufrufen SerCx2SystemDmaTransmitCreatemuss der serielle Controllertreiber die SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG_INIT-Funktion aufrufen, um die SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG Struktur zu initialisieren, auf die SystemDmaTransmitConfigverweist. Diese Funktion legt die folgenden Elemente der Struktur auf Null fest:

MaximumScatterGatherFragments
MinimumTransferUnitOverride
DmaAlignment-
MinimumTransactionLength-
Exklusive

Bei Bedarf kann der serielle Controllertreiber eines dieser Member auf Nichtzerowerte festlegen, nachdem die Initialisierungsfunktion zurückgegeben wurde. Aus Gründen der Einfachheit verwendet SerCx2SystemDmaTransmitCreate die folgenden Standardwerte, wenn diese Member null sind:

Wenn MaximumScatterGatherFragments null ist, legt SerCx2 die maximale Anzahl von Elementen in einer Punkt-/Gatherliste auf ((ULONG)-1 fest.
Wenn MinimumTransferUnitOverride null ist, legt SerCx2 die minimale Übertragungseinheit auf den Standardwert fest, der in der DMA_ADAPTER Struktur für den DMA-Controller des Systems angegeben ist. Weitere Informationen zu dieser Struktur finden Sie unter WdfDmaEnablerWdmGetDmaAdapter.
Wenn DmaAlignment null ist, legt SerCx2 den Ausrichtungswert auf die minimale Übertragungseinheit fest. Wenn MinimumTransferUnitOverride null ist, wird die standardmäßige Mindestübertragungseinheit verwendet.
Wenn MinimumTransactionLength null ist, legt SerCx2 die Mindesttransaktionslänge auf ein Byte fest.
Wenn Exklusiv- null (FALSE) ist, ist der exklusive Modus deaktiviert.

Wenn der aufrufende Treiber Exclusive auf TRUEfestlegt, müssen die MinimumTransferUnitOverride, DmaAlignment-und MinimumTransactionLength Member null sein. Weitere Informationen finden Sie unter SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG.

Wenn die angegebene Kombination von implementierten Rückruffunktionen ungültig ist, schlägt SerCx2SystemDmaTransmitCreate fehl und gibt STATUS_INVALID_PARAMETER zurück. Der Treiber muss entweder alle drei oder keines der EvtSerCx2SystemDmaTransmitDrainFifo, EvtSerCx2SystemDmaTransmitCancelDrainFifound EvtSerCx2SystemDmaTransmitPurgeFifo Funktionen implementieren.

Als Option kann ein serieller Controllertreiber den parameter Attributes verwenden, um einen Kontext für das System-DMA-übertragungsobjekt zu erstellen und Zeiger für EvtCleanupCallback und EvtDestroyCallback- Funktionen anzugeben, die aufgerufen werden, um das Objekt für das Löschen vorzubereiten. Weitere Informationen finden Sie unter WDF_OBJECT_ATTRIBUTES.

Wenn der parameter Attributes auf eine WDF_OBJECT_ATTRIBUTES-Struktur verweist, darf der Aufrufer die Werte, die die WDF_OBJECT_ATTRIBUTES_INIT Initialisierungsfunktion schreibt, nicht in die ParentObject-, ExecutionLevelund SynchronizationScope Member dieser Struktur überschreiben.

Weitere Informationen zum Erstellen von System-DMA-Übertragungsobjekten finden Sie unter SERCX2SYSTEMDMATRANSMIT. Weitere Informationen zu System-DMA-Transmissionstransaktionen finden Sie unter SerCx2 System-DMA-Transmit Transactions.