Fungsi NdisMRegisterScatterGatherDma (ndis.h)

Artikel
08/07/2023

Perhatian

Untuk prosesor ARM dan ARM64, kami sangat menyarankan agar penulis driver NDIS menggunakan WDF DMA atau WDM DMA alih-alih NDIS Scatter/Gather DMA.

Untuk informasi selengkapnya tentang WDF DMA, lihat Menangani Operasi DMA di Driver KMDF.

Untuk informasi selengkapnya tentang WDM DMA, lihat topik anak terkait DMA dari Mengelola Input/Output untuk Driver.

Driver miniport master bus memanggil fungsi NdisMRegisterScatterGatherDma dari MiniportInitializeEx untuk menginisialisasi saluran DMA yang menyebar/mengumpulkan.

Sintaks

NDIS_STATUS NdisMRegisterScatterGatherDma(
  [in]      NDIS_HANDLE              MiniportAdapterHandle,
  [in, out] PNDIS_SG_DMA_DESCRIPTION DmaDescription,
  [out]     PNDIS_HANDLE             NdisMiniportDmaHandle
);

Parameter

[in] MiniportAdapterHandle

Handel miniport yang diteruskan NDIS ke MiniportInitializeEx.

[in, out] DmaDescription

Penunjuk ke struktur NDIS_SG_DMA_DESCRIPTION. Struktur ini menjelaskan properti DMA yang tersebar/dikumpulkan dari driver miniport. Struktur didefinisikan sebagai berikut:

typedef struct _NDIS_SG_DMA_DESCRIPTION {
  NDIS_OBJECT_HEADER  Header;
  ULONG  Flags;
  ULONG  MaximumPhysicalMapping;
  MINIPORT_PROCESS_SG_LIST_HANDLER  ProcessSGListHandler;
  MINIPORT_ALLOCATE_SHARED_MEM_COMPLETE_HANDLER  SharedMemAllocateCompleteHandler;
  ULONG  ScatterGatherListSize;
} NDIS_SG_DMA_DESCRIPTION, *PNDIS_SG_DMA_DESCRIPTION;

Struktur ini mencakup anggota berikut:

Struktur NDIS_OBJECT_HEADER untuk struktur NDIS_SG_DMA_DESCRIPTION. Atur anggota Jenis struktur yang ditentukan Header ke NDIS_OBJECT_TYPE_SG_DMA_DESCRIPTION, anggota Revisi ke NDIS_SG_DMA_DESCRIPTION_REVISION_1, dan anggota Ukuran ke NDIS_SIZEOF_SG_DMA_DESCRIPTION_REVISION_1.

Bendera

Sekumpulan bendera bit yang menentukan karakteristik sebar/kumpulkan. Atur anggota ini ke bitwise ATAU dari semua bendera yang diperlukan.

Bendera NDIS_SG_DMA_64_BIT_ADDRESS menentukan bahwa NIC dapat menggunakan alamat 64-bit untuk operasi DMA. Jika tidak, NIC menggunakan alamat 32-bit.

Atur anggota ini ke nol jika alamat 64-bit tidak diperlukan.

MaximumPhysicalMapping

Jumlah maksimum byte yang dapat ditransfer NIC dalam satu operasi DMA. NDIS memberikan nilai ini ke lapisan abstraksi perangkat keras (HAL) saat mengalokasikan saluran DMA, dan HAL menggunakan nilai ini untuk menentukan jumlah maksimum register peta yang akan dicadangkan untuk NIC.

ProcessSGListHandler

Fungsi MiniportProcessSGList yang dipanggil NDIS ketika HAL selesai membangun daftar sebar/kumpulkan.

SharedMemAllocateCompleteHandler

The Fungsi MiniportSharedMemoryAllocateComplete untuk driver miniport yang memanggil NdisMAllocateSharedMemoryAsyncEx. Bidang ini bersifat opsional dan harus NULL jika driver miniport tidak memanggil NdisMAllocateSharedMemoryAsyncEx.

ScatterGatherListSize

Ukuran, dalam byte, dari memori yang diperlukan untuk menyimpan daftar sebar/kumpulkan. NDIS menetapkan nilai ini sebelum kembali dari NdisMRegisterScatterGatherDma. Driver Miniport harus menggunakan ukuran ini untuk melakukan pra-alokasi memori untuk setiap daftar sebar/kumpulkan.

[out] NdisMiniportDmaHandle

