struktur HW_INITIALIZATION_DATA (srb.h)

Artikel
08/07/2023

Setiap rutinitas DriverEntry driver miniport SCSI harus diinisialisasi dengan nol dan, kemudian, mengisi informasi HW_INITIALIZATION_DATA (SCSI) yang relevan untuk driver port khusus OS.

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

typedef struct _HW_INITIALIZATION_DATA {
  ULONG               HwInitializationDataSize;
  INTERFACE_TYPE      AdapterInterfaceType;
  PHW_INITIALIZE      HwInitialize;
  PHW_STARTIO         HwStartIo;
  PHW_INTERRUPT       HwInterrupt;
  PHW_FIND_ADAPTER    HwFindAdapter;
  PHW_RESET_BUS       HwResetBus;
  PHW_DMA_STARTED     HwDmaStarted;
  PHW_ADAPTER_STATE   HwAdapterState;
  ULONG               DeviceExtensionSize;
  ULONG               SpecificLuExtensionSize;
  ULONG               SrbExtensionSize;
  ULONG               NumberOfAccessRanges;
  PVOID               Reserved;
  BOOLEAN             MapBuffers;
  BOOLEAN             NeedPhysicalAddresses;
  BOOLEAN             TaggedQueuing;
  BOOLEAN             AutoRequestSense;
  BOOLEAN             MultipleRequestPerLu;
  BOOLEAN             ReceiveEvent;
  USHORT              VendorIdLength;
  PVOID               VendorId;
  union {
    USHORT ReservedUshort;
    USHORT PortVersionFlags;
  };
  USHORT              DeviceIdLength;
  PVOID               DeviceId;
  PHW_ADAPTER_CONTROL HwAdapterControl;
} HW_INITIALIZATION_DATA, *PHW_INITIALIZATION_DATA;

Anggota

HwInitializationDataSize

Menentukan ukuran struktur ini dalam byte, seperti yang dikembalikan oleh sizeof(). Akibatnya, anggota ini menunjukkan versi struktur ini yang digunakan oleh driver miniport. Rutinitas DriverEntry driver miniport harus menetapkan nilai anggota ini untuk driver port.

AdapterInterfaceType

Menentukan jenis bus I/O yang terhubung dengan HBA, yang dapat berupa salah satu hal berikut: Internal, Isa, Eisa, MicroChannel, TurboChannel, atau PCIBus. Namun, jenis bus tambahan akan didukung di masa mendatang. Batas atas pada jenis bus yang didukung selalu MaximumInterfaceType.

Jika ini diatur ke PCIBus, driver miniport harus menyediakan nilai untuk anggota VendorIdLength, VendorId, DeviceIdLength, dan DeviceId , yang dijelaskan nanti.

HwInitialize

Arahkan ke rutinitas HwScsiInitialize driver miniport, yang merupakan titik masuk yang diperlukan untuk semua driver miniport. Prototipe untuk rutinitas ini PHW_INITIALIZE.

HwStartIo

Arahkan ke rutinitas HwScsiStartIo driver miniport, yang merupakan titik masuk yang diperlukan untuk semua driver miniport. Prototipe untuk rutinitas ini PHW_STARTIO.

HwInterrupt

Arahkan ke rutinitas HwScsiInterrupt driver miniport, yang merupakan titik masuk yang diperlukan untuk setiap driver miniport HBA yang menghasilkan gangguan. Atur ini ke NULL jika driver miniport tidak memerlukan ISR. Prototipe untuk rutinitas ini PHW_INTERRUPT.

HwFindAdapter

Pointer ke rutinitas HwScsiFindAdapter driver miniport, yang merupakan titik masuk yang diperlukan untuk semua driver miniport. Prototipe untuk rutinitas ini PHW_FIND_ADAPTER.

HwResetBus

Pointer ke rutinitas HwScsiResetBus driver miniport, yang merupakan titik masuk yang diperlukan untuk semua driver miniport. Prototipe untuk rutinitas ini PHW_RESET_BUS.

HwDmaStarted

Pointer ke rutinitas HwScsiDmaStarted driver miniport jika HBA-nya menggunakan DMA sistem, yaitu pengontrol DMA sistem. Atur ini ke NULL jika HBA adalah master bus atau menggunakan PIO. Prototipe untuk rutinitas ini PHW_DMA_STARTED.

HwAdapterState

