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