SerCx2CustomTransmitCreate-Funktion (sercx.h)

Artikel
10/30/2024

Die SerCx2CustomTransmitCreate Methode erstellt ein benutzerdefiniertes Übertragungsobjekt, das version 2 der seriellen Framework-Erweiterung (SerCx2) zum Schreiben von Daten an den seriellen Controller mithilfe eines benutzerdefinierten Datenübertragungsmechanismus verwendet.

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 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] 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 benutzerdefinierte Übertragungstransaktionen auszufü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 eine Position, an die diese Methode ein SERCX2CUSTOMTRANSMIT Handle in das neu erstellte benutzerdefinierte Ü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 benutzerdefiniertes Übertragungsobjekt ist bereits aus einem vorherigen SerCx2CustomTransmitCreate Aufruf vorhanden; oder ein System-DMA-transmit-Objekt ist aus einem vorherigen SerCx2SystemDmaTransmitCreate Aufruf vorhanden; oder ein System-DMA-transmit-Objekt ist aus einem vorherigen SerCx2SystemDmaTransmitCreate Aufruf vorhanden; oder SerCx2PioTransmitCreate wurde noch nicht aufgerufen, um ein PIO-Übertragungsobjekt zu erstellen.
STATUS_INVALID_PARAMETER	Ein Parameterwert ist ungültig.
STATUS_INFO_LENGTH_MISMATCH	Der Wert Config->Size entspricht nicht Sizeof(SERCX2_CUSTOM_TRANSMIT_CONFIG).
STATUS_INSUFFICIENT_RESOURCES	Unzureichende Ressourcen stehen zum Erstellen des benutzerdefinierten Übertragungsobjekts zur Verfügung.

Bemerkungen

Diese Methode wird vom seriellen Controllertreiber aufgerufen, um ein benutzerdefiniertes Übertragungsobjekt zu erstellen. SerCx2 verwendet dieses Objekt zum Ausführen von transaktionen mit benutzerdefinierten Übertragungen, bei denen es sich um Transaktionen handelt, die einen benutzerdefinierten Datenübertragungsmechanismus zum Schreiben von Daten an den seriellen Controller verwenden.

Ein serieller Controllertreiber muss die methoden SerCx2InitializeDevice und SerCx2PioTransmitCreate Methoden aufrufen, bevor SerCx2CustomTransmitCreateaufgerufen wird.

Vor dem Aufrufen SerCx2CustomTransmitCreatemuss der serielle Controllertreiber die SERCX2_CUSTOM_TRANSMIT_CONFIG_INIT-Funktion aufrufen, um die SERCX2_CUSTOM_TRANSMIT_CONFIG Struktur zu initialisieren, auf die CustomTransmitConfigverweist. Diese Funktion legt die folgenden Elemente der Struktur auf Null fest:

Ausrichtung
MinimumTransactionLength-
MaximumTransactionLength-
MinimumTransferUnit
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 SerCx2CustomTransmitCreate die folgenden Standardwerte, wenn diese Member null sind:

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

Wenn der aufrufende Treiber Exclusive auf TRUEfestlegt, muss die MinimumTransferUnit, Alignmentund MinimumTransactionLength Member null sein. Weitere Informationen finden Sie unter SERCX2_CUSTOM_TRANSMIT_CONFIG.

Als Option kann ein serieller Controllertreiber den parameter Attributes verwenden, um einen Kontext für das benutzerdefinierte Übertragungsobjekt zu erstellen und Zeiger auf EvtCleanupCallback und EvtDestroyCallback Funktionen zu liefern, die aufgerufen werden, um das Objekt für den Löschvorgang 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 benutzerdefinierten Übertragungsobjekten finden Sie unter SERCX2CUSTOMTRANSMIT. Weitere Informationen zu benutzerdefinierten Übertragungstransaktionen finden Sie unter SerCx2 Custom-Transmit Transactions.