Penunjuk ke variabel yang disediakan pemanggil dan NDIS tersebut diisi dengan handel. Handel mengidentifikasi area konteks yang digunakan NDIS untuk mengelola sumber daya DMA ini. Driver miniport meneruskan handel ini ke NDIS dalam panggilan berikutnya ke NDIS yang melibatkan sumber daya DMA ini.

Nilai kembali

NdisMRegisterScatterGatherDma mengembalikan salah satu hal berikut ini:

Menampilkan kode	Deskripsi
NDIS_STATUS_SUCCESS	NdisMRegisterScatterGatherDma berhasil mengalokasikan sumber daya untuk operasi DMA master bus.
NDIS_STATUS_RESOURCES	NdisMRegisterScatterGatherDma gagal karena sumber daya yang tidak mencukupi.
NDIS_STATUS_NOT_SUPPORTED	NdisMRegisterScatterGatherDma gagal karena miniport tidak menentukan bahwa ia mendukung NDIS 6.0 atau versi yang lebih baru, atau karena driver miniport tidak menentukan bahwa NIC-master-nya adalah perangkat DMA bus-master. Driver miniport menentukan versi NDIS-nya saat memanggil NdisMRegisterMiniportDriver. Driver miniport menentukan bahwa ia mendukung perangkat DMA master bus saat memanggil NdisMSetMiniportAttributes.
NDIS_STATUS_BAD_VERSION	Versi NDIS saat ini tidak mendukung versi yang ditentukan dalam anggota Revisi struktur HeaderDmaDescription .

Keterangan

Driver miniport master bus NDIS memanggil NdisMRegisterScatterGatherDma dalam fungsi MiniportInitializeEx untuk menginisialisasi sumber daya untuk menyebarkan/mengumpulkan operasi DMA. Parameter DmaDescription yang diteruskan driver miniport ke NdisMRegisterScatterGatherDma berisi informasi yang digunakan NDIS untuk menginisialisasi sumber daya DMA yang menyebar/mengumpulkan. Setelah NdisMRegisterScatterGatherDma kembali, anggota ScatterGatherListSizedari DmaDescription berisi ukuran buffer yang seharusnya cukup untuk menyimpan daftar sebar/kumpulkan. Driver Miniport harus menggunakan ukuran ini untuk melakukan pra-alokasi memori untuk daftar sebar/kumpulkan.

Anggota ProcessSGListHandler dalam parameter DmaDescription menentukan titik masuk di driver miniport untuk fungsi MiniportProcessSGList . Ketika driver miniport memanggil NdisMAllocateNetBufferSGList, NDIS memanggil HAL untuk menyediakan daftar sebar/kumpulkan ke driver miniport. HAL memanggil MiniportProcessSGList setelah HAL selesai membangun daftar sebar/kumpulkan. NDIS dapat memanggil MiniportProcessSGList di luar konteks panggilan ke NdisMAllocateNetBufferSGList.

NdisMRegisterScatterGatherDma mengembalikan pointer ke area konteks yang buram ke driver miniport. Driver miniport harus menggunakan handel ini dalam panggilan berikutnya ke fungsi NDIS menyebar/mengumpulkan DMA.

Sopir miniport master bus memanggil NdisMAllocateSharedMemoryAsyncEx untuk mengalokasikan memori bersama secara dinamis untuk operasi transfer data. Panggilan ini diperlukan ketika lalu lintas jaringan tinggi menyebabkan driver miniport kehabisan ruang memori bersama yang dialokasikan driver selama inisialisasi. Jika NdisMAllocateSharedMemoryAsyncEx mengembalikan NDIS_STATUS_PENDING, NDIS akan memanggil Fungsi MiniportSharedMemoryAllocateComplete untuk menyelesaikan operasi di lain waktu. Driver Miniport menentukan titik masuk untuk fungsi MiniportSharedMemoryAllocateComplete di anggota SharedMemAllocateCompleteHandler dari parameter DmaDescription .

Driver miniport memanggil Fungsi NdisMDeregisterScatterGatherDma untuk membatalkan alokasi sumber daya DMA yang dialokasikan NdisMRegisterScatterGatherDma .

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Didukung di NDIS 6.0 dan yang lebih baru.
Target Platform	Universal
Header	ndis.h (termasuk Ndis.h)
Pustaka	Ndis.lib
IRQL	PASSIVE_LEVEL
Aturan kepatuhan DDI	Init_RegisterSG(ndis), Irql_Gather_DMA_Function(ndis)