EVT_SERCX2_APPLY_CONFIG funzione di callback (sercx.h)

Articolo
10/30/2024

Il EvtSerCx2ApplyConfig funzione di callback degli eventi viene chiamata dalla versione 2 dell'estensione del framework seriale (SerCx2) per fornire al driver del controller seriale un elenco di impostazioni di configurazione specifiche del dispositivo da applicare all'hardware del controller seriale.

Sintassi

EVT_SERCX2_APPLY_CONFIG EvtSercx2ApplyConfig;

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

Parametri

[in] Device

Handle WDFDEVICE per l'oggetto dispositivo framework che rappresenta il controller seriale. Il driver del controller seriale ha creato questo oggetto nel relativo EvtDriverDeviceAdd funzione di callback. Per altre informazioni, vedere SerCx2InitializeDevice.

[in] ConnectionParameters

Puntatore alla struttura dei parametri di connessione. Questa funzione deve eseguire il cast del puntatore 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 SerCx2 che per il sistema operativo. Per altre informazioni, vedere Osservazioni.

Valore restituito

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

Osservazioni

Il driver del controller seriale deve implementare questa funzione. Il driver registra la funzione nella chiamata al metodo SerCx2InitializeDevice che completa l'inizializzazione dell'oggetto dispositivo framework per il controller seriale.

SerCx2 chiama la funzione evtSerCx2ApplyConfig 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 IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION al controller seriale.

SerCx2 ottiene i parametri di configurazione dal campo dati definito dal fornitore nel 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. Per altre informazioni, vedere la descrizione del descrittore di connessione del bus seriale UART nella specifica ACPI 5.0 .

Quando un client invia una richiesta di IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION a una porta seriale gestita da SerCx2, SerCx2 chiama la funzione EvtSerCx2ApplyConfig per passare i parametri di configurazione al driver del controller seriale. Al termine del callback, SerCx2 completa la richiesta e usa il valore restituito dal callback come codice di stato per la richiesta.

Esempi

Per definire un EvtSerCx2ApplyConfig funzione di callback, è prima necessario fornire una dichiarazione di funzione che identifica il tipo di funzione di callback che si sta definendo. Windows fornisce un set di tipi di funzione di callback per i driver. La dichiarazione di una funzione usando i tipi di funzione di callback consente di l'analisi del codice per i driver, del driver statico (SDV) e altri strumenti di verifica rilevano errori ed è un requisito per la scrittura di driver per il sistema operativo Windows.

Ad esempio, per definire un EvtSerCx2ApplyConfig funzione di callback denominata MyApplyConfig, usare il tipo di funzione EVT_SERCX2_APPLY_CONFIG, come illustrato in questo esempio di codice:

EVT_SERCX2_APPLY_CONFIG  MyApplyConfig;

Implementare quindi la funzione di callback come segue:

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

Il tipo di funzione EVT_SERCX2_APPLY_CONFIG è definito nel file di intestazione Sercx.h. Per identificare in modo più accurato gli errori quando si eseguono gli strumenti di analisi del codice, assicurarsi di aggiungere l'annotazione Use_decl_annotations alla definizione della funzione. L'annotazione Use_decl_annotations assicura che vengano utilizzate le annotazioni applicate al tipo di funzione EVT_SERCX2_APPLY_CONFIG nel file di intestazione. Per altre informazioni sui requisiti per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite i tipi di ruolo della funzione per i driver KMDF. Per altre informazioni su Use_decl_annotations, vedere l'annotazione del comportamento della funzione.

L'esempio di codice seguente illustra un'implementazione parziale di una funzione EvtSerCx2ApplyConfig 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
#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;
}

I file di intestazione pshpack1.h e poppack.h nell'esempio di codice precedente controllano la modalità di allineamento della struttura usata dal compilatore. I tipi di puntatore PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER e PPNP_SERIAL_BUS_DESCRIPTOR sono puntatori alle strutture RH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER e PNP_SERIAL_BUS_DESCRIPTOR. Per altre informazioni sui membri della struttura PNP_UART_SERIAL_BUS_DESCRIPTOR, vedere Tabella 6-193 nella specifica ACPI 5.0.