Fungsi NdisMAllocateSharedMemory (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.

NdisMAllocateSharedMemory mengalokasikan dan memetakan rentang memori host sehingga rentang memori dapat diakses secara bersamaan dari sistem host dan DMA NIC.

Sintaks

void NdisMAllocateSharedMemory(
  [in]  NDIS_HANDLE            MiniportAdapterHandle,
  [in]  ULONG                  Length,
  [in]  BOOLEAN                Cached,
  [out] PVOID                  *VirtualAddress,
  [out] PNDIS_PHYSICAL_ADDRESS PhysicalAddress
);

Parameter

[in] MiniportAdapterHandle

Menentukan input handel ke MiniportInitializeEx.

[in] Length

Menentukan jumlah byte yang akan dialokasikan.

[in] Cached

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

[out] VirtualAddress

Pointer ke variabel yang disediakan penelepon di mana fungsi ini mengembalikan alamat virtual dasar alokasi untuk digunakan oleh driver miniport. Jika NdisMAllocateSharedMemory tidak dapat memenuhi pemanggilnya, NdisMAllocateSharedMemory mengembalikan NULL untuk menunjukkan bahwa tidak ada memori yang dialokasikan.

[out] PhysicalAddress

Pointer ke variabel yang disediakan penelepon di mana fungsi ini mengembalikan alamat fisik, cocok untuk digunakan oleh NIC, yang sesuai dengan yang dikembalikan di VirtualAddress, atau mengembalikan NULL.

Menampilkan nilai

Tidak ada

Keterangan

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

Microsoft Windows Server 2003, Windows XP Service Pack 1, dan versi Windows yang lebih baru memungkinkan NIC DMA master bus dan NIC DMA bawahan untuk memanggil NdisMAllocateSharedMemory. Rilis sebelumnya hanya memungkinkan NIC DMA master bus untuk memanggil NdisMAllocateSharedMemory. Dalam rilis sebelumnya, jika MiniportInitializeEx tidak menentukan bahwa NIC adalah master bus ketika disebut NdisMSetMiniportAttributes, NdisMAllocateSharedMemory hanya mengembalikan kontrol tanpa mencoba membuat alokasi.

NdisMAllocateSharedMemory menyediakan rentang alamat virtual yang dipetakan yang digunakan driver untuk mengakses blok memori bersama dan rentang jenis NDIS_PHYSICAL_ADDRESS yang digunakan NIC. Nilai yang dikembalikan di PhysicalAddress dapat dipetakan secara bergantian oleh sistem. Artinya, rentang alamat "fisik" yang dijelaskan oleh nilai di PhysicalAddress and Length dapat menjadi rentang alamat logis yang dipetakan yang tidak cocok dengan alamat fisik host untuk alokasi di setiap platform yang mungkin.

NdisMAllocateSharedMemory hanya dapat dipanggil dari MiniportInitializeEx. Seberapa besar alokasi untuk meminta tergantung pada bagaimana penulis driver, mengetahui kemampuan dan fitur NIC, memutuskan untuk membuat tradeoff antara performa berikut versus dilema ukuran:

Dalam periode lalu lintas jaringan tinggi, driver miniport tidak dapat mempertahankan throughput I/O tinggi jika kehabisan ruang memori bersama untuk buffer data yang dapat diakses perangkat.
Misalnya, driver miniport dapat menunjukkan menerima buffer dalam memori bersama lebih cepat daripada buffer tersebut dikembalikan dari driver protokol terikat ketika banjir penerimaan masuk ke NIC. Jika semua ruang memori bersamanya dikonsumsi oleh buffer penerima yang luar biasa, driver miniport mungkin harus menonaktifkan gangguan penerimaan pada NIC sampai memiliki beberapa ruang memori bersama yang tersedia untuk menerima buffer.
Di sisi lain, memanggil NdisMAllocateSharedMemory dengan Panjang yang dipilih untuk mengantisipasi beberapa permintaan transfer maksimum membuat gambar driver lebih besar dan penggunaan sumber dayanya cukup tidak ekonomis, kecuali untuk periode permintaan I/O yang sangat tinggi. Selain itu, NdisMAllocateSharedMemory mungkin tidak memberi driver blok besar seperti itu jika memori sistem yang tidak mencukupi tersedia, memaksa driver untuk gagal inisialisasi.

Driver miniport yang memasok Fungsi MiniportSharedMemoryAllocateComplete memiliki fleksibilitas yang jauh lebih besar dalam menyelesaikan performa sebelumnya versus dilema ukuran. MiniportInitializeEx harus mengalokasikan hanya cukup memori bersama dengan NdisMAllocateSharedMemory untuk permintaan moderat untuk operasi transfer jaringan melalui NIC jika driver memiliki fungsi MiniportSharedMemoryAllocateComplete . Sopir miniport seperti itu dapat menelepon NdisMAllocateSharedMemoryAsyncEx secara dinamis untuk mengalokasikan lebih banyak memori bersama dalam periode permintaan transfer yang lebih berat pada NIC. Ketika permintaan transfer yang tinggi mereda, driver seperti itu memanggil NdisMFreeSharedMemory untuk merilis memori tambahan yang dialokasikannya. Perhatikan bahwa hanya NIC DMA master bus yang dapat memanggil NdisMAllocateSharedMemoryAsyncEx dan mengekspor MiniportSharedMemoryAllocateComplete. Fungsionalitas ini tidak didukung untuk NIC DMA bawahan.

NdisMAllocateSharedMemory dan NdisMAllocateSharedMemoryAsyncEx adalah satu-satunya fungsi NdisXxx yang dapat dipanggil untuk mengalokasikan memori host yang dibagi antara driver, yang menggunakan alamat virtual, dan NIC, yang menggunakan alamat logis yang sesuai.

Driver miniport harus menyelaraskan buffer yang dialokasikannya dari memori cache bersama pada integral batas baris cache data host untuk mencegah robeknya baris cache selama DMA. Cache-line robek dapat menyebabkan masalah integritas data pada driver atau menurunkan performa I/O driver (dan sistem) dengan memerlukan flushing cache data yang berlebihan untuk menjaga integritas data. MiniportInitializeEx dapat memanggil NdisMGetDmaAlignment untuk menentukan batas perataan di platform saat ini untuk buffer yang dapat diakses perangkat yang akan diatur driver dalam rentang memori bersama yang dialokasikan.

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 menetapkan batas yang terlalu tinggi, karena ini dapat mengakibatkan konsumsi memori bersama yang boros yang dapat mengurangi performa sistem.

MiniportInitializeEx juga dapat memanggil NdisSystemProcessorCount sebelum memanggil NdisMAllocateSharedMemory jika penulis driver memutuskan untuk mengalokasikan blok memori bersama yang lebih besar di mesin multiprosedur pada asumsi bahwa komputer SMP apa pun kemungkinan akan menjadi server jaringan dengan tuntutan transfer jaringan yang lebih tinggi pada NIC daripada stasiun kerja.

Jika panggilannya ke NdisMAllocateSharedMemory gagal, MiniportInitializeEx dapat memanggil lagi meminta alokasi yang lebih kecil. Namun, jika MiniportInitializeEx tidak dapat mengalokasikan memori bersama yang cukup untuk NIC, itu harus merilis semua sumber daya yang telah dialokasikan dan gagal inisialisasi.

Jika driver miniport kemudian menunjukkan menerima dengan NdisMIndicateReceiveNetBufferLists, harus mengalokasikan beberapa jumlah deskriptor buffer dari kumpulan buffer yang memetakan buffer penerima NIC di blok memori bersama.

Jika memori yang dialokasikan di-cache dan, oleh karena itu, perlu dibersihkan pada transfer, driver miniport harus memanggil NdisAllocateMdl untuk mengalokasikan deskriptor jenis NDIS_BUFFER untuk rentang memori bersama. Driver miniport harus memanggil KeFlushIoBuffers dengan deskriptor buffer ini untuk melakukan flush seperti itu.

Jika driver miniport memanggil NdisMAllocateSharedMemoryAsyncEx atau NdisMAllocateSharedMemory, harus melepaskan semua alokasi yang luar biasa dengan satu atau beberapa panggilan ke NdisMFreeSharedMemory ketika NIC dihapus, yaitu, ketika fungsi MiniportHaltEx-nya dipanggil.

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