PALLOCATE_CONTIGUOUS_DMA_BUFFER fungsi panggilan balik (hdaudio.h)

Artikel
02/26/2024

Rutinitas mengalokasikan AllocateContiguousDmaBuffer buffer DMA yang terdiri dari satu blok memori fisik yang berdampingan.

Jenis penunjuk fungsi untuk AllocateContiguousDmaBuffer rutinitas didefinisikan sebagai berikut.

Sintaks

PALLOCATE_CONTIGUOUS_DMA_BUFFER PallocateContiguousDmaBuffer;

NTSTATUS PallocateContiguousDmaBuffer(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
        ULONG RequestedBufferSize,
  [out] PVOID *DataBuffer,
  [out] PHDAUDIO_BUFFER_DESCRIPTOR *BdlBuffer
)
{...}

Parameter

[in] _context

Menentukan nilai konteks dari anggota Konteks struktur HDAUDIO_BUS_INTERFACE_BDL .

[in] Handle

Menangani identifikasi mesin DMA. Nilai handel ini diperoleh dari panggilan sebelumnya ke AllocateCaptureDmaEngine atau AllocateRenderDmaEngine.

RequestedBufferSize

Menentukan ukuran buffer yang diminta dalam byte.

[out] DataBuffer

Mengambil buffer data. Parameter ini menunjuk ke variabel PVOID yang dialokasikan pemanggil tempat rutin menulis alamat virtual sistem buffer data.

[out] BdlBuffer

Mengambil daftar deskriptor buffer (BDL). Parameter ini menunjuk ke variabel PVOID yang dialokasikan pemanggil tempat rutin menulis alamat virtual sistem BDL. Ukuran alokasi BDL tepat satu halaman memori dan BDL dimulai pada batas halaman.

Nilai kembali

AllocateContiguousDmaBuffer mengembalikan STATUS_SUCCESS jika panggilan berhasil. Jika tidak, rutinitas mengembalikan kode kesalahan yang sesuai. Tabel berikut ini memperlihatkan beberapa kemungkinan kode status pengembalian.

Menampilkan kode	Deskripsi
STATUS_UNSUCCESSFUL	Menunjukkan bahwa pemanggil berjalan pada tingkat permintaan interupsi (IRQL) yang terlalu tinggi.
STATUS_INSUFFICIENT_RESOURCES	Menunjukkan bahwa alokasi buffer gagal.
STATUS_INVALID_HANDLE	Menunjukkan bahwa nilai parameter handel tidak valid.
STATUS_INVALID_PARAMETER	Menunjukkan bahwa salah satu nilai parameter salah (penunjuk buruk).
STATUS_DEVICE_NOT_READY	Menunjukkan bahwa waktu pemrograman perangkat keras habis. Jika ini terjadi, perangkat keras mungkin dalam keadaan disusupi.
STATUS_INVALID_DEVICE_REQUEST	Menunjukkan bahwa aliran tidak dalam status reset atau bahwa buffer sudah dialokasikan untuk mesin DMA.

Keterangan

Rutinitas AllocateContiguousDmaBuffer ini digunakan bersama dengan rutinitas SetupDmaEngineWithBdl dan FreeContiguousDmaBuffer . Ketiga rutinitas ini hanya tersedia dalam versi HDAUDIO_BUS_INTERFACE_BDL HD Audio DDI. DDI ini tidak termasuk rutinitas AllocateDmaBuffer dan FreeDmaBuffer , yang tidak pernah digunakan bersama dengan AllocateContiguousDmaBuffer, SetupDmaEngineWithBdl, dan FreeContiguousDmaBuffer. Tidak seperti SetupDmaEngineWithBdl, yang mengonfigurasi mesin DMA untuk menggunakan buffer DMA yang dialokasikan sebelumnya, AllocateDmaBuffer keduanya mengalokasikan buffer DMA dan mengonfigurasi mesin DMA untuk menggunakan buffer. Untuk informasi selengkapnya, lihat Perbedaan antara Dua Versi DDI.

AllocateContiguousDmaBuffer mengalokasikan buffer data untuk mesin DMA yang ditentukan. Ini juga mengalokasikan halaman memori untuk BDL. Tergantung pada arsitektur prosesor host, ukuran halaman umum mungkin 4.096 atau 8.192 byte. Buffer data terdiri dari satu blok memori fisik yang berdampingan.

Parameter handle menentukan mesin DMA yaitu menggunakan buffer data dan BDL. Rutin mengalokasikan penyimpanan yang memenuhi ukuran, penyelarasan, dan persyaratan posisi mesin DMA.

Penyimpanan yang dialokasikan rutin untuk buffer data dan BDL tidak diinisialisasi. Driver fungsi bertanggung jawab untuk mengisi BDL sebelum mengirimkannya ke rutinitas SetupDmaEngineWithBdl . Driver fungsi juga bertanggung jawab untuk memprogram codec untuk mengelola transfer data dan mengenali pengidentifikasi aliran.

Untuk menghasilkan interupsi IOC pada interval yang tepat, driver fungsi mungkin diperlukan untuk membagi alokasi buffer data menjadi beberapa fragmen dengan ukuran tertentu. Setiap fragmen dijelaskan oleh entri BDL. Ukuran fragmen dapat disesuaikan untuk menyetel laju interupsi. Menurut Spesifikasi Audio Definisi Tinggi Intel (lihat situs web Intel HD Audio ), setiap fragmen harus dimulai pada batas 128 byte, meskipun tidak ada persyaratan perataan seperti itu yang berlaku untuk panjang fragmen. Dengan demikian, celah mungkin ada antara akhir satu fragmen dan awal yang berikutnya. Saat memanggil SetupDmaEngineWithBdl, driver fungsi harus menentukan nilai untuk parameter bufferSize yang mewakili jumlah ukuran fragmen individual yang dijelaskan entri BDL. Ukuran ini akan kurang dari atau sama dengan jumlah byte yang ditentukan dalam AllocateContiguousDmaBuffer parameter requestedBufferSize rutin.

Selama masa pakai handel mesin DMA, AllocateContiguousDmaBuffer dapat dipanggil secara berturut-turut untuk mengalokasikan buffer DMA baru. Namun, sebelum memanggil AllocateContiguousDmaBuffer, buffer DMA yang dialokasikan sebelumnya harus terlebih dahulu dikosongkan dengan memanggil FreeContiguousDmaBuffer.

Selama panggilan ke AllocateContiguousDmaBuffer, SetupDmaEngineWithBdl, dan FreeContiguousDmaBuffer, mesin DMA harus dalam status aliran reset. Mesin DMA berada dalam status reset segera setelah panggilan ke AlokasikanXxxDmaEngine. Untuk mengubah mesin DMA ke status eksekusi, panggil SetDmaEngineState.

Rutinitas ini gagal dan mengembalikan kode kesalahan STATUS_INVALID_DEVICE_REQUEST dalam salah satu keadaan berikut: