Fungsi NdisMAllocateNetBufferSGList (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 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
NDIS_STATUS_SUCCESS	NdisMAllocateNetBufferSGList berhasil membangun daftar sebar/kumpulkan untuk struktur NET_BUFFER yang ditentukan.
NDIS_STATUS_RESOURCES	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)