EVT_SERCX_APPLY_CONFIG Rückruffunktion (sercx.h)

Artikel
12/13/2024

Die EvtSerCxApplyConfig Ereignisrückruffunktion weist den seriellen Controllertreiber an, eine Liste der Konfigurationseinstellungen auf die serielle Controllerhardware anzuwenden.

Syntax

EVT_SERCX_APPLY_CONFIG EvtSercxApplyConfig;

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

Parameter

[in] Device

Ein WDFDEVICE-Handle für das Framework-Geräteobjekt, das den seriellen Controller darstellt.

[in] ConnectionParameters

Ein Zeiger auf die Verbindungsparameterstruktur. Diese Funktion muss diesen Parameter in den entsprechenden Zeigertyp umwandeln, die Datenstruktur analysieren, um die Konfigurationseinstellungen abzurufen, und diese Einstellungen auf die Hardware des seriellen Controllers anwenden. Die Verbindungsparameterstruktur wird vom Hardwareplattformanbieter definiert und ist sowohl für die serielle Framework-Erweiterung (SerCx) als auch für das Betriebssystem undurchsichtig.

Rückgabewert

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

Bemerkungen

SerCx ruft diese 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 E/A-Steuerelementanforderung an den Controller sendet.

SerCx ruft diese Konfigurationsparameter vom 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.

Wenn ein Client eine IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION Anforderung an einen seriellen Port sendet, der von SerCx verwaltet wird, bestimmt SerCx, ob der serielle Controllertreiber für den seriellen Port den EvtSerCxApplyConfig Rückruf unterstützt und ob der ACPI-Ressourcendeskriptor für den seriellen Port Standardverbindungseinstellungen bereitstellt. Wenn nicht, schließt SerCx die Anforderung mit fehlerstatuscode STATUS_NOT_SUPPORTED ab. Andernfalls übergibt SerCx die Verbindungsparameter an die EvtSerCxApplyConfig Rückruffunktion des Treibers. Nachdem dieser Rückruf zurückgegeben wurde, schließt SerCx die Anforderung ab und verwendet den Rückgabewert aus dem Rückruf als Statuscode für die Anforderung.

Wenn ein serieller Controllertreiber die Standardverbindungsparameter zu einem anderen Zeitpunkt abrufen muss als während eines EvtSerCxApplyConfig Rückrufs, kann der Treiber die SerCxGetConnectionParameters--Methode aufrufen.

Um eine EvtSerCxApplyConfig Rückruffunktion zu registrieren, muss der Treiber die SerCxInitialize-Methode aufrufen.

Beispiele

Der Funktionstyp für diesen Rückruf wird wie folgt in Sercx.h deklariert.

typedef NTSTATUS
  EVT_SERCX_APPLY_CONFIG(
    __in WDFDEVICE Device
    );

Um eine EvtSerCxApplyConfig Rückruffunktion zu definieren, die MyEvtSerCxApplyConfigheißt, müssen Sie zunächst eine Funktionsdeklaration angeben, die Statische Treiberüberprüfung (SDV) und andere Überprüfungstools erforderlich ist.

EVT_SERCX_APPLY_CONFIG MyEvtSerCxApplyConfig;

Implementieren Sie dann die Rückruffunktion wie folgt.

NTSTATUS
  MyEvtSerCxApplyConfig(
    __in WDFDEVICE Device
    )
{ ... }

Weitere Informationen zu SDV-Anforderungen für Funktionsdeklarationen finden Sie unter Deklarieren von Funktionen mithilfe von Funktionsrollentypen für KMDF-Treiber.

Das folgende Codebeispiel zeigt eine partielle Implementierung einer EvtSerCxApplyConfig--Funktion für eine UART.

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

#define ANYSIZE_ARRAY 1


//
// 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;

EVT_SERCX_APPLY_CONFIG UartEvtApplyConfig;

//
// Implementation of an EvtSerCxApplyConfig callback function
//
NTSTATUS
  UartEvtApplyConfig(
    __in WDFDEVICE Device,
    __in 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 configuration settings from
        // the UART descriptor.
        ...
    }

    return status;
}

Die PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER- und PPNP_SERIAL_BUS_DESCRIPTOR Zeigertypen im vorherigen Codebeispiel werden in der Headerdatei Reshub.h definiert.