Fungsi ScsiPortGetDeviceBase (srb.h)

Artikel
03/08/2023

Rutinitas ScsiPortGetDeviceBase mengembalikan alamat dasar logis yang dipetakan yang dapat digunakan untuk berkomunikasi dengan HBA. Setiap driver miniport harus melewati alamat rentang akses logis yang dipetakan ke ScsiPort.. PortXxx dan ScsiPort.. Daftarkan rutinitas Xxx untuk berkomunikasi dengan HBA-nya.

Catatan Driver port SCSI dan model driver miniport SCSI dapat diubah atau tidak tersedia di masa mendatang. Sebagai gantinya, sebaiknya gunakan driver Storport dan model driver miniport Storport .

Sintaks

SCSIPORT_API PVOID ScsiPortGetDeviceBase(
  [in] PVOID                 HwDeviceExtension,
  [in] INTERFACE_TYPE        BusType,
  [in] ULONG                 SystemIoBusNumber,
  [in] SCSI_PHYSICAL_ADDRESS IoAddress,
  [in] ULONG                 NumberOfBytes,
  [in] BOOLEAN               InIoSpace
);

Parameter

[in] HwDeviceExtension

Arahkan ke ekstensi perangkat keras. Ini adalah area penyimpanan per HBA yang dialokasikan dan diinisialisasi driver port atas nama driver miniport. Driver Miniport biasanya menyimpan informasi khusus HBA dalam ekstensi ini, seperti status HBA dan rentang akses HBA yang dipetakan. Area ini tersedia untuk driver miniport di deviceExtension-HwDeviceExtension> anggota objek perangkat HBA segera setelah driver miniport memanggil ScsiPortInitialize. Pengandar porta membebaskan memori ini ketika melepas perangkat.

[in] BusType

Menentukan jenis antarmuka bus I/O tempat HBA terhubung. Rutinitas HwScsiFindAdapter driver miniport mendapatkan nilai untuk parameter ini dari anggota AdapterInterfaceType dari PORT_CONFIGURATION_INFORMATION input.

[in] SystemIoBusNumber

Menentukan nomor bus I/O yang ditetapkan sistem tempat HBA terhubung. Rutinitas HwScsiFindAdapter mendapatkan nilai untuk parameter ini dari anggota SystemIoBusNumber dari PORT_CONFIGURATION_INFORMATION input.

[in] IoAddress

Menentukan alamat dasar relatif bus dari rentang yang digunakan oleh HBA. Rutinitas HwScsiFindAdapter mendapatkan nilai untuk parameter ini dari salah satu elemen AccessRanges di PORT_CONFIGURATION_INFORMATION jika driver port menyediakan informasi konfigurasi rentang. Jika tidak, alamat ini dapat menjadi nilai yang dikembalikan oleh ScsiPortGetBusData atau nilai default yang disediakan driver miniport. Hindari menggunakan alamat dasar nol karena status pengembaliannya yang berhasil dapat bertentangan dengan status kesalahan (NULL).

[in] NumberOfBytes

Menentukan ukuran dalam byte rentang yang harus dicakup pemetaan. Rutinitas HwScsiFindAdapter mendapatkan nilai parameter ini dari elemen AccessRanges yang sama dengan IoAddress jika driver port memasok informasi konfigurasi rentang. Jika tidak, nilai ini dapat dikembalikan oleh ScsiPortGetBusData atau default yang disediakan driver miniport. Bagaimanapun, driver tidak boleh mengakses perangkat keras di luar rentang yang dikembalikan dan dipetakan.

[in] InIoSpace

TRUE menunjukkan rentang yang akan dipetakan berada di ruang I/O, dan driver miniport akan meneruskan alamat yang dipetakan dalam rentang ini ke ScsiPort... PortXxx untuk berkomunikasi dengan HBA. Rutinitas HwScsiFindAdapter mendapatkan nilai parameter ini dari elemen AccessRanges yang sama dengan IoAddress. Perhatikan bahwa driver miniport harus membalikkan nilai anggota InMemorySpace dalam elemen jenis ACCESS_RANGE sebelum diteruskan ke ScsiPortGetDeviceBase sebagai argumen InIoSpace . FALSE menunjukkan bahwa rentang yang akan dipetakan berada di ruang memori.

