HW_FIND_ADAPTER fungsi panggilan balik (storport.h)

Artikel
08/07/2023

Rutinitas HwStorFindAdapter menggunakan konfigurasi yang disediakan untuk menentukan apakah HBA tertentu didukung dan, jika ya, untuk mengembalikan informasi konfigurasi tentang adaptor tersebut.

Sintaks

HW_FIND_ADAPTER HwFindAdapter;

ULONG HwFindAdapter(
           PVOID DeviceExtension,
  [in]     PVOID HwContext,
  [in]     PVOID BusInformation,
  [in]     PCHAR ArgumentString,
  [in/out] PPORT_CONFIGURATION_INFORMATION ConfigInfo,
  [in]     PBOOLEAN Reserved3
)
{...}

Parameter

DeviceExtension

Memasok area penyimpanan per adaptor.

[in] HwContext

Atur ke NULL.

[in] BusInformation

Atur ke NULL.

[in] ArgumentString

Menyediakan string yang dihentikan NULL dengan informasi konteks tentang driver.

[in/out] ConfigInfo

Memasok struktur PORT_CONFIGURATION_INFORMATION yang diinisialisasi yang digunakan driver miniport selama inisialisasi.

[in] Reserved3

Dicadangkan untuk penggunaan sistem.

Nilai kembali

HwStorFindAdapter harus mengembalikan salah satu nilai status berikut:

Menampilkan kode	Deskripsi
SP_RETURN_FOUND	Menunjukkan bahwa HBA yang didukung ditemukan dan informasi konfigurasi yang relevan dengan HBA berhasil ditentukan dan diatur dalam struktur PORT_CONFIGURATION_INFORMATION .
SP_RETURN_ERROR	Menunjukkan bahwa HBA ditemukan tetapi ada kesalahan saat mendapatkan informasi konfigurasi. Jika memungkinkan, kesalahan seperti itu harus dicatat dengan StorPortLogError.
SP_RETURN_BAD_CONFIG	Menunjukkan bahwa informasi konfigurasi yang disediakan tidak valid untuk adaptor.
SP_RETURN_NOT_FOUND	Menunjukkan bahwa tidak ada HBA yang didukung yang ditemukan untuk informasi konfigurasi yang disediakan.

Keterangan

Karena driver Storport hanya mendukung perangkat Plug and Play (PnP), parameter HwContext dan BusInformation ke HwStorFindAdapter tidak disediakan untuk driver miniport non-virtual.

HwStorFindAdapter harus mengatur bidang MaximumTransferLength dan NumberOfPhysicalBreaks dalam struktur ConfigInfo . Selain bidang ini, struktur PORT_CONFIGURATION_INFORMATION akan selalu sepenuhnya menentukan semua sumber daya adaptor yang diperlukan untuk memulai adaptor.

Nama HwStorFindAdapter hanyalah tempat penampung. Prototipe aktual dari rutinitas ini didefinisikan dalam Storport.h sebagai berikut:

typedef
ULONG
HW_FIND_ADAPTER (
  _In_ PVOID  DeviceExtension,
  _In_ PVOID  HwContext,
  _In_ PVOID  BusInformation,
  _In_z_ PCHAR  ArgumentString,
  _Inout_ PPORT_CONFIGURATION_INFORMATION  ConfigInfo,
  _In_ PBOOLEAN  Reserved3
  );

Dalam kebanyakan kasus, StorPort memanggil rutinitas HwStorFindAdapter di IRQL == PASSIVE_LEVEL tanpa memperoleh kunci putar. Kasus pengecualian adalah ketika miniport tidak mendukung panggilan HwStorAdaptorControl dengan jenis kontrol ScsiRestartAdapter . Dalam situasi ini, StorPort akan menginisialisasi ulang adaptor dengan memanggil HwStorFindAdapter dan HwStorInitialize. Jika demikian, HwStorFindAdapter dipanggil di IRQL == DISPATCH_LEVEL. Selain itu, ketika dalam mode dump, HwStorFindAdapter dipanggil di IRQL == HIGH_LEVEL.

Contoh

Untuk menentukan fungsi panggilan balik HwStorFindAdapter , 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 rutinitas panggilan balik HwStorFindAdapter yang diberi nama MyHwFindAdapter, gunakan jenis HW_FIND_ADAPTER seperti yang ditunjukkan dalam contoh kode ini:

HW_FIND_ADAPTER MyHwFindAdapter;

Kemudian, terapkan rutinitas panggilan balik Anda sebagai berikut:

_Use_decl_annotations_
ULONG
MyHwFindAdapter (
  _In_ PVOID  DeviceExtension,
  _In_ PVOID  HwContext,
  _In_ PVOID  BusInformation,
  _In_z_ PCHAR  ArgumentString,
  _Inout_ PPORT_CONFIGURATION_INFORMATION  ConfigInfo,
  _In_ PBOOLEAN  Reserved3
  );
  {
      ...
  }

Jenis fungsi HW_FIND_ADAPTER ditentukan 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 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.