DXGKDDI_RENDER fungsi panggilan balik (d3dkmddi.h)

Artikel
03/08/2023

Fungsi DxgkDdiRender menghasilkan buffer akses memori langsung (DMA) dari buffer perintah yang diteruskan driver tampilan mode pengguna.

Sintaks

DXGKDDI_RENDER DxgkddiRender;

NTSTATUS DxgkddiRender(
  [in]     IN_CONST_HANDLE hContext,
  [in/out] INOUT_PDXGKARG_RENDER pRender
)
{...}

Parameter

[in] hContext

Handel ke konteks perangkat untuk DMA dan buffer perintah. Fungsi DxgkDdiCreateContext driver miniport tampilan sebelumnya mengembalikan handel ini di anggota hContext dari struktur DXGKARG_CREATECONTEXT yang ditunjukkan parameter pCreateContext dari DxgkDdiCreateContext .

Jika driver tidak mendukung pembuatan konteks, subsistem kernel grafis Microsoft DirectX menggantikan handel ke konteks dengan handel ke perangkat. Fungsi DxgkDdiCreateDevice driver miniport tampilan sebelumnya mengembalikan handel perangkat di anggota hDevice dari struktur DXGKARG_CREATEDEVICE yang ditunjukkan parameter pCreateDevice dari DxgkDdiCreateDevice .

[in/out] pRender

Penunjuk ke struktur DXGKARG_RENDER yang berisi informasi tentang DMA dan buffer perintah.

Nilai kembali

DxgkDdiRender mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
STATUS_SUCCESS	Seluruh buffer perintah diterjemahkan.
STATUS_NO_MEMORY	DxgkDdiRender tidak dapat mengalokasikan memori yang diperlukan untuk menyelesaikannya.
STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER	Buffer DMA saat ini habis.
STATUS_PRIVILEGED_INSTRUCTION	DxgkDdiRender mendeteksi instruksi nonprivileged (yaitu, instruksi yang mengakses memori di luar hak istimewa dari proses unit pemrosesan pusat [CPU] saat ini).
STATUS_ILLEGAL_INSTRUCTION	DxgkDdiRender mendeteksi instruksi yang tidak dapat didukung perangkat keras grafis.
STATUS_INVALID_PARAMETER	DxgkDdiRender mendeteksi parameter instruksi yang tidak dapat didukung perangkat keras grafis; namun, perangkat keras grafis dapat mendukung instruksi itu sendiri. Driver tidak diperlukan untuk mengembalikan kode galat ini. Sebaliknya, ini dapat mengembalikan STATUS_ILLEGAL_INSTRUCTION ketika mendeteksi parameter instruksi yang tidak didukung.
STATUS_INVALID_USER_BUFFER	DxgkDdiRender mendeteksi data atau instruksi underrun atau overrun. Artinya, driver menerima lebih sedikit atau lebih banyak instruksi atau data dari yang diharapkan. Driver tidak diperlukan untuk mengembalikan kode galat ini. Sebaliknya, ini dapat mengembalikan STATUS_ILLEGAL_INSTRUCTION ketika mendeteksi data atau instruksi yang diserap atau diserbu.
STATUS_INVALID_HANDLE	DxgkDdiRender mendeteksi handel yang tidak valid di buffer perintah.
STATUS_GRAPHICS_DRIVER_MISMATCH	Driver miniport tampilan tidak kompatibel dengan driver tampilan mode pengguna yang memulai panggilan ke DxgkDdiRender (yaitu, mengirimkan buffer perintah).
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE	Driver miniport tampilan mendeteksi kesalahan dalam aliran DMA. Perangkat konteks grafis ditempatkan dalam status hilang jika driver mengembalikan kode kesalahan ini.

Keterangan

Subsistem kernel grafis DirectX memanggil fungsi DxgkDdiRender driver miniport tampilan untuk menghasilkan buffer DMA dari buffer perintah yang dilewati driver tampilan mode pengguna. Ketika driver miniport tampilan diterjemahkan dari buffer perintah ke buffer DMA, driver juga harus memvalidasi buffer perintah untuk memastikan bahwa buffer perintah tidak berisi perintah atau perintah istimewa apa pun yang dapat digunakan untuk mengakses memori yang bukan milik proses. Selain buffer DMA output, driver miniport tampilan juga harus menghasilkan daftar lokasi patch output. Manajer memori video menggunakan daftar ini untuk memisahkan dan mem-patch buffer DMA dengan tepat.

Baik buffer perintah pCommand dan daftar lokasi patch input pPatchLocationListIn yang dihasilkan driver tampilan mode pengguna dialokasikan dari ruang alamat mode pengguna dan diteruskan ke driver miniport tampilan tidak tersentuh. Driver miniport tampilan harus menggunakan __try/__except kode pada akses apa pun ke buffer dan daftar dan harus memvalidasi konten buffer dan daftar sebelum menyalin konten ke masing-masing buffer kernel (yaitu, sebelum menyalin konten anggota pCommand ke anggota pDmaBuffer dan konten anggota pPatchLocationListIn ke anggota pPatchLocationListOut , yang merupakan semua anggota struktur DXGKARG_RENDER yang dirujuk parameter pRender ).

