SerCx2SystemDmaReceiveCreate-Funktion (sercx.h)

Artikel
10/30/2024

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

Syntax

NTSTATUS SerCx2SystemDmaReceiveCreate(
  [in]           WDFDEVICE                         Device,
  [in]           PSERCX2_SYSTEM_DMA_RECEIVE_CONFIG SystemDmaReceiveConfig,
  [in, optional] PWDF_OBJECT_ATTRIBUTES            Attributes,
  [out]          SERCX2SYSTEMDMARECEIVE            *SystemDmaReceive
);

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] SystemDmaReceiveConfig

Ein Zeiger auf eine SERCX2_SYSTEM_DMA_RECEIVE_CONFIG Struktur. Vor dem Aufrufen dieser Methode muss der Aufrufer die SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT- oder SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT_NEW_DATA_NOTIFICATION-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 auf, um System-DMA-Empfangstransaktionen auszuführen.

[in, optional] Attributes

Ein Zeiger auf eine WDF_OBJECT_ATTRIBUTES-Struktur, die die Attribute beschreibt, die dem neuen System-DMA-Empfangsobjekt 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] SystemDmaReceive

Ein Zeiger auf eine Position, an die diese Methode ein SERCX2SYSTEMDMARECEIVE Handle in das neu erstellte System-DMA-Empfangsobjekt 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-Receive-Objekt ist bereits aus einem vorherigen SerCx2SystemDmaReceiveCreate Aufruf vorhanden; oder ein objekt für den benutzerdefinierten Empfang ist bereits aus einem vorherigen Aufruf der SerCx2CustomReceiveCreate-Methode vorhanden; oder ein benutzerdefiniertes Übertragungsobjekt ist aus einem vorherigen Aufruf der SerCx2CustomTransmitCreate-Methode vorhanden; oder SerCx2PioReceiveCreate wurde noch nicht aufgerufen, um ein PIO-Empfangsobjekt zu erstellen.
STATUS_INFO_LENGTH_MISMATCH	Der Wert Config->Size entspricht nicht Sizeof(SERCX2_SYSTEM_DMA_RECEIVE_CONFIG).
STATUS_INVALID_PARAMETER	Ein Parameterwert ist ungültig.
STATUS_INSUFFICIENT_RESOURCES	Unzureichende Ressourcen sind verfügbar, um den angeforderten Vorgang auszuführen.

Bemerkungen

Diese Methode wird vom seriellen Controllertreiber aufgerufen, um ein System-DMA-Empfangsobjekt zu erstellen. SerCx2 verwendet dieses Objekt zum Ausführen von System-DMA-Empfangstransaktionen, bei denen es sich um E/A-Transaktionen handelt, die den DMA-Controller des Systems verwenden, um vom seriellen Controller empfangene Daten zu lesen.

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

Ein serieller Controllertreiber muss die methoden SerCx2InitializeDevice und SerCx2PioReceiveCreate Methoden aufrufen, bevor SerCx2SystemDmaReceiveCreateaufgerufen wird.

Vor dem Aufrufen SerCx2SystemDmaReceiveCreatemuss der serielle Controllertreiber die SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT- oder SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT_NEW_DATA_NOTIFICATION-Funktion aufrufen, um die SERCX2_SYSTEM_DMA_RECEIVE_CONFIG Struktur zu initialisieren, auf die SystemDmaReceiveConfigverweist. Diese Funktionen legen 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 SerCx2SystemDmaReceiveCreate 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_RECEIVE_CONFIG.

Wenn die angegebene Kombination von implementierten Rückruffunktionen ungültig ist, schlägt SerCx2SystemDmaReceiveCreate fehl und gibt STATUS_INVALID_PARAMETER zurück. Der Treiber muss beide oder keines der EvtSerCx2SystemDmaReceiveEnableNewDataNotification und EvtSerCx2SystemDmaReceiveCancelNewDataNotification Funktionen implementieren.

Als Option kann ein serieller Controllertreiber den parameter Attributes verwenden, um einen Kontext für das System-DMA-Empfangsobjekt 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-Empfangsobjekten finden Sie unter SERCX2SYSTEMDMARECEIVE. Weitere Informationen zu System-DMA-Receive-Transaktionen finden Sie unter SerCx2 System-DMA-Receive Transactions.