VIRTUAL_HW_FIND_ADAPTER fungsi panggilan balik (storport.h)

Artikel
08/07/2023

Miniport virtual Storport menggunakan informasi konfigurasi yang disediakan ke rutinitas VIRTUAL_HW_FIND_ADAPTER untuk menginisialisasi dirinya lebih lanjut.

Sintaks

VIRTUAL_HW_FIND_ADAPTER VirtualHwFindAdapter;

ULONG VirtualHwFindAdapter(
  PVOID DeviceExtension,
  PVOID HwContext,
  PVOID BusInformation,
  PVOID LowerDevice,
  PCHAR ArgumentString,
  PPORT_CONFIGURATION_INFORMATION ConfigInfo,
  PBOOLEAN Again
)
{...}

Parameter

DeviceExtension

Penunjuk ke area penyimpanan non-halaman per adaptor driver miniport. Driver port khusus sistem operasi mengalokasikan memori untuk dan menginisialisasi ekstensi ini dengan nol sebelum memanggil rutinitas VIRTUAL_HW_FIND_ADAPTER miniport.

HwContext

Penunjuk ke PDO di tumpukan perangkat. HBA itu sendiri adalah FDO. PDO mungkin milik driver Pci.sys jika driver miniport mengontrol perangkat keras fisik. Tetapi dalam kasus driver miniport virtual, PDO milik manajer PnP.

BusInformation

Penunjuk ke objek perangkat fungsi miniport (FDO).

LowerDevice

Penunjuk ke objek perangkat yang dikendalikan oleh FDO miniport.

ArgumentString

Penunjuk ke string ASCII yang dihentikan null. String ini, jika disediakan, berisi informasi perangkat dari registri seperti parameter dasar.

ConfigInfo

Penunjuk ke struktur PORT_CONFIGURATION_INFORMATION . Driver port menginisialisasi struktur ini dengan informasi konfigurasi yang diketahui, seperti nilai yang ditetapkan DriverEntry driver miniport dalam VIRTUAL_HW_INITIALIZATION_DATA. VIRTUAL_HW_FIND_ADAPTER harus menggunakan informasi yang disediakan untuk menentukan apakah HBA virtual yang dijelaskannya adalah salah satu yang didukung driver miniport. Jika demikian, VIRTUAL_HW_FIND_ADAPTER menginisialisasi dan mengonfigurasi HBA tersebut dan mengisi informasi konfigurasi yang hilang. Jika memungkinkan, driver miniport harus memiliki nilai konfigurasi default untuk setiap jenis HBA yang didukungnya, jika driver port yang bergantung pada sistem operasi tidak dapat menyediakan informasi konfigurasi tambahan yang tidak disediakan oleh rutinitas DriverEntry driver miniport.

Again

Tidak digunakan.

Mengembalikan nilai

VIRTUAL_HW_FIND_ADAPTER harus mengembalikan salah satu nilai status berikut:

Menampilkan kode	Deskripsi
SP_RETURN_FOUND	HBA yang didukung ditemukan dan bahwa informasi konfigurasi yang relevan dengan HBA berhasil ditentukan dan diatur dalam struktur PORT_CONFIGURATION_INFORMATION .
SP_RETURN_ERROR	HBA ditemukan, tetapi terjadi kesalahan ketika memperoleh informasi konfigurasi. Jika memungkinkan, kesalahan seperti itu harus dicatat dengan ScsiPortLogError.
SP_RETURN_BAD_CONFIG	Informasi konfigurasi yang disediakan tidak valid untuk adaptor.
SP_RETURN_NOT_FOUND	Tidak ada HBA yang didukung yang ditemukan untuk informasi konfigurasi yang disediakan.

Keterangan

Bidang VirtualDevice dalam struktur informasi konfigurasi harus diatur ke TRUE. Bidang lain dapat diatur sesuai kebutuhan.

Driver port memanggil VIRTUAL_HW_FIND_ADAPTER Storport virtual miniport di PASSIVE_LEVEL.

Nama VirtualHwStorFindAdapter adalah teks tempat penampung untuk nama rutin aktual. Prototipe aktual dari rutinitas ini didefinisikan dalam Srb.h sebagai berikut:

typedef
ULONG
VIRTUAL_HW_FIND_ADAPTER (
  _In_ PVOID  DeviceExtension,
  _In_ PVOID  HwContext,
  _In_ PVOID  BusInformation,
  _In_ PVOID  LowerDevice,
  _In_ PCHAR  ArgumentString,
  _Inout_ PPORT_CONFIGURATION_INFORMATION  ConfigInfo,
  _Out_ PBOOLEAN Again
  );

Contoh

Untuk menentukan fungsi panggilan balik VIRTUAL_HW_FIND_ADAPTER , Anda harus terlebih dahulu memberikan deklarasi fungsi yang mengidentifikasi jenis fungsi panggilan balik yang Anda tentukan. Windows menyediakan sekumpulan tipe fungsi panggilan balik untuk driver. 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 rutinitas panggilan balik VIRTUAL_HW_FIND_ADAPTER yang bernama MyVirtualHwFindAdapter, gunakan jenis VIRTUAL_HW_FIND_ADAPTER seperti yang ditunjukkan dalam contoh kode ini:

VIRTUAL_HW_FIND_ADAPTER MyVirtualHwFindAdapter;

Kemudian, terapkan rutinitas panggilan balik Anda sebagai berikut:

_Use_decl_annotations_
ULONG
MyVirtualHwFindAdapter (
  _In_ PVOID  DeviceExtension,
  _In_ PVOID  HwContext,
  _In_ PVOID  BusInformation,
  _In_ PVOID  LowerDevice,
  _In_ PCHAR  ArgumentString,
  _Inout_ PPORT_CONFIGURATION_INFORMATION  ConfigInfo,
  _Out_ PBOOLEAN Again
  );
  {
      ...
  }

Jenis fungsi VIRTUAL_HW_FIND_ADAPTER didefinisikan dalam file header Storport.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 VIRTUAL_HW_FIND_ADAPTER dalam file header digunakan. Untuk informasi selengkapnya tentang persyaratan untuk deklarasi fungsi, lihat Mendeklarasikan Fungsi Menggunakan Jenis Peran Fungsi untuk Driver Storport. Untuk informasi tentang Use_decl_annotations, lihat Perilaku Fungsi Anotasi.