Fungsi NdisMAllocateSharedMemoryAsyncEx (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 memanggil fungsi NdisMAllocateSharedMemoryAsyncEx untuk mengalokasikan memori tambahan yang dibagikan antara pengemudi dan DMA NIC master busnya, biasanya ketika driver miniport hampir kehabisan NIC yang tersedia menerima buffer.

Sintaks

NDIS_STATUS NdisMAllocateSharedMemoryAsyncEx(
  [in] NDIS_HANDLE MiniportDmaHandle,
  [in] ULONG       Length,
  [in] BOOLEAN     Cached,
  [in] PVOID       Context
);

Parameter

[in] MiniportDmaHandle

Handel ke area konteks yang digunakan NDIS untuk mengelola sumber daya DMA. Pemanggil memperoleh handel ini dengan memanggil Fungsi NdisMRegisterScatterGatherDma .

[in] Length

Jumlah byte yang akan dialokasikan.

[in] Cached

Parameter ini diabaikan (memori yang di-cache selalu digunakan pada sistem x86 dan x64).

[in] Context

Penunjuk ke konteks yang ditentukan driver untuk diteruskan ke fungsi MiniportSharedMemoryAllocateComplete saat dipanggil.

Mengembalikan nilai

NdisMAllocateSharedMemoryAsyncEx dapat mengembalikan salah satu hal berikut:

Menampilkan kode	Deskripsi
NDIS_STATUS_PENDING	NDIS akan memanggil fungsi MiniportSharedMemoryAllocateComplete dan memberikan informasi yang menjelaskan memori bersama yang dialokasikan. Jika upaya untuk mengalokasikan memori bersama gagal, NDIS memanggil MiniportSharedMemoryAllocateComplete dan melewati pointer NULL .
NDIS_STATUS_FAILURE	Memori yang diminta saat ini tidak dapat dialokasikan. Jika NdisMAllocateSharedMemoryAsyncEx mengembalikan status ini, panggilan berikutnya dengan parameter yang sama mungkin berhasil, tergantung pada apakah sumber daya sistem telah tersedia.

Keterangan

Catatan Driver miniport harus sudah memanggil NdisMRegisterScatterGatherDma atau NdisMRegisterDmaChannel untuk menginisialisasi saluran DMA yang menyebar/mengumpulkan sebelum memanggil NdisMAllocateSharedMemoryAsyncEx.

Driver NIC DMA master bus memanggil NdisMAllocateSharedMemoryAsyncEx untuk mengalokasikan memori bersama secara dinamis. Driver tersebut juga mengalokasikan ruang memori bersama selama inisialisasi. Driver ini menggunakan memori bersama yang dialokasikan secara dinamis untuk operasi transfer ketika lalu lintas jaringan tinggi menempatkan tuntutan yang berlebihan pada ruang memori bersama yang ada.

Driver miniport seperti itu biasanya mempertahankan satu atau beberapa variabel status untuk melacak jumlah buffer memori bersama yang tersedia untuk transfer masuk. Ketika jumlah buffer yang tersedia mencapai driver yang ditentukan rendah, driver miniport memanggil NdisMAllocateSharedMemoryAsyncEx untuk mengalokasikan lebih banyak ruang buffer dalam memori bersama. Ketika jumlah buffer yang tersedia naik ke driver yang ditentukan tinggi, driver miniport memanggil NdisMFreeSharedMemory satu atau beberapa kali untuk merilis alokasi dinamis sebelumnya.

Biasanya, driver miniport seperti itu mempertahankan blok memori bersama bahwa fungsi MiniportInitializeEx yang dialokasikan dengan NdisMAllocateSharedMemory sampai NIC dihapus. Ketika NIC dihapus, NDIS memanggil fungsi MiniportHaltEx driver miniport. Alokasi ini cukup untuk menangani permintaan rata-rata transfer melalui NIC.

Driver miniport harus menetapkan batas berapa banyak memori bersama yang dapat dialokasikannya. Batas ini khusus driver dan harus cukup tinggi sehingga driver tidak kehabisan buffer. Jangan mengikat batas yang terlalu tinggi, karena ini dapat mengakibatkan konsumsi memori bersama yang boros yang dapat mengurangi performa sistem.

Setiap driver miniport yang memanggil NdisMAllocateSharedMemoryAsyncEx atau NdisMAllocateSharedMemory harus merilis semua alokasi yang luar biasa dengan satu atau beberapa panggilan ke NdisMFreeSharedMemory ketika NIC-nya dihapus.

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)
IRQL	<= DISPATCH_LEVEL
Aturan kepatuhan DDI	Irql_Gather_DMA_Function(ndis)