PMAP_TRANSFER_EX fungsi panggilan balik (wdm.h)

Artikel
03/14/2023

Rutinitas MapTransferEx menyiapkan register peta untuk memetakan alamat fisik dalam daftar sebar/kumpulkan ke alamat logis yang diperlukan untuk melakukan transfer DMA.

Sintaks

PMAP_TRANSFER_EX PmapTransferEx;

NTSTATUS PmapTransferEx(
  [in]            PDMA_ADAPTER DmaAdapter,
  [in]            PMDL Mdl,
  [in]            PVOID MapRegisterBase,
  [in]            ULONGLONG Offset,
  [in]            ULONG DeviceOffset,
  [in, out]       PULONG Length,
  [in]            BOOLEAN WriteToDevice,
  [out, optional] PSCATTER_GATHER_LIST ScatterGatherBuffer,
  [in]            ULONG ScatterGatherBufferLength,
  [in, optional]  PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
  [in, optional]  PVOID CompletionContext
)
{...}

Parameter

[in] DmaAdapter

Penunjuk ke struktur DMA_ADAPTER . Struktur ini adalah objek adaptor yang mewakili perangkat DMA master bus driver atau saluran DMA sistem. Penelepon memperoleh pointer ini dari panggilan sebelumnya ke rutinitas IoGetDmaAdapter .

[in] Mdl

Penunjuk ke rantai MDL yang menjelaskan tata letak halaman fisik untuk kumpulan buffer terkunci dalam memori virtual. Daftar sebar/kumpulkan untuk transfer DMA akan menggunakan wilayah memori ini yang ditentukan oleh parameter Offset dan Panjang . Untuk informasi selengkapnya tentang rantai MDL, lihat Menggunakan MDL.

[in] MapRegisterBase

Handel ke register peta yang dialokasikan untuk objek adaptor. Pemanggil sebelumnya memperoleh handel ini dari rutinitas AllocateAdapterChannelEx .

[in] Offset

Offset byte dari awal memori yang dijelaskan oleh rantai MDL. Offset ini menentukan awal buffer data I/O yang digunakan untuk transfer DMA. Jika daftar sebar/kumpulkan diberikan ke pemanggil, offset ini menentukan alamat awal fragmen buffer pertama dalam daftar. Jika MDL dalam rantai MDL menjelaskan total N byte memori, nilai Offset yang valid berada dalam rentang 0 hingga N–1. Untuk informasi selengkapnya, lihat Keterangan.

[in] DeviceOffset

Offset byte dari register data perangkat target atau FIFO dari alamat dasar perangkat. Parameter ini berlaku untuk perangkat yang memiliki beberapa FIFO yang dapat diakses oleh pengontrol DMA sistem. Parameter ini hanya digunakan untuk transfer DMA sistem. Untuk transfer bus-master, atur parameter ini ke nol.

[in, out] Length

Penunjuk ke variabel yang berisi panjang, dalam byte, dari buffer data I/O yang digunakan untuk transfer DMA. Pada entri, variabel ini berisi panjang yang diminta oleh driver panggilan. Sebelum kembali, rutin menulis panjang aktual buffer yang dipetakan ke variabel ini. Nilai *Panjang saat kembali dari MapTransferEx menunjukkan berapa banyak byte yang dipetakan. Jika jumlah register peta dan ukuran buffer sebar/kumpulkan cukup untuk memetakan seluruh panjang yang diminta oleh pemanggil, nilai input dan output *Length identik. Jika MDL dalam rantai MDL menjelaskan total N byte memori, nilai *Panjang yang valid berada dalam rentang 0 hingga N–Offset.

[in] WriteToDevice

Arah transfer DMA. Atur parameter ini ke TRUE untuk operasi tulis, yang mentransfer data ke perangkat dari memori. Atur parameter ini ke FALSE untuk operasi baca, yang mentransfer data dari perangkat ke memori.

[out, optional] ScatterGatherBuffer

Penunjuk ke buffer yang dialokasikan pemanggil tempat rutin menulis daftar sebar/kumpulkan untuk transfer DMA. Daftar ini dimulai dengan struktur SCATTER_GATHER_LIST , yang segera diikuti oleh array SCATTER_GATHER_ELEMENT . Untuk driver yang menggunakan perangkat DMA master bus, ScatterGatherBuffer adalah parameter yang diperlukan. Untuk driver yang menggunakan pengontrol DMA sistem, parameter ScatterGatherBuffer bersifat opsional dan dapat berupa NULL. Untuk informasi selengkapnya, lihat Keterangan.

