MINIPORT_PNP_IRP fungsi panggilan balik (ndis.h)

Artikel
08/07/2023

Fungsi MiniportPnpIrp memungkinkan driver miniport mengelola sumber daya Plug and Play (PnP) secara opsional. MiniportPnpIrp sendiri tidak pernah didefinisikan oleh driver miniport secara langsung. Sebaliknya, ini didefinisikan baik sebagai MiniportFilterResourceRequirements atau MiniportStartDevice.

Jika didefinisikan sebagai MiniportFilterResourceRequirements, fungsi ini memungkinkan driver miniport untuk memodifikasi persyaratan sumber daya untuk perangkat. Jika didefinisikan sebagai MiniportStartDevice, fungsi ini memungkinkan driver miniport untuk menghapus sumber daya yang ditambahkan di Fungsi MiniportFilterResourceRequirements .

Catatan Anda harus mendeklarasikan fungsi ini dengan menggunakan jenis MINIPORT_FILTER_RESOURCE_REQUIREMENTS atau jenis MINIPORT_START_DEVICE . Untuk informasi selengkapnya, lihat bagian Contoh berikut ini.

Sintaks

MINIPORT_PNP_IRP MiniportPnpIrp;

NDIS_STATUS MiniportPnpIrp(
  [in] NDIS_HANDLE MiniportAddDeviceContext,
  [in] PIRP Irp
)
{...}

Parameter

[in] MiniportAddDeviceContext

Handel untuk area konteks yang dialokasikan driver yang didaftarkan driver miniport dengan NDIS dalam fungsi MiniportAddDevice .

[in] Irp

Jika fungsi ini didefinisikan sebagai MiniportFilterResourceRequirements, parameter ini adalah penunjuk ke IRP_MN_FILTER_RESOURCE_REQUIREMENTS untuk ditangani driver.

Jika fungsi ini didefinisikan sebagai MiniportStartDevice, parameter ini adalah penunjuk ke IRP IRP_MN_START_DEVICE .

Nilai kembali

MiniportPnpIrp mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
NDIS_STATUS_SUCCESS	Driver miniport berhasil menangani permintaan perangkat mulai.
NDIS_STATUS_RESOURCES	Driver miniport tidak dapat menangani permintaan perangkat mulai karena sumber daya rendah.
NDIS_STATUS_FAILURE	MiniportFilterResourceRequirements gagal karena alasan selain sumber daya yang tidak mencukupi.

Keterangan

Komentar MiniportFilterResourceRequirements

Fungsi MiniportFilterResourceRequirements adalah fungsi opsional. Driver Miniport harus mendaftarkan fungsi ini jika mereka mendukung MSI-X dan setidaknya salah satu hal berikut ini benar:

Driver memerlukan kemampuan untuk mengubah afinitas interupsi untuk setiap pesan MSI-X.
Driver akan mendaftar untuk interupsi berbasis baris di Fungsi MiniportInitializeEx .

Untuk mendaftarkan MiniportFilterResourceRequirements, tentukan titik masuk di NDIS_MINIPORT_PNP_CHARACTERISTICS struktur.

NDIS memanggil fungsi MiniportFilterResourceRequirements setelah NDIS menerima IRP_MN_FILTER_RESOURCE_REQUIREMENTS IRP untuk kartu antarmuka jaringan (NIC). NDIS memanggil MiniportFilterResourceRequirements setelah driver fungsi yang mendasar di tumpukan perangkat telah menyelesaikan pemrosesan IRP.

Driver miniport harus siap untuk menangani IRP_MN_FILTER_RESOURCE_REQUIREMENTS dari MiniportFilterResourceRequirements segera setelah fungsi MiniportAddDevice mengembalikan NDIS_STATUS_SUCCESS.

Driver miniport dapat mengatur kebijakan afinitas untuk setiap sumber daya jenis CmResourceTypeInterrupt yang menjelaskan pesan MSI-X. Jika kebijakan afinitas meminta penargetan untuk serangkaian prosesor tertentu, driver miniport juga menetapkan masker KAFFINITY pada anggota Interrupt.TargetedProcessors dalam struktur IO_RESOURCE_DESCRIPTOR .

Jika driver miniport NDIS 6.1 atau yang lebih baru memerlukan lebih banyak sumber daya interupsi pesan, itu dapat menambahkan lebih banyak sumber daya interupsi pesan ke daftar sumber daya. Jika sistem operasi dapat menyediakan lebih banyak sumber daya interupsi pesan, adaptor miniport menerima sumber daya interupsi pesan tambahan saat dimulai.

Setiap sumber daya interupsi pesan dalam daftar diberi nomor pesan yang sesuai dengan urutan yang ada dalam daftar sumber daya. Pesan dinomor dari 0 hingga jumlah total sumber daya interupsi pesan dikurangi satu.

Untuk menetapkan entri tabel MSI-X ke CPU pada waktu proses, driver miniport dapat memanggil Fungsi NdisMConfigMSIXTableEntry .

Driver miniport dapat menghapus semua sumber daya jenis CmResourceTypeInterrupt yang merupakan sumber daya interupsi pesan. Driver kemudian dapat mendaftar untuk interupsi berbasis baris dalam fungsi MiniportInitializeEx . Jika driver miniport tidak menghapus sumber daya interupsi pesan ini, sistem operasi akan gagal jika driver mencoba mendaftarkan gangguan berbasis baris di MiniportInitializeEx.

Untuk mengalokasikan memori untuk daftar persyaratan sumber daya baru, gunakan Fungsi NdisAllocateMemoryWithTagPriority . Driver miniport dapat membebaskan memori untuk daftar persyaratan sumber daya lama dengan fungsi NdisFreeMemory . Manajer PnP membebaskan memori yang dialokasikan driver setelah IRP terkait selesai.

