EVT_SERCX_APPLY_CONFIG fungsi panggilan balik (sercx.h)

Artikel
02/29/2024

Fungsi panggilan balik peristiwa EvtSerCxApplyConfig menginstruksikan driver pengontrol serial untuk menerapkan daftar pengaturan konfigurasi ke perangkat keras pengontrol serial.

Sintaks

EVT_SERCX_APPLY_CONFIG EvtSercxApplyConfig;

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

Parameter

[in] Device

Handel WDFDEVICE ke objek perangkat kerangka kerja yang mewakili pengontrol serial.

[in] ConnectionParameters

Penunjuk ke struktur parameter koneksi. Fungsi ini harus mentransmisikan parameter ini ke jenis penunjuk yang sesuai, mengurai struktur data untuk mendapatkan pengaturan konfigurasi, dan menerapkan pengaturan ini ke perangkat keras pengontrol serial. Struktur parameter koneksi didefinisikan oleh vendor platform perangkat keras dan buram untuk ekstensi kerangka kerja serial (SerCx) dan sistem operasi.

Nilai kembali

Fungsi EvtSerCxApplyConfig mengembalikan STATUS_SUCCESS jika panggilan berhasil. Jika tidak, kode status kesalahan akan dikembalikan.

Keterangan

SerCx memanggil fungsi ini selama inisialisasi pengontrol serial untuk memastikan bahwa perangkat keras dalam keadaan awal yang valid. Selain itu, fungsi ini dipanggil setiap kali klien mengirim permintaan kontrol I/O IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION ke pengontrol.

SerCx mendapatkan parameter konfigurasi ini dari deskriptor sumber daya ACPI untuk perangkat pengontrol serial. Format data yang digunakan firmware ACPI untuk menyimpan pengaturan konfigurasi ini harus format data yang sama yang diharapkan oleh driver pengontrol serial.

Ketika klien mengirim permintaan IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION ke port serial yang dikelola oleh SerCx, SerCx menentukan apakah driver pengontrol serial untuk port serial mendukung panggilan balik EvtSerCxApplyConfig , dan apakah deskriptor sumber daya ACPI untuk port serial menyediakan pengaturan koneksi default. Jika tidak, SerCx menyelesaikan permintaan dengan kode status kesalahan STATUS_NOT_SUPPORTED. Jika tidak, SerCx meneruskan parameter koneksi ke fungsi panggilan balik EvtSerCxApplyConfig driver. Setelah panggilan balik ini kembali, SerCx menyelesaikan permintaan dan menggunakan nilai pengembalian dari panggilan balik sebagai kode status untuk permintaan tersebut.

Jika driver pengontrol serial perlu mendapatkan parameter koneksi default pada satu waktu selain selama panggilan balik EvtSerCxApplyConfig , driver dapat memanggil metode SerCxGetConnectionParameters .

Untuk mendaftarkan fungsi panggilan balik EvtSerCxApplyConfig , driver harus memanggil metode SerCxInitialize .

Contoh

Jenis fungsi untuk panggilan balik ini dinyatakan dalam Sercx.h, sebagai berikut.

typedef NTSTATUS
  EVT_SERCX_APPLY_CONFIG(
    __in WDFDEVICE Device
    );

Untuk menentukan fungsi panggilan balik EvtSerCxApplyConfig yang diberi nama MyEvtSerCxApplyConfig, Anda harus terlebih dahulu memberikan deklarasi fungsi yang diperlukan Static Driver Verifier (SDV) dan alat verifikasi lainnya, sebagai berikut.

EVT_SERCX_APPLY_CONFIG MyEvtSerCxApplyConfig;

Kemudian, terapkan fungsi panggilan balik Anda sebagai berikut.

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

Untuk informasi selengkapnya tentang persyaratan SDV untuk deklarasi fungsi, lihat Mendeklarasikan Fungsi Menggunakan Jenis Peran Fungsi untuk Driver KMDF.

Contoh kode berikut menunjukkan implementasi parsial fungsi EvtSerCxApplyConfig untuk 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;
}

Jenis penunjuk PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER dan PPNP_SERIAL_BUS_DESCRIPTOR dalam contoh kode sebelumnya ditentukan dalam file header Reshub.h.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia dimulai dengan Windows 8.
Target Platform	Desktop
Header	sercx.h
IRQL	Dipanggil di IRQL <= DISPATCH_LEVEL

Lihat juga

IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION

SerCxGetConnectionParameters

SerCxInitialize

Bagikan melalui