GPIO_CLIENT_PREPARE_CONTROLLER fungsi panggilan balik (gpioclx.h)

Artikel
08/07/2023

Fungsi panggilan balik peristiwa CLIENT_PrepareController melakukan operasi apa pun yang diperlukan untuk membuat pengontrol I/O (GPIO) tujuan umum siap diakses oleh driver pengontrol GPIO.

Sintaks

GPIO_CLIENT_PREPARE_CONTROLLER GpioClientPrepareController;

NTSTATUS GpioClientPrepareController(
  [in] WDFDEVICE Device,
  [in] PVOID Context,
  [in] WDFCMRESLIST ResourcesRaw,
  [in] WDFCMRESLIST ResourcesTranslated
)
{...}

Parameter

[in] Device

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

[in] Context

Penunjuk ke konteks perangkat driver pengontrol GPIO.

[in] ResourcesRaw

Handel WDFCMRESLIST ke kumpulan objek sumber daya kerangka kerja. Koleksi ini mengidentifikasi sumber daya perangkat keras mentah (relatif bus) yang telah ditetapkan manajer Plug and Play (PnP) ke perangkat pengontrol GPIO.

[in] ResourcesTranslated

Handel WDFCMRESLIST ke kumpulan objek sumber daya kerangka kerja. Koleksi ini mengidentifikasi sumber daya perangkat keras yang diterjemahkan (fisik sistem) yang telah ditetapkan manajer PnP ke perangkat pengontrol GPIO.

Nilai kembali

Fungsi CLIENT_PrepareController mengembalikan STATUS_SUCCESS jika panggilan berhasil. Jika tidak, kode kesalahan akan menampilkan kode kesalahan yang sesuai.

Keterangan

Fungsi panggilan balik ini diimplementasikan oleh driver pengontrol GPIO. Ekstensi kerangka kerja GPIO (GpioClx) memanggil fungsi ini untuk menginisialisasi sumber daya perangkat keras yang dibutuhkan driver pengontrol GPIO sehingga dapat mengakses perangkat pengontrol GPIO.

Parameter ResourcesRaw dan ResourcesTranslated ditangani ke daftar sumber daya mentah dan terjemahan. Daftar ini menjelaskan sumber daya perangkat keras yang telah ditetapkan manajer PnP ke perangkat pengontrol GPIO yang ditentukan oleh parameter Perangkat . Untuk informasi selengkapnya, lihat Sumber Daya Mentah dan Terjemahan.

Selama panggilan balik CLIENT_PrepareController , driver pengontrol GPIO dapat memperoleh sumber daya perangkat keras yang diperlukan dari daftar ResourcesRaw atau ResourcesTranslated . Jika perangkat pengontrol GPIO dipetakan memori, driver harus memetakan rentang atau rentang alamat memori relatif bus yang ditetapkan ke daftar perangkat keras perangkat ke alamat virtual sistem. Untuk informasi selengkapnya, lihat Memetakan Alamat Bus-Relative ke Alamat Virtual.

Jika pengontrol GPIO tidak dipetakan memori, sumber daya perangkat keras driver berisi ID koneksi alih-alih rentang memori. Driver menggunakan ID ini untuk membuka koneksi logis ke pengontrol GPIO, dan mengirim permintaan I/O melalui koneksi ini untuk mengakses register pengontrol.

GpioClx terhubung ke (dan kemudian terputus dari) sumber daya interupsi apa pun yang ditetapkan manajer PnP ke pengontrol GPIO. Jika GpioClx menerima sumber daya interupsi seperti itu, GpioClx tidak menghapus sumber daya interupsi ini dari daftar sumber daya yang diteruskannya ke fungsi panggilan balik CLIENT_PrepareController . Namun, driver pengontrol GPIO tidak boleh mencoba menyambungkan (atau kemudian memutuskan sambungan dari) sumber daya interupsi apa pun yang ditemukannya dalam daftar ini.

Fungsi panggilan balik peristiwa CLIENT_ReleaseController melakukan operasi yang diperlukan ketika perangkat pengontrol GPIO tidak lagi dapat diakses. Selama panggilan balik ini, driver pengontrol GPIO harus merilis sumber daya perangkat keras apa pun yang diperolehnya selama panggilan balik CLIENT_PrepareController sebelumnya.

Untuk mendaftarkan fungsi panggilan balik CLIENT_PrepareController driver Anda, panggil metode GPIO_CLX_RegisterClient . Metode ini menerima, sebagai parameter input, penunjuk ke struktur GPIO_CLIENT_REGISTRATION_PACKET yang berisi penunjuk fungsi CLIENT_PrepareController .

Meskipun fungsi panggilan balik CLIENT_PrepareController dipanggil di IRQL = PASSIVE_LEVEL, Anda tidak boleh membuat fungsi ini dapat di-pageable. Panggilan balik CLIENT_PrepareController berada di jalur waktu penting untuk memulihkan daya ke perangkat di platform perangkat keras dan, karena alasan performa, itu tidak boleh tertunda oleh kesalahan halaman.

Contoh

Untuk menentukan fungsi panggilan balik CLIENT_PrepareController , 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_PrepareController yang diberi nama MyEvtGpioPrepareController, gunakan jenis fungsi GPIO_CLIENT_PREPARE_CONTROLLER, seperti yang ditunjukkan dalam contoh kode ini:

GPIO_CLIENT_PREPARE_CONTROLLER MyEvtGpioPrepareController;

Kemudian, terapkan fungsi panggilan balik Anda sebagai berikut:

_Use_decl_annotations_
NTSTATUS
  MyEvtGpioPrepareController(
    WDFDEVICE Device,
    PVOID Context,
    WDFCMRESLIST ResourcesRaw,
    WDFCMRESLIST ResourcesTranslated
)
{ ... }

Jenis fungsi GPIO_CLIENT_PREPARE_CONTROLLER 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_PREPARE_CONTROLLER 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.