Driver Miniport tidak boleh memodifikasi sumber daya lain, seperti sumber daya CmResourceTypeMemory dan CmResourceTypePort . Driver miniport harus menghindari penambahan sumber daya baru ke daftar sumber daya. Namun, driver miniport dapat menambahkan lebih banyak sumber daya interupsi pesan. Jika driver miniport menambahkan lebih banyak sumber daya interupsi pesan, driver tidak boleh menghapusnya dari fungsi MiniportStartDevice .

Jika driver miniport mengembalikan NDIS_STATUS_RESOURCES atau NDIS_STATUS_FAILURE dari MiniportFilterResourceRequirements, NDIS akan menggunakan persyaratan sumber daya seperti yang ditentukan oleh driver bus induk.

NDIS dapat memanggil MiniportFilterResourceRequirements beberapa kali sebelum NDIS memanggil fungsi MiniportRemoveDevice . Tetapi NDIS memanggil MiniportFilterResourceRequirements hanya ketika perangkat dalam keadaan dihentikan.

NDIS memanggil MiniportFilterResourceRequirements di IRQL = PASSIVE_LEVEL.

Contoh MiniportFilterResourceRequirements

Untuk menentukan fungsi MiniportFilterResourceRequirements , Anda harus terlebih dahulu memberikan deklarasi fungsi yang mengidentifikasi jenis fungsi yang Anda tentukan. Windows menyediakan sekumpulan tipe fungsi untuk pengandar. Mendeklarasikan fungsi menggunakan jenis fungsi 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 MiniportFilterResourceRequirements yang diberi nama "MyFilterResourceRequirements", gunakan jenis MINIPORT_FILTER_RESOURCE_REQUIREMENTS seperti yang ditunjukkan dalam contoh kode ini:

MINIPORT_FILTER_RESOURCE_REQUIREMENTS MyFilterResourceRequirements;

Kemudian, terapkan fungsi Anda sebagai berikut:

_Use_decl_annotations_
NDIS_STATUS
 MyFilterResourceRequirements(
    NDIS_HANDLE  MiniportAddDeviceContext,
    PIRP  Irp
    )
  {...}

Jenis fungsi MINIPORT_FILTER_RESOURCE_REQUIREMENTS didefinisikan dalam file header Ndis.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 MINIPORT_FILTER_RESOURCE_REQUIREMENTS dalam file header digunakan. Untuk informasi selengkapnya tentang persyaratan untuk deklarasi fungsi, lihat Mendeklarasikan Fungsi dengan Menggunakan Jenis Peran Fungsi untuk Driver NDIS.

Untuk informasi tentang Use_decl_annotations, lihat Perilaku Fungsi Anotasi.

Komentar MiniportStartDevice

MiniportStartDevice adalah fungsi opsional. Driver miniport yang mendukung MSI-X dapat menentukan titik masuk untuk fungsi ini dalam NDIS_MINIPORT_PNP_CHARACTERISTICS struktur. Ketika NDIS menerima permintaan dari manajer Plug and Play (PnP) untuk memulai perangkat, NDIS memanggil fungsi MiniportStartDevice, jika ada. Jika driver miniport menambahkan sumber daya baru di Fungsi MiniportFilterResourceRequirements harus menyediakan fungsi MiniportStartDevice untuk menghapus sumber daya.

Jika driver miniport memodifikasi sumber daya sia-sia sehingga driver bus yang mendasar tidak dapat mengenali sumber daya, driver harus menyediakan fungsi MiniportStartDevice untuk menghapus sumber daya. Driver bus yang mendasar mungkin menggagalkan permintaan perangkat mulai jika tidak mengenali sumber daya yang ditambahkan driver miniport di MiniportFilterResourceRequirements. Jika driver miniport menambahkan sumber daya interupsi pesan, driver tidak boleh menghapusnya dari MiniportStartDevice.

NDIS memanggil MiniportStartDevice sebelum meneruskan permintaan perangkat mulai ke driver yang mendasar. Jika driver yang mendasar berhasil menyelesaikan permintaan, NDIS memanggil fungsi MiniportInitializeEx untuk menginisialisasi adaptor miniport.

NDIS memanggil MiniportStartDevice di IRQL = PASSIVE_LEVEL.

Contoh MiniportStartDevice

Untuk menentukan fungsi MiniportStartDevice , Anda harus terlebih dahulu memberikan deklarasi fungsi yang mengidentifikasi jenis fungsi yang Anda tentukan. Windows menyediakan sekumpulan tipe fungsi untuk pengandar. Mendeklarasikan fungsi menggunakan jenis fungsi 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 MiniportStartDevice yang diberi nama "MyStartDevice", gunakan jenis MINIPORT_START_DEVICE seperti yang ditunjukkan dalam contoh kode ini:

MINIPORT_START_DEVICE MyStartDevice;

Kemudian, terapkan fungsi Anda sebagai berikut:

_Use_decl_annotations_
NDIS_STATUS
 MyStartDevice(
    NDIS_HANDLE  MiniportAddDeviceContext,
    PIRP  Irp
    )
  {...}

Jenis fungsi MINIPORT_START_DEVICE didefinisikan dalam file header Ndis.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 MINIPORT_START_DEVICE dalam file header digunakan. Untuk informasi selengkapnya tentang persyaratan untuk deklarasi fungsi, lihat Mendeklarasikan Fungsi dengan Menggunakan Jenis Peran Fungsi untuk Driver NDIS.

Untuk informasi tentang Use_decl_annotations, lihat Perilaku Fungsi Anotasi.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Didukung di NDIS 6.0 dan yang lebih baru.
Target Platform	Windows
Header	ndis.h (termasuk Ndis.h)
IRQL	PASSIVE_LEVEL