PALLOCATE_DMA_BUFFER fungsi panggilan balik (hdaudio.h)

Artikel
08/07/2023

AllocateDmaBuffer Rutin mengalokasikan buffer data dalam memori sistem untuk mesin DMA.

Jenis penunjuk fungsi untuk AllocateDmaBuffer rutinitas didefinisikan sebagai berikut.

Sintaks

PALLOCATE_DMA_BUFFER PallocateDmaBuffer;

NTSTATUS PallocateDmaBuffer(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
  [in]  SIZE_T RequestedBufferSize,
  [out] PMDL *BufferMdl,
  [out] PSIZE_T AllocatedBufferSize,
  [out] PUCHAR StreamId,
  [out] PULONG FifoSize
)
{...}

Parameter

[in] _context

Menentukan nilai konteks dari anggota Konteks struktur HDAUDIO_BUS_INTERFACE dan HDAUDIO_BUS_INTERFACE_V2 .

[in] Handle

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

[in] RequestedBufferSize

Menentukan ukuran buffer yang diminta dalam byte.

[out] BufferMdl

Mengambil halaman memori fisik yang berisi buffer yang dialokasikan. Parameter ini menunjuk ke variabel PMDL yang dialokasikan pemanggil tempat rutin menulis penunjuk ke daftar deskriptor memori (MDL) yang menjelaskan buffer.

[out] AllocatedBufferSize

Mengambil ukuran buffer yang dialokasikan dalam byte. Parameter ini menunjuk ke variabel SIZE_T yang dialokasikan pemanggil tempat rutin menulis ukuran buffer yang dialokasikan.

[out] StreamId

Mengambil pengidentifikasi aliran. Parameter ini menunjuk ke variabel UCHAR yang dialokasikan pemanggil tempat rutin menulis pengidentifikasi aliran yang ditetapkannya ke aliran.

[out] FifoSize

Mengambil ukuran FIFO mesin DMA dalam byte. Parameter ini menunjuk ke variabel ULONG yang dialokasikan pemanggil tempat rutin menulis ukuran FIFO.

Nilai kembali

AllocateDmaBuffer 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 di 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

AllocateDmaBuffer Rutinitas ini digunakan bersama dengan rutinitas FreeDmaBuffer. Kedua rutinitas ini hanya tersedia di HDAUDIO_BUS_INTERFACE dan versi HDAUDIO_BUS_INTERFACE_V2 dari HD Audio DDI. DDI ini tidak termasuk rutinitas AllocateContiguousDmaBuffer, SetupDmaEngineWithBdl, dan FreeContiguousDmaBuffer , yang tidak pernah digunakan bersama dan AllocateDmaBufferFreeDmaBuffer. 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.

Jika mesin DMA tidak dapat menggunakan buffer ukuran yang diminta dalam parameter requestedBufferSize, rutin mengalokasikan buffer yang sedekat mungkin dengan ukuran yang diminta.

Driver fungsi untuk codec audio atau modem bertanggung jawab untuk memprogram codec untuk mengelola transfer data dan mengenali pengidentifikasi aliran.

Rutin menghasilkan MDL yang mencantumkan halaman memori fisik yang berisi buffer. Alamat dasar buffer bertepatan dengan awal halaman fisik pertama dalam daftar.

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

Selama panggilan ke AllocateDmaBuffer dan FreeDmaBuffer, 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.

Ukuran FIFO adalah jumlah maksimum byte yang dapat ditahan oleh mesin DMA di buffer internalnya. Tergantung pada implementasi perangkat keras, ukuran FIFO mesin DMA dapat statis atau bervariasi secara dinamis dengan perubahan format aliran. Untuk informasi selengkapnya tentang ukuran FIFO, lihat Spesifikasi Audio Definisi Tinggi Intel di situs web Intel HD Audio .

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

Buffer DMA yang dialokasikan sebelumnya belum dibebaskan (dengan memanggil FreeDmaBuffer).
Aliran berada dalam status selain reset.

Di Windows Server 2003, Windows XP, Windows 2000, dan Windows Me/98, driver audio WDM memanggil rutinitas ini selama eksekusi metode NewStream-nya (pada waktu pembuatan pin) atau metode SetFormat (setelah memanggil salah satu rutinitas AlokasikanXxxDmaEngine di HD Audio DDI). Untuk informasi selengkapnya, lihat IMiniportWavePci::NewStream dan IMiniportWavePciStream::SetFormat.