Arahkan ke rutinitas HwScsiAdapterState driver miniport, yang merupakan titik masuk yang diperlukan untuk driver miniport HBA dengan BIOS yang terkait dengan driver port khusus platform x86 yang bergantung pada sistem operasi yang harus beralih antara mode prosesor x86 yang dilindungi dan nyata. Jika driver miniport tidak memerlukan rutinitas HwScsiAdapterState , atur anggota ini ke NULL. Driver miniport untuk HBA yang memiliki BIOS harus memiliki rutinitas HwScsiAdapterState agar kompatibel dengan driver port khusus x86 dan portabel ke lingkungan sistem operasi khusus x86. Prototipe untuk rutinitas ini PHW_ADAPTER_STATE.

DeviceExtensionSize

Menentukan ukuran dalam byte yang diperlukan oleh driver miniport untuk ekstensi perangkat per-HBA-nya. Driver miniport menggunakan ekstensi perangkatnya sebagai penyimpanan untuk informasi HBA yang ditentukan driver. Driver port khusus OS menginisialisasi setiap ekstensi perangkat yang dialokasikan dengan nol, dan meneruskan pointer ke ekstensi perangkat khusus HBA di setiap panggilan ke driver miniport kecuali rutinitas DriverEntry-nya . Ukuran yang diberikan tidak termasuk penyimpanan per unit-unit miniport yang diminta driver, yang dijelaskan berikutnya.

SpecificLuExtensionSize

Menentukan ukuran dalam byte yang diperlukan oleh driver miniport untuk penyimpanan per unit logisnya, jika ada. Driver miniport dapat menggunakan ekstensi LU-nya sebagai penyimpanan untuk informasi unit logis yang ditentukan pengemudi tentang periferal SCSI di bus. Driver port khusus OS menginisialisasi setiap ekstensi LU yang dialokasikannya dengan nol. Biarkan anggota ini diatur ke nol jika driver miniport tidak mempertahankan informasi per LU yang memerlukan penyimpanan. Nilai ini didasarkan pada asumsi bahwa HBA dapat menerima alamat 32-bit, terlepas dari apa yang sebenarnya dapat didukung oleh pengontrol. Jika ruang tambahan diperlukan dalam ekstensi LUN atau SRB untuk menangani alamat 64-bit, maka penyesuaian yang sesuai harus dilakukan pada nilai ini sebelum menggunakannya dengan rutinitas seperti ScsiPortGetUncachedExtension.

SrbExtensionSize

Menentukan ukuran dalam byte yang diperlukan oleh driver miniport untuk penyimpanan per permintaannya, jika ada. Driver miniport dapat menggunakan ekstensi SRB sebagai penyimpanan untuk informasi khusus permintaan yang ditentukan driver, seperti data yang diperlukan untuk memproses permintaan tertentu. Driver port khusus OS tidak menginisialisasi ekstensi SRB, tetapi mengatur pointer ke penyimpanan ini di setiap SRB yang dikirimnya ke driver miniport. Ekstensi SRB dapat diakses dengan aman oleh perangkat keras HBA. Biarkan anggota ini diatur ke nol jika driver miniport tidak mempertahankan informasi per-SRB yang memerlukan penyimpanan. Nilai ini didasarkan pada asumsi bahwa HBA dapat menerima alamat 32-bit, terlepas dari apa yang sebenarnya dapat didukung oleh pengontrol. Jika ruang tambahan diperlukan dalam ekstensi LUN atau SRB untuk menangani alamat 64-bit, maka penyesuaian yang sesuai harus dilakukan pada nilai ini sebelum menggunakannya dengan rutinitas seperti ScsiPortGetUncachedExtension.

NumberOfAccessRanges

Menentukan berapa banyak rentang akses yang digunakan adaptor. Masing-masing adalah rentang alamat memori atau alamat port I/O. HBA yang khas menggunakan dua rentang, satu untuk port I/O-nya dan satu lagi untuk rentang memori perangkatnya.

Reserved

Dicadangkan untuk penggunaan sistem dan tidak tersedia untuk digunakan oleh driver miniport.

MapBuffers

Menunjukkan, ketika TRUE, semua alamat buffer data harus dipetakan ke alamat virtual untuk akses oleh driver miniport. Ketika FALSE, alamat buffer data tidak harus dipetakan ke alamat virtual.

NeedPhysicalAddresses

Menunjukkan, ketika TRUE, bahwa driver miniport perlu menerjemahkan perangkatnya, per-LU, dan alamat ekstensi per SRB apa pun, serta alamat buffer SRB, ke alamat fisik, seperti yang diperlukan oleh HBA. Ketika FALSE, tidak ada alamat ini yang harus diterjemahkan ke alamat fisik.

TaggedQueuing

Menunjukkan, ketika TRUE, driver miniport tersebut dapat mendukung antrean bertag SCSI. Ketika FALSE, driver miniport tidak dapat mendukung antrean bertag SCSI.

