Fungsi NdisMAllocateNetBufferSGList (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.
Driver miniport master bus memanggil fungsi NdisMAllocateNetBufferSGList untuk mendapatkan daftar sebar/kumpulkan untuk data jaringan yang terkait dengan struktur NET_BUFFER .
Sintaks
NDIS_STATUS NdisMAllocateNetBufferSGList(
[in] NDIS_HANDLE NdisMiniportDmaHandle,
[in] PNET_BUFFER NetBuffer,
[in] PVOID Context,
[in] ULONG Flags,
[in, optional] PVOID ScatterGatherListBuffer,
[in] ULONG ScatterGatherListBufferSize
);
Parameter
[in] NdisMiniportDmaHandle
Handel ke area konteks yang digunakan NDIS untuk mengelola sumber daya DMA. Pemanggil memperoleh handel ini dengan memanggil Fungsi NdisMRegisterScatterGatherDma .
[in] NetBuffer
Penunjuk ke struktur NET_BUFFER. NdisMAllocateNetBufferSGList mengalokasikan daftar sebar/kumpulkan untuk data jaringan yang terkait dengan struktur NET_BUFFER ini. Daftar sebar/kumpulkan dihasilkan dari data mulai dari awal MDL yang ditentukan pada anggota CurrentMdl dari struktur NET_BUFFER_DATA terkait.
[in] Context
Penunjuk ke area konteks yang dibuat pemanggil. HAL meneruskan pointer ini ke MiniportProcessSGList setelah HAL membuat daftar sebar/kumpulkan. Pemanggil dapat menggunakan area konteks ini untuk tujuannya sendiri.
[in] Flags
Bendera NDIS yang dapat dikombinasikan dengan operasi OR. Untuk menghapus semua bendera, atur anggota ini ke nol. Fungsi ini mendukung bendera NDIS_SG_LIST_WRITE_TO_DEVICE yang; jika diatur, menunjukkan arah transfer DMA adalah dari NET_BUFFER ke perangkat. Jika NDIS_SG_LIST_WRITE_TO_DEVICE jelas, transfer berasal dari perangkat. Driver miniport harus mengatur bendera ini pada jalur pengiriman ketika operasi DMA mentransfer data dari NET_BUFFER ke perangkat. Driver miniport yang melakukan operasi DMA dari perangkat ke NET_BUFFER yang telah dialokasikan sebelumnya, misalnya NIC berkemampukan offload cerobong asap selama operasi penerimaan, harus menghapus bendera ini.
[in, optional] ScatterGatherListBuffer
Jika bukan NULL, ScatterGatherListBuffer menentukan pointer ke penyimpanan yang dialokasikan pemanggil untuk menyimpan daftar sebar/kumpulkan. Jika NULL, NDIS mengalokasikan penyimpanan untuk daftar sebar/kumpulkan.
[in] ScatterGatherListBufferSize
Jika parameter ScatterGatherListBuffer bukan NULL, ScatterGatherListBufferSize menentukan ukuran buffer yang berisi daftar sebar/kumpulkan. Jika ukuran ini terlalu kecil, NDIS mengalokasikan penyimpanan untuk daftar sebar/kumpulkan. Jika parameter ScatterGatherListBufferADALAH NULL, parameter ini tidak digunakan.
Mengembalikan nilai
NdisMAllocateNetBufferSGList mengembalikan salah satu hal berikut ini:
Menampilkan kode | Deskripsi |
---|---|
|
NdisMAllocateNetBufferSGList berhasil membangun daftar sebar/kumpulkan untuk struktur NET_BUFFER yang ditentukan. |
|
NdisMAllocateNetBufferSGList gagal karena sumber daya yang tidak mencukupi. |
Keterangan
Driver miniport master bus NDIS memanggil NdisMAllocateNetBufferSGList dari Fungsi MiniportSendNetBufferLists . Driver miniport memanggil NdisMAllocateNetBufferSGList sekali untuk setiap struktur NET_BUFFER yang harus mendapatkan daftar sebar/kumpulkan.
Ketika driver miniport memanggil NdisMAllocateNetBufferSGList, NDIS memanggil HAL untuk membangun daftar sebar/kumpulkan. Setelah HAL membangun daftar sebar/kumpulkan, HAL memanggil fungsi MiniportProcessSGList yang didaftarkan driver miniport dengan memanggil NdismRegisterScatterGatherDma.
HAL dapat memanggil MiniportProcessSGList sebelum atau sesudah NDIS kembali dari NdisMAllocateNetBufferSGList. Driver miniport tidak boleh mencoba mengakses daftar sebar/kumpulkan hingga setelah HAL memanggil MiniportProcessSGList.
Untuk meningkatkan performa sistem, driver miniport harus melakukan pra-alokasi buffer untuk digunakan dalam parameter ScatterGatherListBufferdari NdisMAllocateNetBufferSGList. NDIS menyediakan ukuran yang direkomendasikan untuk buffer di anggota ScatterGatherListSize dari parameter DmaDescription saat driver miniport memanggil NdisMRegisterScatterGatherDma. Driver miniport menentukan ukuran buffer dalam parameter ScatterGatherListBufferSize saat mereka memanggil NdisMAllocateNetBufferSGList.
NDIS mungkin mengalokasikan buffer meskipun driver miniport menentukan buffer dalam parameter ScatterGatherListBuffer . Ini dapat terjadi jika buffer yang ditentukan terlalu kecil untuk menahan daftar sebar/kumpulkan. Oleh karena itu, penulis driver tidak boleh berasumsi bahwa buffer yang ditentukan dalam parameter ScatterGatherListBuffer berisi daftar sebar/kumpulkan. HAL meneruskan penunjuk daftar sebar/kumpulkan yang benar ke fungsi MiniportProcessSGList driver miniport .
Untuk meningkatkan performa sistem, daftar sebar/kumpulkan dihasilkan dari data jaringan mulai dari awal MDL yang ditentukan pada anggota CurrentMdl dari struktur NET_BUFFER_DATA terkait. Awal data jaringan dalam daftar SG diimbangi dari awal daftar SG dengan nilai yang ditentukan dalam anggota CurrentMdlOffset dari struktur NET_BUFFER_DATA terkait.
Driver miniport harus memanggil fungsi NdisMFreeNetBufferSGList untuk membebaskan daftar sebar/kumpulkan.
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 | DISPATCH_LEVEL |
Aturan kepatuhan DDI | Irql_Gather_DMA_Function(ndis) |
Lihat juga
NDIS Menyebar/Mengumpulkan DMA
NdismRegisterScatterGatherDma