GPIO_CLIENT_CONTROLLER_SPECIFIC_FUNCTION fungsi panggilan balik (gpioclx.h)

Artikel
03/01/2024

Fungsi panggilan balik peristiwa CLIENT_ControllerSpecificFunction melakukan operasi yang khusus untuk pengontrol I/O (GPIO) tujuan umum tertentu.

Sintaks

GPIO_CLIENT_CONTROLLER_SPECIFIC_FUNCTION GpioClientControllerSpecificFunction;

NTSTATUS GpioClientControllerSpecificFunction(
  [in]      PVOID Context,
  [in, out] PGPIO_CLIENT_CONTROLLER_SPECIFIC_FUNCTION_PARAMETERS Parameters
)
{...}

Parameter

[in] Context

Penunjuk ke konteks perangkat driver pengontrol GPIO.

[in, out] Parameters

Penunjuk ke struktur GPIO_CLIENT_CONTROLLER_SPECIFIC_FUNCTION_PARAMETERS yang berisi buffer input dan output untuk operasi khusus pengontrol.

Nilai kembali

Fungsi CLIENT_ControllerSpecificFunction mengembalikan STATUS_SUCCESS jika panggilan berhasil. Nilai yang mungkin dikembalikan termasuk kode kesalahan berikut.

Menampilkan kode	Deskripsi
STATUS_NOT_SUPPORTED	Pengontrol GPIO tidak mendukung operasi yang ditentukan oleh parameter input.
STATUS_BUFFER_TOO_SMALL	Ukuran buffer input atau buffer output terlalu kecil.

Keterangan

Sebagai opsi, driver pengontrol GPIO dapat mendukung permintaan IOCTL_GPIO_CONTROLLER_SPECIFIC_FUNCTION . Jenis permintaan kontrol I/O (IOCTL) ini melakukan operasi khusus pengontrol untuk keuntungan driver perangkat periferal yang memerlukan operasi ini. Untuk mendukung IOCTL ini, driver pengontrol GPIO menerapkan fungsi CLIENT_ControllerSpecificFunction .

Ekstensi kerangka kerja GPIO (GpioClx) mendukung fungsi CLIENT_ControllerSpecificFunction untuk mengatasi kebutuhan spesifik platform perangkat keras tertentu. Driver pengontrol GPIO umum tidak mengimplementasikan fungsi ini. Driver perangkat periferal yang menggunakan permintaan IOCTL_GPIO_CONTROLLER_SPECIFIC_FUNCTION untuk melakukan operasi khusus perangkat keras pada satu platform berisiko hilangnya kompatibilitas dengan platform lain yang tidak mendukung operasi ini.

Biasanya, fungsi CLIENT_ControllerSpecificFunction memprogram pengontrol GPIO untuk melakukan operasi khusus perangkat keras pada satu set pin GPIO. Parameter input dan output untuk operasi ini ditentukan oleh pengembang untuk driver pengontrol GPIO. Hanya driver perangkat periferal yang mengetahui operasi tertentu yang diterapkan oleh driver pengontrol GPIO yang dapat meminta operasi ini.

Ketika GpioClx menerima permintaan IOCTL_GPIO_CONTROLLER_SPECIFIC_FUNCTION , GpioClx memeriksa apakah driver pengontrol GPIO telah menerapkan fungsi CLIENT_ControllerSpecificFunction . Jika demikian, GpioClx menyalin deskripsi buffer input dan output dari IOCTL ke struktur GPIO_CLIENT_CONTROLLER_SPECIFIC_FUNCTION_PARAMETERS dan meneruskan pointer ke struktur ini sebagai parameter ke fungsi CLIENT_ControllerSpecificFunction . Jika nilai parameter dalam struktur GPIO_CLIENT_CONTROLLER_SPECIFIC_FUNCTION_PARAMETERS valid, fungsi melakukan operasi yang diminta dan mengembalikan STATUS_SUCCESS.

Jika GpioClx menerima permintaan IOCTL_GPIO_CONTROLLER_SPECIFIC_FUNCTION , dan driver pengontrol GPIO tidak menerapkan fungsi CLIENT_ControllerSpecificFunction , GpioClx menyelesaikan IOCTL dengan kode kesalahan STATUS_NOT_IMPLEMENTED.

Contoh

Untuk menentukan fungsi panggilan balik CLIENT_ControllerSpecificFunction , Anda harus terlebih dahulu memberikan deklarasi fungsi yang mengidentifikasi jenis fungsi panggilan balik yang Anda tentukan. Windows menyediakan sekumpulan tipe fungsi panggilan balik untuk pengandar. Mendeklarasikan fungsi menggunakan jenis fungsi panggilan balik membantu Analisis Kode untuk Driver, Pemverifikasi Driver Statis (SDV), dan alat verifikasi lainnya menemukan kesalahan, dan itu adalah persyaratan untuk menulis driver untuk sistem operasi Windows.

Misalnya, untuk menentukan fungsi panggilan balik CLIENT_ControllerSpecificFunction yang diberi nama MyEvtGpioControllerSpecificFunction, gunakan jenis fungsi GPIO_CLIENT_CONTROLLER_SPECIFIC_FUNCTION, seperti yang ditunjukkan dalam contoh kode ini:

GPIO_CLIENT_CONTROLLER_SPECIFIC_FUNCTION MyEvtGpioControllerSpecificFunction;

Kemudian, terapkan fungsi panggilan balik Anda sebagai berikut:

_Use_decl_annotations_
NTSTATUS
  MyEvtGpioControllerSpecificFunction(
    PVOID Context,
    PGPIO_CLIENT_CONTROLLER_SPECIFIC_FUNCTION_PARAMETERS Parameters
    )
{ ... }

Jenis fungsi GPIO_CLIENT_CONTROLLER_SPECIFIC_FUNCTION ditentukan dalam file header Gpioclx.h. Untuk mengidentifikasi kesalahan secara lebih akurat saat Anda menjalankan alat analisis kode, pastikan untuk menambahkan anotasi Use_decl_annotations ke definisi fungsi Anda. Anotasi Use_decl_annotations memastikan bahwa anotasi yang diterapkan ke jenis fungsi GPIO_CLIENT_CONTROLLER_SPECIFIC_FUNCTION dalam file header digunakan. Untuk informasi selengkapnya tentang persyaratan untuk deklarasi fungsi, lihat Mendeklarasikan Fungsi dengan Menggunakan Jenis Peran Fungsi untuk Driver KMDF. Untuk informasi selengkapnya tentang Use_decl_annotations, lihat Perilaku Fungsi Anotasi.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Didukung dimulai dengan Windows 8.
Target Platform	Desktop
Header	gpioclx.h
IRQL	Dipanggil pada PASSIVE_LEVEL.

Lihat juga

GPIO_CLIENT_CONTROLLER_SPECIFIC_FUNCTION_PARAMETERS

IOCTL_GPIO_CONTROLLER_SPECIFIC_FUNCTION

Bagikan melalui