AutoRequestSense

Menunjukkan, ketika TRUE, bahwa HBA dapat melakukan operasi request-sense tanpa memerlukan permintaan eksplisit untuk melakukannya. Ketika FALSE, HBA memerlukan permintaan eksplisit sebelum dapat melakukan operasi request-sense. Hanya driver miniport yang mengendarai HBA dengan firmware bawaan untuk melakukan operasi request-sense yang harus mengatur anggota ini ke TRUE.

MultipleRequestPerLu

Menunjukkan, ketika TRUE, bahwa driver miniport dapat mengantre beberapa permintaan per unit logis, khususnya, dalam HBA. Ketika FALSE, driver miniport tidak dapat mengantre beberapa permintaan per unit logis. Perhatikan bahwa HBA harus mendukung pengertian permintaan otomatis agar driver miniport-nya dapat mengaktifkan fungsionalitas ini. Jika driver miniport mengatur anggota ini ke TRUE, driver harus menggunakan setiap anggota SRB QueueTag untuk permintaan jenis ini, tetapi SRB_FLAGS_QUEUE_ACTION_ENABLE tidak diatur dalam anggota SrbFlags dari struktur SCSI_REQUEST_BLOCK.

ReceiveEvent

Menunjukkan, ketika TRUE, bahwa driver miniport mengendarai HBA yang dapat mendukung SRB peristiwa penerimaan untuk peristiwa asinkron SCSI. Ketika FALSE, HBA tidak dapat mendukung SRB peristiwa penerimaan untuk peristiwa asinkron SCSI.

VendorIdLength

Menentukan ukuran dalam byte string VendorId , yang dijelaskan berikutnya.

VendorId

Arahkan ke string byte ASCII yang mengidentifikasi produsen HBA. Anggota ini tidak relevan untuk driver Plug and Play.

Jika AdapterInterfaceType yang diberikan adalah PCIBus, ID vendor adalah nilai USHORT yang dialokasikan oleh PCI SIG, yang harus dikonversi menjadi string byte oleh driver miniport. Misalnya, jika nilai ID vendor PCI yang ditetapkan adalah 1001, string VendorId yang disediakan driver miniport adalah ('1', '0', '0', '1').

ReservedUshort

Dicadangkan untuk penggunaan sistem dan tidak tersedia untuk digunakan oleh driver miniport.

PortVersionFlags

DeviceIdLength

Menentukan ukuran dalam byte string DeviceId , yang dijelaskan berikutnya.

DeviceId

Arahkan ke string byte ASCII yang mengidentifikasi model HBA yang didukung oleh driver miniport. Anggota ini tidak relevan untuk driver Plug and Play.

Jika AdapterInterfaceType yang diberikan adalah PCIBus, ID perangkat adalah nilai USHORT yang ditetapkan oleh produsen HBA. Driver miniport harus mengonversi nilai ID perangkat PCI apa pun untuk HBA yang dapat didukungnya menjadi string byte DeviceId , seperti untuk anggota VendorId . Misalnya, jika driver miniport dapat mendukung HBA dengan ID perangkat PCI 8040 dan 8050, itu mungkin mengatur DeviceId dengan pointer ke string byte ('8', '0').

HwAdapterControl

Arahkan ke rutinitas HwScsiAdapterControl driver miniport, yang merupakan titik masuk yang diperlukan untuk semua driver miniport PnP. Atur ini ke NULL jika driver miniport tidak mendukung Plug and Play.

Keterangan

Setiap driver miniport harus menginisialisasi struktur HW_INITIALIZATION_DATA dengan nol sebelum menetapkan nilai anggota yang relevan dalam struktur ini dan memanggil ScsiPortInitialize.

Anggota HW_INITIALIZATION_DATA Dma64BitAddresses telah dihilangkan di Windows 2000 (Lihat diskusi di bawah PORT_CONFIGURATION_DATA untuk detail lebih lanjut).

Baik HW_INITIALIZATION_DATA maupun PORT_CONFIGURATION_INFORMATION memiliki sepasang anggota yang disebut SpecificLuExtensionSize dan SrbExtensionSize yang nilainya ditangani secara berbeda dari sebelumnya ke Windows 2000. Driver miniport harus menghitung nilai awal SpecificLuExtensionSize dan SrbExtensionSize dalam HW_INITIALIZATION_DATA berdasarkan asumsi bahwa HBA mampu menangani alamat 32-bit, terlepas dari apa yang sebenarnya dapat didukung oleh pengontrol. (Lihat diskusi di bawah PORT_CONFIGURATION_DATA untuk detail lebih lanjut.)