Nilai kembali

ScsiPortGetDeviceBase mengembalikan alamat dasar logis yang dipetakan untuk IoAddress yang diberikan jika berhasil memetakan rentang yang diberikan dari IoAddress ke NumberOfBytes. Jika rentang tertentu tidak dapat dipetakan, ScsiPortGetDeviceBase mengembalikan NULL.

Keterangan

Platform sistem operasi berbasis NT dapat memiliki beberapa jenis bus I/O dan beberapa bus I/O dengan jenis yang sama. Selain itu, HAL dapat memetakan ruang I/O ke memori di beberapa platform.

Akibatnya, pengemudi miniport tidak dapat menggunakan alamat rentang akses relatif bus untuk berkomunikasi dengan HBA-nya. Untuk mempertahankan portabilitas driver miniport di seluruh mesin berbasis CISC dan RISC, alamat yang mereka gunakan untuk mengakses HBA harus diterjemahkan dengan ScsiPortGetDeviceBase.

Setiap driver miniport harus menggunakan alamat rentang logis ruang sistem, yang dipetakan oleh ScsiPortGetDeviceBase, untuk berkomunikasi dengan HBA-nya. Panggilan ke ScsiPort... Rutinitas Port/RegisterXxx memerlukan alamat logis yang dipetakan ini.

ScsiPortGetDeviceBase dapat dipanggil beberapa kali, tergantung pada berapa banyak HBA yang didukung driver miniport dan berapa banyak rentang akses yang diperlukan setiap HBA. Setiap rentang yang dipetakan sesuai dengan rentang alamat perangkat relatif bus yang ditentukan dalam elemen jenis ACCESS_RANGE dari array AccessRanges .

ScsiPortGetDeviceBase hanya dapat dipanggil dari rutinitas HwScsiFindAdapter driver miniport atau dari HwScsiAdapterControl ketika jenis kontrolnya adalah ScsiSetRunningConfig. Panggilan dari rutinitas driver miniport lainnya akan mengakibatkan kegagalan sistem atau operasi yang salah untuk pemanggil.

Ikuti panduan berikut untuk memanggil ScsiPortGetDeviceBase:

Jika HwScsiFindAdapter menggunakan sekumpulan rentang akses atau nilai relatif bus default yang dikembalikan oleh ScsiPortGetBusData, ia harus memanggil ScsiPortValidateRange sebelum mencoba memanggil ScsiPortGetDeviceBase.
Jika HwScsiFindAdapter menentukan bahwa HBA tertentu bukan salah satu yang didukung driver miniport, ia harus memanggil ScsiPortFreeDeviceBase untuk merilis pemetaan yang disiapkannya untuk berkomunikasi dengan HBA tersebut.

Alamat logis yang dikembalikan oleh ScsiPortGetDeviceBase harus digunakan untuk semua referensi berikutnya yang dibuat ke perangkat keras tetapi tidak boleh ditambahkan ke spesifikasi AccessRanges apa pun di PORT_CONFIGURATION_INFORMATION. Penulis driver Miniport tidak boleh membuat asumsi tentang berapa banyak bit yang digunakan dalam alamat dasar logis yang dikembalikan oleh ScsiPortGetDeviceBase.

ScsiPortGetDeviceBase menggunakan SCSI_PHYSICAL_ADDRESS untuk mewakili alamat relatif bus.

typedef PHYSICAL_ADDRESS SCSI_PHYSICAL_ADDRESS, *PSCSI_PHYSICAL_ADDRESS;

Jenis SCSI_PHYSICAL_ADDRESS adalah jenis data independen sistem operasi yang digunakan driver miniport SCSI untuk mewakili alamat fisik atau alamat relatif bus.