EVT_SERCX_APPLY_CONFIG funzione di callback (sercx.h)

Articolo
12/15/2024

La funzione di callback degli eventi EvtSerCxApplyConfig indica al driver del controller seriale di applicare un elenco di impostazioni di configurazione all'hardware del controller seriale.

Sintassi

EVT_SERCX_APPLY_CONFIG EvtSercxApplyConfig;

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

Parametri

[in] Device

Handle WDFDEVICE per l'oggetto dispositivo framework che rappresenta il controller seriale.

[in] ConnectionParameters

Puntatore alla struttura dei parametri di connessione. Questa funzione deve eseguire il cast di questo parametro al tipo di puntatore appropriato, analizzare la struttura dei dati per ottenere le impostazioni di configurazione e applicare queste impostazioni all'hardware del controller seriale. La struttura dei parametri di connessione è definita dal fornitore della piattaforma hardware ed è opaca sia per l'estensione del framework seriale (SerCx) che per il sistema operativo.

Valore restituito

La funzione evtSerCxApplyConfig restituisce STATUS_SUCCESS se la chiamata ha esito positivo. In caso contrario, restituisce un codice di stato di errore appropriato.

Osservazioni

SerCx chiama questa funzione durante l'inizializzazione del controller seriale per assicurarsi che l'hardware sia in uno stato iniziale valido. Inoltre, questa funzione viene chiamata ogni volta che un client invia una richiesta di controllo I/O IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION al controller.

SerCx ottiene questi parametri di configurazione dal descrittore di risorse ACPI per il dispositivo controller seriale. Il formato di dati usato dal firmware ACPI per archiviare queste impostazioni di configurazione deve essere lo stesso formato di dati previsto dal driver del controller seriale.

Quando un client invia una richiesta di IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION a una porta seriale gestita da SerCx, SerCx determina se il driver del controller seriale per la porta seriale supporta il EvtSerCxApplyConfig callback e se il descrittore di risorse ACPI per la porta seriale fornisce le impostazioni di connessione predefinite. In caso contrario, SerCx completa la richiesta con codice di stato di errore STATUS_NOT_SUPPORTED. In caso contrario, SerCx passa i parametri di connessione alla evtSerCxApplyConfig del driver funzione di callback. Al termine di questo callback, SerCx completa la richiesta e usa il valore restituito dal callback come codice di stato per la richiesta.

Se un driver del controller seriale deve ottenere i parametri di connessione predefiniti alla volta diversi da durante un EvtSerCxApplyConfig callback, il driver può chiamare il metodo SerCxGetConnectionParameters.

Per registrare un EvtSerCxApplyConfig funzione di callback, il driver deve chiamare il metodo SerCxInitialize.

Esempi

Il tipo di funzione per questo callback viene dichiarato in Sercx.h, come indicato di seguito.

typedef NTSTATUS
  EVT_SERCX_APPLY_CONFIG(
    __in WDFDEVICE Device
    );

Per definire un EvtSerCxApplyConfig funzione di callback denominata MyEvtSerCxApplyConfig, è prima necessario fornire una dichiarazione di funzione che Static Driver Verifier (SDV) e altri strumenti di verifica, come indicato di seguito.

EVT_SERCX_APPLY_CONFIG MyEvtSerCxApplyConfig;

Implementare quindi la funzione di callback come indicato di seguito.

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

Per altre informazioni sui requisiti SDV per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite i tipi di ruolo della funzione per i driver KMDF.

L'esempio di codice seguente mostra un'implementazione parziale di una funzione EvtSerCxApplyConfig per un 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;
}

I tipi di puntatore PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER e PPNP_SERIAL_BUS_DESCRIPTOR nell'esempio di codice precedente vengono definiti nel file di intestazione Reshub.h.

Fabbisogno

Requisito	Valore
client minimo supportato	Disponibile a partire da Windows 8.
piattaforma di destinazione	Desktop
intestazione	sercx.h
IRQL	Chiamato in IRQL <= DISPATCH_LEVEL

Vedere anche

IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION

SerCxGetConnectionParameters

SerCxInitialize

Condividi tramite