funzione di callback EVT_SERCX2_APPLY_CONFIG (sercx.h)
La funzione di callback dell'evento EvtSerCx2ApplyConfig 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 nella relativa funzione di callback EvtDriverDeviceAdd . 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 la sezione 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.
Commenti
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. Questa funzione viene inoltre 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 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.
Esempio
Per definire una funzione di callback EvtSerCx2ApplyConfig , è necessario innanzitutto 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 tramite i tipi di funzione di callback consente di analizzare il codice per i driver, l'SDV ( Static Driver Verifier ) e altri strumenti di verifica di trovare errori ed è un requisito per la scrittura di driver per il sistema operativo Windows.
Ad esempio, per definire una funzione di callback EvtSerCx2ApplyConfig denominata MyApplyConfig, usare il tipo di funzione EVT_SERCX2_APPLY_CONFIG , come illustrato nell'esempio di codice seguente:
EVT_SERCX2_APPLY_CONFIG MyApplyConfig;
Implementare quindi la funzione di callback come indicato di seguito:
_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 garantisce 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 tipi di ruolo di funzione per i driver KMDF. Per altre informazioni sulle Use_decl_annotations, vedere Annotazione del comportamento della funzione.
L'esempio di codice seguente mostra 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 ulteriori informazioni sui membri della struttura PNP_UART_SERIAL_BUS_DESCRIPTOR , vedere la tabella 6-193 nella specifica ACPI 5.0.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Disponibile a partire da Windows 8.1. |
| Piattaforma di destinazione | Desktop |
| Intestazione | sercx.h |
| IRQL | Chiamato a PASSIVE_LEVEL. |
Vedi anche
IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per