[in] ScatterGatherBufferLength

Ukuran, dalam byte, dari buffer yang dituju oleh parameter ScatterGatherBuffer . Ukuran buffer yang dialokasikan harus cukup besar untuk berisi daftar sebar/kumpulkan, ditambah data internal yang disimpan sistem operasi di buffer ini. Untuk menentukan ukuran buffer yang diperlukan, panggil rutinitas GetDmaTransferInfo atau CalculateScatterGatherList . Jika ScatterGatherBufferADALAH NULL, atur ScatterGatherBufferLength ke nol.

[in, optional] DmaCompletionRoutine

Penunjuk ke rutinitas DmaCompletionRoutine yang disediakan pemanggil untuk dipanggil ketika transfer DMA selesai. Rutinitas ini dipanggil jika perangkat target menggunakan pengontrol DMA sistem yang menghasilkan gangguan penyelesaian DMA. Rutinitas DmaCompletionRoutine dipanggil pada DISPATCH_LEVEL setelah transfer DMA selesai. Untuk adaptor DMA sistem, parameter ini bersifat opsional dan dapat berupa NULL. Untuk adaptor master bus, atur parameter ini ke NULL.

[in, optional] CompletionContext

Konteks yang ditentukan driver untuk rutinitas DmaCompletionRoutine . Konteks ini disediakan sebagai parameter CompletionContext ke rutinitas DmaCompletionRoutine . Jika parameter DmaCompletionRoutineadalah NULL, atur CompletionContext ke NULL.

Mengembalikan nilai

MapTransferEx mengembalikan STATUS_SUCCESS jika panggilan berhasil. Kemungkinan nilai pengembalian kesalahan menyertakan kode status berikut.

Menampilkan kode	Deskripsi
STATUS_INVALID_PARAMETERS	Rutinitas gagal karena nilai parameter yang tidak valid yang diteruskan oleh pemanggil.
STATUS_BUFFER_TOO_SMALL	Buffer yang disediakan penelepon di ScatterGatherBuffer terlalu kecil untuk berisi daftar sebar/kumpulkan.
STATUS_INSUFFICIENT_RESOURCES	Rutinitas gagal mengalokasikan sumber daya yang diperlukan untuk transfer DMA.
STATUS_CANCELLED	Transfer ini dibatalkan.

Keterangan

MapTransferEx bukan rutinitas sistem yang dapat dipanggil langsung berdasarkan nama. Rutinitas ini hanya dapat dipanggil dengan pointer dari alamat yang dikembalikan dalam struktur DMA_OPERATIONS. Driver mendapatkan alamat rutinitas ini dengan memanggil IoGetDmaAdapter dengan anggota Versi parameter DeviceDescription diatur ke DEVICE_DESCRIPTION_VERSION3. Jika IoGetDmaAdapter mengembalikan NULL, rutinitas tidak tersedia di platform Anda.

Untuk transfer yang menggunakan pengontrol DMA sistem, pemanggil dapat, sebagai opsi, menyediakan rutinitas panggilan balik DmaCompletionRoutine yang dipanggil ketika transfer selesai. Sistem operasi menjadwalkan panggilan balik ini sebagai respons terhadap gangguan penyelesaian DMA dari pengontrol DMA sistem.

Jumlah register peta yang dapat disiapkan oleh MapTransferEx tidak dapat melebihi maksimum yang diperoleh driver dari IoGetDmaAdapter.

Parameter Mdl, Offset, dan Length menjelaskan buffer data I/O untuk transfer DMA yang diminta. Jumlah register peta yang dialokasikan mungkin tidak cukup untuk memetakan semua memori dalam buffer ini, atau buffer sebar/kumpulkan yang ditujukkan oleh ScatterGatherBuffer mungkin tidak cukup besar untuk menggambarkan seluruh buffer. MapTransferEx menulis nilai output ke *Panjang untuk memberi tahu driver berapa banyak memori buffer untuk transfer DMA yang diminta dipetakan oleh rutinitas. Rutinitas menulis daftar sebar/kumpulkan ke buffer yang ditujukkan oleh ScatterGatherBuffer. Daftar ini menjelaskan fragmen buffer yang berhasil dipetakan oleh rutinitas.

