PSETUP_DMA_ENGINE_WITH_BDL fungsi panggilan balik (hdaudio.h)

Artikel
07/27/2023

Rutinitas SetupDmaEngineWithBdl menyiapkan mesin DMA untuk menggunakan buffer DMA yang dialokasikan pemanggil.

Jenis penunjuk fungsi untuk rutinitas SetupDmaEngineWithBdl didefinisikan sebagai berikut.

Sintaks

PSETUP_DMA_ENGINE_WITH_BDL PsetupDmaEngineWithBdl;

NTSTATUS PsetupDmaEngineWithBdl(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
  [in]  ULONG BufferLength,
  [in]  ULONG Lvi,
  [in]  PHDAUDIO_BDL_ISR Isr,
  [in]  PVOID Context,
  [out] PUCHAR StreamId,
  [out] PULONG FifoSize
)
{...}

Parameter

[in] _context

Menentukan nilai konteks dari anggota Konteks struktur HDAUDIO_BUS_INTERFACE_BDL .

[in] Handle

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

[in] BufferLength

Panjang buffer.

[in] Lvi

Menentukan indeks terakhir yang valid (LVI). Parameter ini berisi indeks untuk deskriptor buffer terakhir yang valid di BDL. Setelah mesin DMA memproses deskriptor ini, mesin membungkus kembali ke deskriptor pertama dalam daftar dan melanjutkan pemrosesan. Jika BDL berisi n deskriptor, mereka diberi nomor 0 hingga n-1. Nilai lvi harus minimal 1; dengan kata lain, BDL harus berisi setidaknya dua entri yang valid sebelum mesin DMA dapat memulai operasi.

[in] Isr

Penunjuk fungsi ke ISR pemanggil. Jika pemanggil mengatur bit interupsi-on-completion (IOC) dalam satu atau beberapa deskriptor buffer di BDL, driver bus HD Audio memanggil ISR setiap kali interupsi IOC terjadi pada aliran. Parameter ini adalah penunjuk fungsi jenis HDAUDIO_BDL_ISR, yang didefinisikan di bagian Keterangan berikut.

[in] Context

Konteksnya.

[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 UINT yang dialokasikan pemanggil tempat rutin menulis ukuran FIFO.

Nilai kembali

SetupDmaEngineWithBdl 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_INVALID_HANDLE	Menunjukkan bahwa nilai parameter handel tidak valid.
STATUS_INVALID_PARAMETER	Menunjukkan bahwa salah satu nilai parameter salah (penunjuk buruk atau format aliran yang tidak valid).
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 perangkat DMA atau buffer DMA tidak dialokasikan atau aliran tidak dalam status Reset.

Keterangan

Rutinitas SetupDmaEngineWithBdl digunakan bersama dengan rutinitas AllocateContiguousDmaBuffer 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 mengalokasikan buffer DMA dan mengonfigurasi mesin DMA untuk menggunakan buffer.

Pemanggil harus memanggil AllocateContiguousDmaBuffer untuk mengalokasikan penyimpanan dalam memori sistem untuk buffer DMA dan BDL yang menjelaskan halaman memori fisik di buffer. Entri BDL harus berada dalam memori yang secara fisik berdampingan. Memori BDL dan buffer harus memenuhi persyaratan penyelarasan yang dijelaskan dalam Spesifikasi Audio Definisi Tinggi Intel (lihat situs web Intel HD Audio ).

Baik memori BDL maupun buffer yang dijelaskannya harus tetap valid selama operasi DMA. Setelah panggilan ke SetupDmaEngineWithBdl, memori BDL dan buffer harus tetap valid selama mesin DMA terus menggunakan buffer. Mesin DMA menggunakan buffer hingga driver fungsi mengganti buffer dengan memanggil SetupDmaEngineWithBdl lagi atau membebaskan mesin DMA dengan memanggil FreeDmaEngine. Driver fungsi bertanggung jawab untuk memanggil FreeContiguousDmaBuffer untuk membebaskan buffer dan BDL ketika mereka tidak lagi diperlukan.

Saat mengalokasikan memori untuk buffer, pemanggil harus memenuhi semua batasan perangkat keras untuk alamat, panjang, dan penyelarasan blok memori yang berdekatan secara fisik yang ditentukan BDL. Dengan demikian, hanya klien dengan pengetahuan yang signifikan tentang pengontrol bus dan perangkat keras sistem yang harus menggunakan rutinitas SetupDmaEngineWithBdl .

Sebelum memanggil SetupDmaEngineWithBdl untuk mengonfigurasi mesin DMA, klien harus memanggil AllocateCaptureDmaEngine atau AllocateRenderDmaEngine untuk mengalokasikan mesin DMA. Parameter handle adalah nilai yang diperoleh dari panggilan sebelumnya ke Alokasikan XxxDmaEngine.

Pemanggil bertanggung jawab untuk memprogram codec untuk mengelola transfer data dan mengenali pengidentifikasi aliran.

Driver audio WDM memanggil rutinitas ini pada waktu pembuatan pin selama eksekusi metode NewStream-nya (misalnya, lihat IMiniportWavePci::NewStream).

Setelah panggilan ke SetupDmaEngineWithBdl, mesin DMA berada dalam status Reset. Untuk memulai mesin DMA, panggil SetDmaEngineState.

Parameter isr menentukan ISR yang dipanggil oleh driver bus HD Audio setiap kali gangguan IOC terjadi pada aliran. Parameter ini adalah penunjuk fungsi jenis HDAUDIO_BDL_ISR, yang didefinisikan sebagai:

typedef void
  (*PHDAUDIO_BDL_ISR)
    (IN VOID *Context, IN ULONG InterruptBitMask);

Driver bus HD Audio memanggil ISR dengan nilai konteks yang sama dengan yang ditentukan klien dalam parameter konteks panggilan SetupDmaEngineWithBdl sebelumnya. Parameter interruptBitMask berisi bit dari daftar status streaming perangkat pengontrol HD Audio yang menunjukkan alasan gangguan. Tabel berikut menunjukkan arti bit individual dalam interruptBitMask.

Angka Bit	Makna
31:5	Tidak digunakan.
4	Kesalahan Deskriptor (DESE). Jika terjadi kesalahan selama pengambilan deskriptor buffer, maka pengontrol Hd Audio mengatur bit DESE ke 1.
3	Kesalahan FIFO (FIFOE). Jika terjadi kesalahan FIFO (overrun pada aliran output atau underrun pada aliran input), maka pengontrol HD Audio mengatur FIFOE bit ke 1.
2	Status Gangguan Penyelesaian Buffer (BCIS). Jika bit IOC diatur ke 1 dalam byte perintah deskriptor buffer, maka pengontrol HD Audio mengatur bit BCIS ke 1 setelah sampel terakhir buffer diproses.
1:0	Tidak digunakan.

Driver bus HD Audio mengatur bit yang tidak digunakan ke nol. Alih-alih berasumsi bahwa gangguan IOC telah terjadi, ISR harus selalu memeriksa parameter interruptBitMask untuk menentukan apakah kesalahan aliran telah terjadi. Untuk informasi selengkapnya tentang bit status interupsi yang ditunjukkan dalam tabel sebelumnya, lihat deskripsi daftar status aliran dalam Spesifikasi Audio Definisi Tinggi Intel.

Ukuran FIFO adalah jumlah maksimum byte yang dapat ditahan mesin DMA dalam buffer internalnya kapan saja. 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.

Pemanggil harus mengalokasikan memori buffer dan BDL dari kumpulan yang tidak disebarkan.