SerCx2CustomTransmitCreate-Funktion (sercx.h)

Artikel
08/07/2023

Die SerCx2CustomTransmitCreate-Methode erstellt ein benutzerdefiniertes Übertragungsobjekt, das Version 2 der Serial Framework-Erweiterung (SerCx2) verwendet, um Übertragungsdaten mithilfe eines benutzerdefinierten Datenübertragungsmechanismus in den seriellen Controller zu schreiben.

Syntax

NTSTATUS SerCx2CustomTransmitCreate(
  [in]  WDFDEVICE                      Device,
  [in]  PSERCX2_CUSTOM_TRANSMIT_CONFIG CustomTransmitConfig,
  [in]  PWDF_OBJECT_ATTRIBUTES         Attributes,
  [out] SERCX2CUSTOMTRANSMIT           *CustomTransmit
);

Parameter

[in] Device

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

[in] CustomTransmitConfig

Ein Zeiger auf eine SERCX2_CUSTOM_TRANSMIT_CONFIG-Struktur . Vor dem Aufrufen dieser Methode muss der Aufrufer die SERCX2_CUSTOM_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 auf, um Transaktionen mit benutzerdefinierter Übertragung durchzuführen.

[in] Attributes

Ein Zeiger auf eine WDF_OBJECT_ATTRIBUTES-Struktur , die die Attribute beschreibt, die dem neuen benutzerdefinierten Ü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] CustomTransmit

Ein Zeiger auf einen Speicherort, an den diese Methode ein SERCX2CUSTOMTRANSMIT-Handle in das neu erstellte objekt mit benutzerdefinierter Übertragung 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 umfassen die folgenden status-Codes.

Rückgabecode	Beschreibung
STATUS_INVALID_DEVICE_REQUEST	Ein benutzerdefiniertes Übertragungsobjekt ist bereits aus einem vorherigen SerCx2CustomTransmitCreate-Aufruf vorhanden. oder ein System-DMA-transmit-Objekt aus einem vorherigen SerCx2SystemDmaTransmitCreate-Aufruf vorhanden ist; oder ein System-DMA-transmit-Objekt aus einem vorherigen SerCx2SystemDmaTransmitCreate-Aufruf vorhanden ist; oder SerCx2PioTransmitCreate wurde noch nicht aufgerufen, um ein PIO-Transmit-Objekt zu erstellen.
STATUS_INVALID_PARAMETER	Ein Parameterwert ist ungültig.
STATUS_INFO_LENGTH_MISMATCH	Der Wert Config->Size ist nicht gleich sizeof(SERCX2_CUSTOM_TRANSMIT_CONFIG).
STATUS_INSUFFICIENT_RESOURCES	Es stehen nicht genügend Ressourcen zum Erstellen des benutzerdefinierten Übertragungsobjekts zur Verfügung.

Hinweise

Diese Methode wird vom seriellen Controllertreiber aufgerufen, um ein benutzerdefiniertes Übertragungsobjekt zu erstellen. SerCx2 verwendet dieses Objekt, um transaktionen mit benutzerdefinierter Übertragung durchzuführen. Dabei handelt es sich um Transaktionen, die einen benutzerdefinierten Datenübertragungsmechanismus zum Schreiben von Übertragungsdaten in den seriellen Controller verwenden.

Ein serieller Controllertreiber muss die Methoden SerCx2InitializeDevice und SerCx2PioTransmitCreate erfolgreich aufrufen, bevor SerCx2CustomTransmitCreate aufgerufen wird.

Vor dem Aufrufen von SerCx2CustomTransmitCreate muss der Treiber des seriellen Controllers die SERCX2_CUSTOM_TRANSMIT_CONFIG_INIT-Funktion aufrufen, um die SERCX2_CUSTOM_TRANSMIT_CONFIG Struktur zu initialisieren, auf die von CustomTransmitConfig verwiesen wird. Diese Funktion legt die folgenden Elemente der Struktur auf 0 fest:

Ausrichtung
MinimumTransactionLength
MaximumTransactionLength
MinimumTransferUnit
Exklusiv

Bei Bedarf kann der serielle Controllertreiber jedes dieser Member auf Nichtzero-Werte festlegen, nachdem die Initialisierungsfunktion zurückgegeben wird. Der Einfachheit halber verwendet SerCx2CustomTransmitCreate jedoch die folgenden Standardwerte, wenn diese Member 0 sind:

Wenn Alignment 0 ist, legt SerCx2 den Datenausrichtungswert auf eins fest, was bedeutet, dass der Schreibpuffer an einer beliebigen Bytegrenze im Arbeitsspeicher starten kann.
Wenn MinimumTransactionLength 0 ist, legt SerCx2 die minimale Transaktionslänge auf ein Byte fest.
Wenn MaximumTransactionLength 0 ist, legt SerCx2 die maximale Transaktionslänge auf ((ULONG)-1) fest.
Wenn MinimumTransferUnit 0 ist, legt SerCx2 die minimale Übertragungseinheit auf ein Byte fest.
Wenn Exklusiv null (FALSE) ist, ist der exklusive Modus deaktiviert.

Wenn der aufrufende Treiber Exklusiv auf TRUE festlegt, müssen die Member MinimumTransferUnit, Alignment und MinimumTransactionLength 0 sein. Weitere Informationen finden Sie unter SERCX2_CUSTOM_TRANSMIT_CONFIG.

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

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

Weitere Informationen zum Erstellen benutzerdefinierter Übertragungsobjekte finden Sie unter SERCX2CUSTOMTRANSMIT. Weitere Informationen zu Transaktionen mit benutzerdefinierter Übertragung finden Sie unter SerCx2 Custom-Transmit Transaktionen.