EVT_SERCX2_APPLY_CONFIG Rückruffunktion (sercx.h)

Artikel
10/30/2024

Die EvtSerCx2ApplyConfig Ereignisrückruffunktion wird von Version 2 der seriellen Framework-Erweiterung (SerCx2) aufgerufen, um den seriellen Controllertreiber mit einer Liste gerätespezifischer Konfigurationseinstellungen anzugeben, die auf die serielle Controllerhardware angewendet werden sollen.

Syntax

EVT_SERCX2_APPLY_CONFIG EvtSercx2ApplyConfig;

NTSTATUS EvtSercx2ApplyConfig(
  [in] WDFDEVICE Device,
  [in] PVOID ConnectionParameters
)
{...}

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

Ein Zeiger auf die Verbindungsparameterstruktur. Diese Funktion muss den Zeiger in den entsprechenden Zeigertyp umwandeln, die Datenstruktur analysieren, um die Konfigurationseinstellungen abzurufen, und diese Einstellungen auf die serielle Controllerhardware anwenden. Die Verbindungsparameterstruktur wird vom Hardwareplattformanbieter definiert und ist sowohl für SerCx2 als auch für das Betriebssystem undurchsichtig. Weitere Informationen finden Sie in den Hinweisen.

Rückgabewert

Die EvtSerCx2ApplyConfig Funktion gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich ist. Andernfalls wird ein entsprechender Fehlerstatuscode zurückgegeben.

Bemerkungen

Der serielle Controllertreiber muss diese Funktion implementieren. Der Treiber registriert die Funktion im Aufruf der SerCx2InitializeDevice Methode, die die Initialisierung des Framework-Geräteobjekts für den seriellen Controller beendet.

SerCx2 ruft die EvtSerCx2ApplyConfig Funktion während der Initialisierung des seriellen Controllers auf, um sicherzustellen, dass sich die Hardware in einem gültigen Anfangszustand befindet. Darüber hinaus wird diese Funktion aufgerufen, wenn ein Client eine IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION Anforderung an den seriellen Controller sendet.

SerCx2 ruft die Konfigurationsparameter aus dem vom Anbieter definierten Datenfeld im ACPI-Ressourcendeskriptor für das serielle Controllergerät ab. Das Datenformat, das die ACPI-Firmware zum Speichern dieser Konfigurationseinstellungen verwendet, sollte dasselbe Datenformat sein, das vom seriellen Controllertreiber erwartet wird. Weitere Informationen finden Sie in der Beschreibung der seriellen UART-Busverbindungsbeschreibung in der ACPI 5.0-Spezifikation.

Wenn ein Client eine IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION Anforderung an einen seriellen Port sendet, der von SerCx2 verwaltet wird, ruft SerCx2 die EvtSerCx2ApplyConfig--Funktion auf, um die Konfigurationsparameter an den seriellen Controllertreiber zu übergeben. Nachdem dieser Rückruf zurückgegeben wurde, schließt SerCx2 die Anforderung ab und verwendet den Rückgabewert aus dem Rückruf als Statuscode für die Anforderung.

Beispiele

Um eine EvtSerCx2ApplyConfig Rückruffunktion zu definieren, müssen Sie zuerst eine Funktionsdeklaration bereitstellen, die den Typ der rückruffunktion identifiziert, die Sie definieren. Windows stellt eine Reihe von Rückruffunktionstypen für Treiber bereit. Durch das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen können Codeanalyse für Treiber, statische Treiberüberprüfung (SDV) und andere Überprüfungstools Fehler finden, und es ist eine Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine EvtSerCx2ApplyConfig Rückruffunktion zu definieren, die MyApplyConfigbenannt ist, verwenden Sie den EVT_SERCX2_APPLY_CONFIG Funktionstyp, wie in diesem Codebeispiel gezeigt:

EVT_SERCX2_APPLY_CONFIG  MyApplyConfig;

Implementieren Sie dann die Rückruffunktion wie folgt:

_Use_decl_annotations_
NTSTATUS
  MyApplyConfig(
    WDFDEVICE  Device,
    PVOID  ConnectionParameters
    )
  {...}