Berikut adalah contoh bagaimana driver miniport tampilan harus mengakses buffer ini menggunakan __try dan __except logika. AllocationListIn menunjuk ke buffer mode pengguna.

__try
  {
    for (Index = 0; Index < AllocationListInSize; AllocationTable++, 
           AllocationListIn++, AllocationListOut++, Index++) 
    {
      D3DKMT_HANDLE AllocationHandle = AllocationListIn->hAllocation;
      . . .
    }
  }
__except(EXCEPTION_EXECUTE_HANDLER)
  {
    Status = STATUS_INVALID_PARAMETER;
    SAMPLE_LOG_ERROR(
  "Exception occurred accessing user-mode allocation list. Returning Status=0x%I64x",
      Status);
    goto cleanup;
  }

Catatan

Akses ke buffer kernel tidak memerlukan perlindungan dari try/except kode.

Driver miniport tampilan tidak diperlukan untuk menggunakan informasi yang disediakan driver tampilan mode pengguna jika membuat ulang informasi lebih optimal. Misalnya, jika pPatchLocationListIn kosong karena driver tampilan mode pengguna tidak menyediakan daftar lokasi patch input, driver miniport tampilan dapat menghasilkan konten pPatchLocationListOut berdasarkan konten buffer perintah sebagai gantinya.

Daftar alokasi yang disediakan driver tampilan mode pengguna divalidasi, disalin, dan dikonversi menjadi daftar alokasi mode kernel selama transisi kernel. Subsistem kernel grafis DirectX mengonversi setiap elemen D3DDDI_ALLOCATIONLIST menjadi elemen DXGK_ALLOCATIONLIST dengan mengonversi handel yang diketik D3DKMT_HANDLE yang disediakan driver tampilan mode pengguna menjadi handel khusus perangkat, yang dikembalikan oleh fungsi DxgkDdiOpenAllocation driver miniport tampilan. Indeks setiap alokasi dan status tulis alokasi (yaitu, pengaturan bendera bit-field WriteOperation ) tetap konstan selama konversi.

Selain handel khusus perangkat, subsistem kernel grafis DirectX menyediakan driver miniport tampilan dengan alamat segmen GPU terakhir yang diketahui untuk setiap alokasi. Jika indeks alokasi N saat ini di-page out, subsistem kernel grafis DirectX mengatur anggota SegmentId dari elemen Nth dari anggota pAllocationListdari DXGKARG_RENDER ke nol. Jika anggota SegmentId dari elemen Nth dari daftar alokasi tidak diatur ke nol, driver miniport tampilan harus melakukan pra-patch buffer DMA yang dihasilkan dengan informasi alamat segmen yang disediakan. Driver harus melakukan pra-patch ketika diminta karena subsistem kernel grafis DirectX mungkin tidak memanggil fungsi DxgkDdiPatch pada buffer DMA yang seharusnya telah di-patch dengan benar oleh driver.

Catatan

Meskipun fungsi DxgkDdiRender driver melakukan pra-patch pada buffer DMA, driver masih harus menyisipkan semua referensi ke alokasi ke dalam daftar lokasi patch output yang ditentukan anggota pPatchLocationListOutdari DXGKARG_RENDER . Daftar ini harus berisi semua referensi karena alamat alokasi mungkin berubah sebelum buffer DMA dikirimkan ke GPU; oleh karena itu, subsistem kernel grafis DirectX akan memanggil fungsi DxgkDdiPatch untuk mengirimkan ulang buffer DMA.

Untuk membatalkan alokasi, driver miniport tampilan dapat menentukan elemen dalam daftar alokasi yang mereferensikan handel NULL dan kemudian dapat menggunakan elemen lokasi patch yang mereferensikan alokasi NULL . Biasanya, driver harus menggunakan elemen pertama dari daftar alokasi (elemen 0) sebagai elemen NULL .

Ketika driver miniport tampilan menerjemahkan buffer perintah ke buffer DMA, driver miniport tampilan dan driver tampilan mode pengguna harus melakukan tindakan berikut untuk situasi berikut:

Dalam mode DMA kontrak yang dijamin (untuk informasi selengkapnya, lihat Menggunakan Model Buffer DMA Kontrak Terjamin), driver tampilan mode pengguna harus menjamin sumber daya yang cukup untuk perintah terjemahan. Jika sumber daya yang cukup tidak ada untuk terjemahan, driver miniport tampilan harus menolak buffer DMA.
Driver tampilan mode pengguna harus selalu membagi perintah yang mungkin diterjemahkan ke lebih dari ukuran buffer DMA tunggal karena fungsi DxgkDdiRender driver miniport tampilan tidak dapat menangani satu perintah yang lebih besar dari ukuran buffer DMA dan yang tidak dapat dipisahkan.

DxgkDdiRender harus dibuat dapat dipaginasi.

Dukungan untuk fungsi DxgkDdiRenderKm ditambahkan dimulai dengan Windows 7 untuk adaptor tampilan yang mendukung Akselerasi Perangkat Keras GDI.