PSET_DMA_ENGINE_STATE fungsi panggilan balik (hdaudio.h)

Artikel
07/27/2023

Rutinitas SetDmaEngineState mengatur status satu atau beberapa mesin DMA ke status Berjalan, Dihentikan, Dijeda, atau Reset.

Jenis penunjuk fungsi untuk rutinitas SetDmaEngineState didefinisikan sebagai berikut.

Sintaks

PSET_DMA_ENGINE_STATE PsetDmaEngineState;

NTSTATUS PsetDmaEngineState(
  [in] PVOID _context,
  [in] HDAUDIO_STREAM_STATE StreamState,
  [in] ULONG NumberOfHandles,
  [in] PHANDLE Handles
)
{...}

Parameter

[in] _context

Menentukan nilai konteks dari anggota Konteks struktur HDAUDIO_BUS_INTERFACE, HDAUDIO_BUS_INTERFACE_V2, atau HDAUDIO_BUS_INTERFACE_BDL .

[in] StreamState

Menentukan status aliran baru. Atur parameter ini ke salah satu nilai enumerasi HDAUDIO_STREAM_STATE berikut:

PauseState (dijeda)
ResetState (reset)
RunState (berjalan)
StopState (dihentikan)

Dalam implementasi saat ini, PauseState dan StopState mewakili status perangkat keras yang sama.

[in] NumberOfHandles

Menentukan jumlah handel dalam array handel . Atur parameter ini ke nilai bukan nol.

[in] Handles

Penunjuk ke array handel ke mesin DMA. Tentukan nilai non-NULL untuk parameter ini.

Nilai kembali

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

Menampilkan kode	Deskripsi
STATUS_INVALID_HANDLE	Menunjukkan bahwa salah satu handel tidak valid.
STATUS_INVALID_PARAMETER	Menunjukkan bahwa salah satu nilai parameter salah (nilai parameter tidak valid atau penunjuk buruk).
STATUS_INVALID_DEVICE_REQUEST	Menunjukkan bahwa tidak ada buffer yang saat ini dialokasikan untuk salah satu mesin DMA.

Keterangan

Rutinitas ini mengubah status satu atau beberapa mesin DMA ke status yang ditentukan parameter streamState . Rutinitas menyinkronkan transisi status semua mesin DMA yang ditangani dalam menangani array identifikasi. Untuk informasi selengkapnya, lihat Menyinkronkan Dua Aliran atau Lebih.

Sebelum memanggil rutinitas ini, siapkan setiap mesin DMA dalam array handel :

Jika menggunakan versi HDAUDIO_BUS_INTERFACE dari HD Audio DDI, panggil AllocateDmaBuffer untuk menyiapkan mesin DMA.
Jika menggunakan versi HDAUDIO_BUS_INTERFACE_BDL DDI, panggil SetupDmaEngineWithBdl untuk menyiapkan mesin DMA.

Jika saat ini tidak ada buffer DMA yang dialokasikan untuk mesin DMA apa pun dalam array handel , upaya untuk mengubah aliran ke status apa pun selain Reset menyebabkan panggilan SetDmaEngineState gagal dan mengembalikan kode kesalahan STATUS_INVALID_DEVICE_REQUEST.

Status aliran tidak dapat bertransisi langsung antara Berjalan dan Reset. Sebagai gantinya, aliran harus terlebih dahulu melewati status perantara Dijeda atau Dihentikan:

Dari status Berjalan atau Reset, status aliran dapat berubah langsung menjadi Dijeda atau Dihentikan.
Dari status dijeda atau dihentikan, status aliran dapat berubah langsung menjadi Berjalan atau Reset.

Driver audio WDM memanggil rutinitas ini selama panggilan ke metode SetState-nya . Misalnya, lihat IMiniportWaveCyclicStream::SetState.