Der EVT_SERCX2_APPLY_CONFIG Funktionstyp wird in der Headerdatei Sercx.h definiert. Um Fehler genauer zu identifizieren, wenn Sie die Codeanalysetools ausführen, müssen Sie der Funktionsdefinition die Use_decl_annotations Anmerkung hinzufügen. Die Use_decl_annotations Anmerkung stellt sicher, dass die Anmerkungen, die auf den funktionstyp EVT_SERCX2_APPLY_CONFIG in der Headerdatei angewendet werden, verwendet 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_annotationsfinden Sie unter Annotating Function Behavior.

Das folgende Codebeispiel zeigt eine partielle Implementierung einer EvtSerCx2ApplyConfig--Funktion für ein UART:The following code example shows a partial implementation of an EvtSerCx2ApplyConfig function for a UART:

//
// Define the UART ACPI descriptor, plus any vendor-specific
// data that is needed by the serial controller (UART) driver.
//

#define ANYSIZE_ARRAY 1
#include <pshpack1.h>

//
// Common resource name descriptor
//
typedef struct _PNP_IO_DESCRIPTOR_RESOURCE_NAME {
    UCHAR ResourceIndex;
    UCHAR ResourceName[ANYSIZE_ARRAY];
} PNP_IO_DESCRIPTOR_RESOURCE_NAME, *PPNP_IO_DESCRIPTOR_RESOURCE_NAME;

//
// Bus descriptor for a UART
//
typedef struct _PNP_UART_SERIAL_BUS_DESCRIPTOR {
    PNP_SERIAL_BUS_DESCRIPTOR SerialBusDescriptor;
    ULONG BaudRate;
    USHORT RxBufferSize;
    USHORT TxBufferSize;
    UCHAR Parity;
    // Include any optional vendor data here:
    ...
    // Append the PNP_IO_DESCRIPTOR_RESOURCE_NAME here:
    ....
} PNP_UART_SERIAL_BUS_DESCRIPTOR, *PPNP_UART_SERIAL_BUS_DESCRIPTOR;

#include <poppack.h>

EVT_SERCX_APPLY_CONFIG MyApplyConfig;

//
// Implementation of an EvtSerCx2ApplyConfig callback function
//
_Use_decl_annotations_
VOID
  MyApplyConfig(
    WDFDEVICE Device,
    PVOID ConnectionParameters
    )
{
    NTSTATUS status = STATUS_SUCCESS; 
    PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER connection;
    PPNP_SERIAL_BUS_DESCRIPTOR descriptor;
    PPNP_UART_SERIAL_BUS_DESCRIPTOR uartDescriptor;

    if (ConnectionParameters == NULL)
    {
        status = STATUS_INVALID_PARAMETER; 
    }

    if (NT_SUCCESS(status))
    {
        connection = (PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER)ConnectionParameters;

        if (connection->PropertiesLength < sizeof(PNP_SERIAL_BUS_DESCRIPTOR))
        {
            status = STATUS_INVALID_PARAMETER;
        }
    }

    if (NT_SUCCESS(status))
    {
        descriptor = (PPNP_SERIAL_BUS_DESCRIPTOR)connection->ConnectionProperties;

        if (descriptor->SerialBusType != UART_SERIAL_BUS_TYPE)
        {
            status = STATUS_INVALID_PARAMETER;
        }
    }

    if (NT_SUCCESS(status))
    {
        uartDescriptor = (PPNP_UART_SERIAL_BUS_DESCRIPTOR)connection->ConnectionProperties; 

        // Apply the platform-specific configuration settings
        // from the UART descriptor here:
        ...
    }

    return status;
}

Die Headerdateien pshpack1.h und poppack.h im vorherigen Codebeispiel steuern den vom Compiler verwendeten Strukturausrichtungsmodus. Die PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER- und PPNP_SERIAL_BUS_DESCRIPTOR Zeigertypen sind Zeiger auf RH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER und PNP_SERIAL_BUS_DESCRIPTOR Strukturen. Weitere Informationen zu den Mitgliedern der PNP_UART_SERIAL_BUS_DESCRIPTOR Struktur finden Sie in Tabelle 6-193 in der ACPI 5.0-Spezifikation.