Fungsi NdisAllocateSpinLock (ndis.h)

Artikel
02/26/2024

Fungsi NdisAllocateSpinLock menginisialisasi variabel jenis NDIS_SPIN_LOCK, digunakan untuk menyinkronkan akses ke sumber daya yang dibagikan di antara fungsi driver non-ISR.

Sintaks

void NdisAllocateSpinLock(
  [out] PNDIS_SPIN_LOCK SpinLock
);

Parameter

[out] SpinLock

Penunjuk ke variabel buram yang mewakili kunci putar.

Menampilkan nilai

Tidak ada

Keterangan

Sebelum driver memanggil NdisAcquireSpinLock, NdisDprAcquireSpinLock, atau salah satu fungsi Xxx NdisInterlocked, ia harus memanggil NdisAllocateSpinLock untuk menginisialisasi kunci putaran yang diteruskan sebagai parameter yang diperlukan untuk fungsi NdisXxx ini. Pemanggil harus menyediakan penyimpanan yang tidak di-halaman untuk variabel di SpinLock .

Setelah memanggil NdisAllocateSpinLock, driver dapat memanggil NdisAcquireSpinLock untuk mendapatkan penggunaan eksklusif sumber daya yang dilindungi kunci spin. Ketika akses sumber daya selesai, driver memanggil NdisReleaseSpinLock sehingga fungsi driver lain dapat mengakses sumber daya yang dilindungi oleh kunci putar tersebut.

Sebagai aturan umum, untuk meningkatkan performa driver harus menggunakan kunci yang berbeda untuk melindungi bagian penting yang berbeda. Dengan demikian, driver mungkin menginisialisasi lebih dari satu kunci putar dengan NdisAllocateSpinLock.

Setiap kunci putar yang dialokasikan driver melindungi sekumpulan sumber daya bersama yang diskrit dari akses simultan oleh fungsi driver yang berjalan di IRQL <= DISPATCH_LEVEL. Misalnya, driver yang mempertahankan antrean internal paket mungkin menginisialisasi satu kunci putaran untuk melindungi antreannya dan yang lain untuk melindungi serangkaian variabel status yang beberapa fungsi driver, tidak termasuk MiniportInterrupt atau Fungsi MiniportDisableInterruptEx , akses saat driver memproses paket.

NdisAcquireSpinLock menaikkan IRQL ke DISPATCH_LEVEL dan menyimpan IRQL lama di kunci putar. Melepaskan kunci putaran mengatur IRQL ke nilai yang disimpan di kunci putar. Karena NDIS terkadang memasukkan driver pada PASSIVE_LEVEL, masalah dapat muncul dengan kode berikut:

NdisAcquireSpinLock(A);
NdisAcquireSpinLock(B);
NdisReleaseSpinLock(A);
NdisReleaseSpinLock(B);

Driver tidak boleh mengakses kunci putaran dalam urutan ini karena alasan berikut:

Antara NdisReleaseSpinLock(A) dan NdisReleaseSpinLock(B) kode berjalan pada PASSIVE_LEVEL alih-alih DISPATCH_LEVEL dan mengalami gangguan yang tidak tepat.
Setelah NdisReleaseSpinLock(B) kode berjalan pada DISPATCH_LEVEL yang dapat menyebabkan kesalahan pemanggil di lain waktu dengan kesalahan berhenti IRQL_NOT_LESS_OR_EQUAL.

Driver tidak boleh menggunakan dua kunci spin untuk melindungi (sub)set sumber daya yang sama karena akuisisi kunci putar berlapis sehingga sering menyebabkan kebuntuan. Bahkan jika driver dapat dirancang untuk mencegah kebuntuan, akuisisi kunci putar berlapis memiliki efek buruk pada performa driver dan throughput I/O.

Driver miniport tidak dapat menggunakan kunci putar untuk melindungi sumber daya yang dibagikan fungsi non-ISR dengan MiniportInterrupt atau Fungsi MiniportDisableInterruptEx . Untuk mengakses sumber daya yang dibagikan dengan fungsi MiniportInterrupt atau MiniportDisableInterruptEx , driver miniport harus memanggil NdisMSynchronizeWithInterruptEx memiliki Fungsi MiniportSynchronizeInterrupt mengakses sumber daya tersebut di DIRQL.

Ketika driver tidak lagi memerlukan perlindungan sumber daya, misalnya, ketika NIC sedang dihapus dan driver merilis sumber daya yang dialokasikan untuk NIC tersebut, driver memanggil NdisFreeSpinLock.

Membebaskan kunci putaran dan melepaskan kunci putaran berpotensi membingungkan. NdisFreeSpinLock menghapus memori di SpinLock sehingga tidak lagi mewakili kunci putaran. Melepaskan kunci spin yang diperoleh dengan NdisReleaseSpinLock hanya memungkinkan utas eksekusi lain untuk memperoleh kunci spin tersebut.

Untuk informasi selengkapnya tentang memperoleh dan merilis kunci spin NDIS, lihat Sinkronisasi dan Pemberitahuan di Driver Jaringan.

Penelepon NdisAllocateSpinLock dapat berjalan di IRQL apa pun. Biasanya pemanggil berjalan di IRQL = PASSIVE_LEVEL selama inisialisasi.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Didukung untuk driver NDIS 6.0 dan NDIS 5.1 (lihat NdisAllocateSpinLock (NDIS 5.1)) di Windows Vista. Didukung untuk driver NDIS 5.1 (lihat NdisAllocateSpinLock (NDIS 5.1)) di Windows XP.
Target Platform	Universal
Header	ndis.h (termasuk Ndis.h)
Pustaka	Ndis.lib
IRQL	Tingkat apa pun (lihat bagian Keterangan)
Aturan kepatuhan DDI	SpinLockDpr(ndis), SpinLockDprRelease(ndis), SpinlockRelease(ndis)