Jika panggilan ke MapTransferEx berhasil, MapTransferEx menulis nilai output *Panjang sebelum kembali. Jika pemanggil menentukan DmaCompletionRoutine, nilai output *Panjang yang diperbarui selalu ditulis sebelum DmaCompletionRoutine berjalan. Untuk informasi selengkapnya, lihat Beberapa panggilan ke MapTransferEx.

Parameter Offset menentukan offset awal dalam rantai MDL yang menjelaskan memori dalam buffer data I/O. Misalnya, asumsikan bahwa rantai MDL berisi dua MDL, MDL₁ dan MDL₂, dan MDL₁ tersebut menjelaskan N₁ byte memori, dan MDL₂ menjelaskan N₂ byte. Jika Offset = N, di mana N₁ < N < N₁ + N₂, buffer tidak berisi memori yang dijelaskan oleh MDL₁, dan dimulai pada offset N - N₁ byte dalam memori yang dijelaskan oleh MDL₂.

Jika transfer menggunakan pengontrol DMA sistem, pemanggil dapat mengatur ScatterGatherBuffer = NULL, dalam hal ini MapTransferEx menggunakan buffer default yang dialokasikan secara internal untuk menahan daftar sebar/kumpulkan. Buffer default dijamin cukup besar untuk berisi daftar sebar/kumpulkan setidaknya satu elemen. Jika buffer default digunakan untuk menyebarkan/mengumpulkan transfer banyak elemen, banyak panggilan ke MapTransferEx mungkin diperlukan untuk menyelesaikan transfer. Jika perangkat keras pengontrol DMA mendukung transfer sebar/kumpulkan, penggunaan buffer default mungkin menurunkan performa.

Jika ScatterGatherBuffer non-NULL dan ScatterGatherBufferSize menentukan ukuran yang terlalu kecil untuk berisi daftar sebar/kumpulkan setidaknya satu elemen, MapTransferEx gagal dan mengembalikan STATUS_INVALID_PARAMETER.

MapTransferEx adalah versi rutinitas MapTransfer yang diperluas. Versi yang diperluas memiliki keuntungan berikut:

MapTransferEx dapat memproses semua fragmen buffer dalam rantai MDL dalam satu panggilan, tetapi MapTransfer hanya dapat memproses satu fragmen buffer yang berdampingan secara fisik per panggilan.
MapTransferEx dapat menghasilkan seluruh daftar sebar/kumpulkan dalam satu panggilan, tetapi MapTransfer hanya dapat menghasilkan satu elemen daftar sebar/kumpulkan per panggilan.
MapTransferEx dapat memetakan semua fragmen buffer dalam daftar sebar/kumpulkan dalam satu panggilan, tetapi MapTransfer hanya dapat memetakan satu fragmen buffer yang berdekatan secara fisik per panggilan.
MapTransferEx hanya memerlukan offset awal untuk seluruh daftar sebar/kumpulkan, tetapi MapTransfer memerlukan alamat virtual awal untuk setiap fragmen buffer yang berdekatan secara fisik.
Panggilan MapTransferEx dapat memetakan buffer yang meluas melalui satu atau beberapa MDL, tetapi panggilan MapTransfer hanya dapat memetakan satu fragmen buffer yang berdekatan secara fisik dalam memori yang dijelaskan oleh MDL.
Untuk transfer DMA sistem, MapTransferEx memungkinkan pemanggil untuk menyediakan rutinitas panggilan balik DmaCompletionRoutine untuk menerima pemberitahuan setelah transfer selesai, tetapi MapTransfer tidak menyediakan cara untuk memberi tahu pemanggil ketika transfer DMA selesai.

Setiap panggilan yang berhasil ke MapTransferEx harus diikuti dengan panggilan yang sesuai ke rutinitas FlushAdapterBuffersEx . Panggilan FlushAdapterBuffersEx yang mengikuti panggilan MapTransferEx harus terjadi sebelum panggilan MapTransferEx berikutnya terjadi. Panggilan FlushAdapterBuffersEx diperlukan meskipun panggilan ke rutinitas CancelMappedTransfer berhasil membatalkan transfer yang dipetakan yang diminta oleh panggilan MapTransferEx sebelumnya.

Untuk informasi selengkapnya, lihat Menggunakan Rutinitas MapTransferEx.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia dimulai dengan Windows 8.
Target Platform	Desktop
Header	wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h)
IRQL	<= DISPATCH_LEVEL