Fungsi StorPortBuildScatterGatherList (storport.h)

Artikel
08/07/2023

Rutinitas StorPortBuildScatterGatherList membuat daftar sebar/kumpulkan untuk buffer data yang ditentukan.

Sintaks

ULONG StorPortBuildScatterGatherList(
  [in]      PVOID                        HwDeviceExtension,
  [in]      PVOID                        Mdl,
  [in]      PVOID                        CurrentVa,
  [in]      ULONG                        Length,
  [in]      PPOST_SCATTER_GATHER_EXECUTE ExecutionRoutine,
  [in]      PVOID                        Context,
  [in]      BOOLEAN                      WriteToDevice,
  [in, out] PVOID                        ScatterGatherBuffer,
  [in]      ULONG                        ScatterGatherBufferLength
);

Parameter

[in] HwDeviceExtension

Penunjuk ke ekstensi perangkat keras untuk adaptor bus host (HBA).

[in] Mdl

Penunjuk ke daftar deskriptor memori (MDL) yang menjelaskan halaman memori yang terkait dengan buffer data.

[in] CurrentVa

Alamat virtual buffer data.

[in] Length

Panjang, dalam byte, dari buffer data.

[in] ExecutionRoutine

Penunjuk ke ExecutionRoutine yang disediakan driver miniport. Driver Storport memanggil rutinitas ini setelah membuat daftar sebar/kumpulkan. Driver miniport harus melakukan semua operasi yang menggunakan daftar sebar/kumpulkan di dalam rutinitas eksekusi, bukan dalam kode yang mengikuti panggilan ke rutinitas StorPortBuildScatterGatherList .

ExecutionRoutine dinyatakan sebagai berikut:

VOID
ExecutionRoutine (
    IN PVOID  *DeviceObject,
    IN PVOID  *Irp,
    IN PSTOR_SCATTER_GATHER_LIST  ScatterGather,
    IN PVOID  Context
    );

DeviceObject

Driver Miniport harus mengabaikan parameter ini.

Irp

Driver Miniport harus mengabaikan parameter ini.

ScatterGather

Penunjuk ke struktur STOR_SCATTER_GATHER_LIST yang berisi daftar sebar/kumpulkan untuk buffer data yang ditentukan.

Konteks

Nilai konteks yang ditentukan dalam parameter Konteks fungsi StorPortBuildScatterGatherList.

Driver Storport memanggil ExecutionRoutine driver miniport di IRQL = DISPATCH_LEVEL.

[in] Context

Nilai konteks yang diteruskan driver port ke rutinitas eksekusi yang ditentukan dalam parameter ExecutionRoutine . Rutinitas eksekusi menggunakan nilai ini untuk mengidentifikasi permintaan secara unik.

[in] WriteToDevice

Nilai yang menunjukkan arah transfer DMA. Nilai TRUE menunjukkan transfer yang berasal dari buffer data ke perangkat, dan nilai FALSE menunjukkan transfer yang berasal dari perangkat ke buffer data.

[in, out] ScatterGatherBuffer

Penunjuk ke buffer yang disediakan miniport yang menerima daftar sebar/kumpulkan. Driver miniport dapat mengalokasikan memori untuk buffer ini dengan memanggil rutinitas StorPortAllocatePool .

[in] ScatterGatherBufferLength

Ukuran, dalam byte, dari buffer yang diacu oleh parameter ScatterGatherBuffer .

Nilai kembali

StorPortBuildScatterGatherList mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
STOR_STATUS_NOT_IMPLEMENTED	Fungsi ini tidak diimplementasikan pada sistem operasi aktif.
STOR_STATUS_SUCCESS	Menunjukkan bahwa rutinitas berhasil membuat daftar sebar/kumpulkan. Penting Lihat 'Komentar'.
STOR_STATUS_INVALID_PARAMETER	HwDeviceExtension yang dilewatkan adalah NULL.
STOR_STATUS_INVALID_IRQL	Panggilan dilakukan pada IRQL yang tidak valid.
STOR_STATUS_INSUFFICIENT_RESOURCES	Sistem tidak memiliki cukup daftar peta yang tersedia untuk transfer.
STOR_STATUS_BUFFER_TOO_SMALL	Parameter Panjang terlalu besar agar pas dalam buffer.

Keterangan

Driver miniport memanggil StorPortPutScatterGatherList untuk merilis sumber daya yang dialokasikan StorPortBuildScatterGatherList saat membuat daftar sebar/kumpulkan.

Driver miniport harus memanggil StorPortPutScatterGatherList sebelum membebaskan atau menggunakan kembali memori yang dialokasikan untuk daftar sebar/kumpulkan.

Catatan Jika StorPortBuildScatterGatherList mengembalikan STOR_STATUS_SUCCESS, maka panggilan balik di ExecutionRoutine berhasil diantrekan untuk dijalankan setelah daftar sebar/kumpulkan dibuat. Miniport tidak boleh berasumsi bahwa ExecutionRoutine dipanggil atau bahwa daftar sebar/kumpulkan siap ketika StorPortBuildScatterGatherList kembali. Jika perlu, miniport dapat menyinkronkan eksekusi kode setelah StorPortBuildScatterGatherList dengan panggilan balik di ExecutionRoutine untuk memastikan bahwa daftar sebar/kumpulkan tersedia.

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Header	storport.h (termasuk Storport.h)
IRQL	DISPATCH_LEVEL

Lihat juga

STOR_SCATTER_GATHER_LIST

StorPortAllocatePool

StorPortPutScatterGatherList

Bagikan melalui