DirectML hata ayıklama katmanını kullanma

DirectML hata ayıklama katmanı, DirectML kodunuzun hatalarını ayıklamanıza yardımcı olan isteğe bağlı bir geliştirme zamanı bileşenidir. Etkinleştirildiğinde, DirectML hata ayıklama katmanı DirectML API çağrılarını sarmalar ve geliştirici olarak size ek doğrulama ve iletiler sağlar. Hata ayıklama katmanı, ayrı bir DirectML.Debug.dll kitaplıkta uygulanır ve bu kitaplık çalışma zamanında çekirdek çalışma zamanı kitaplığı DirectML.dll tarafından koşullu olarak yüklenir.

Geçersiz API kullanımı durumunda çok değerli bilgiler sağlayabildiği için DirectML kullanarak uygulama geliştirirken hata ayıklama katmanını etkinleştirmenizi kesinlikle öneririz.

Hata ayıklama katmanı iletilerine genel bakış

Aşağıdaki kod örneğinde hata ayıklama katmanının yanlış API kullanımını tanılamaya nasıl yardımcı olabileceği gösterilmektedir. Bu kod bir DirectML kimlik işlemi oluşturmayı dener; bu nedenle giriş ve çıkış tensorları aynı şekil ve veri türüne sahip olmalıdır. Ancak, bu örnekte çıkış tensor parametrelerinde bir hata gösterilmektedir.

uint32_t sizes[] = { 1 };

DML_BUFFER_TENSOR_DESC inputBufferDesc = {};
inputBufferDesc.DataType = DML_TENSOR_DATA_TYPE_FLOAT32;
inputBufferDesc.DimensionCount = ARRAYSIZE(sizes);
inputBufferDesc.Sizes = sizes;
inputBufferDesc.TotalTensorSizeInBytes = 256;

DML_BUFFER_TENSOR_DESC outputBufferDesc = {};
outputBufferDesc.DataType = DML_TENSOR_DATA_TYPE_FLOAT16; // Invalid: doesn't match input type!
outputBufferDesc.DimensionCount = ARRAYSIZE(sizes);
outputBufferDesc.Sizes = sizes;
outputBufferDesc.TotalTensorSizeInBytes = 256;

DML_TENSOR_DESC inputDesc = { DML_TENSOR_TYPE_BUFFER, &inputBufferDesc };
DML_TENSOR_DESC outputDesc = { DML_TENSOR_TYPE_BUFFER, &outputBufferDesc };

DML_ELEMENT_WISE_IDENTITY_OPERATOR_DESC identityDesc = {};
identityDesc.InputTensor = &inputDesc;
identityDesc.OutputTensor = &outputDesc;

DML_OPERATOR_DESC opDesc = { DML_OPERATOR_ELEMENT_WISE_IDENTITY, &identityDesc };

Microsoft::WRL::ComPtr<IDMLOperator> op;
THROW_IF_FAILED(dmlDevice->CreateOperator(&opDesc, IID_PPV_ARGS(&op)));

DirectML hata ayıklama katmanı olmadan, işleci oluşturmak için son satır başarısız olur ve döndürür E_INVALIDARG (0x80070057). Makro THROW_IF_FAILED (daha fazla ayrıntı için bkz . WIL), bu hata kodunu "parametre yanlış" genel iletisine çevirir ve hata ayıklayıcı çıkış penceresine yazdırır.

TensorValidator.h(203)\DirectML.dll!00007FF83D25ADC9: (caller: 00007FF83D267523) Exception(1) tid(3b54) 80070057 The parameter is incorrect.

Ancak DirectML hata ayıklama katmanı etkinleştirildiğinde , nedeni daraltmak için ek bilgiler görürsünüz:

D3D12 ERROR: Mismatched tensor data types. Tensor 'Output' has DataType of DML_TENSOR_DATA_TYPE_FLOAT16, while tensor 'Input' has DataType of DML_TENSOR_DATA_TYPE_FLOAT32. Both tensors are expected to have the same DataType. [ UNKNOWN ERROR #1: STRING_FROM_APPLICATION]

TensorValidator.h(203)\DirectML.Debug.dll!00007FF86DF66ADA: (caller: 00007FF86DF81646) Exception(1) tid(9f34) 80070057 The parameter is incorrect.

Genişletilmiş bilgilerin D3D12 ERROR ile nasıl başladığına dikkat edin. DirectML hata ayıklama katmanı bir sorun algıladığında, her zaman DirectML cihaz oluşturma sırasında geçirilen ID3D12Device ile ilişkili ID3D12InfoQueue'ye hata iletileri göndermeyi tercih eder. Yukarıda gösterildiği gibi, bilgi kuyruğundaki hata iletilerine her zaman D3D12 ERROR ön eki eklenir; ve direct3D 12 hata ayıklama katmanı ileti geri çağırma kullanarak program aracılığıyla da erişilebilirler ( D3D12 hata ayıklama katmanı ileti geri çağırma blog gönderisine bakın).

ID3D12InfoQueue yalnızca Direct3D 12 hata ayıklama katmanı ID3D12Debug::EnableDebugLayer ile etkinleştirildiğinde kullanılabilir. Direct3D 12 ve DirectML hata ayıklama katmanlarını birlikte etkinleştirmek (veya devre dışı bırakmak) her zaman tercih edilir ancak DirectML'nin daha yeni sürümleri Direct3D 12 hata ayıklama katmanı olmadan temel parametre doğrulamasını destekler. Direct3D 12 hata ayıklama katmanı etkinleştirilmemişken DML_CREATE_DEVICE_FLAG_DEBUG ile bir DirectML cihazı oluşturursanız, bunun yerine OutputDebugStringA kullanılarak hata iletileri yazdırılır:

[DIRECTML WARNING]: enable the D3D debug layer for enhanced validation with DML_CREATE_DEVICE_FLAG_DEBUG.

[DIRECTML ERROR]: Mismatched tensor data types. Tensor 'Output' has DataType of DML_TENSOR_DATA_TYPE_FLOAT16, while tensor 'Input' has DataType of DML_TENSOR_DATA_TYPE_FLOAT32. Both tensors are expected to have the same DataType.

TensorValidator.h(218)\DirectML.Debug.dll!00007FF820C43AFB: (caller: 00007FF820C01CD1) Exception(1) tid(5df8) 80070057 The parameter is incorrect.

Uyarı iletisinde de belirtildiği gibi, DirectML hata ayıklama katmanını kullanırken Direct3D 12 hata ayıklama katmanını etkinleştirmek en iyisidir. Bazı doğrulama türleri yalnızca her iki hata ayıklama katmanı da etkinleştirildiğinde mümkündür.

DirectML ve Direct3D 12 hata ayıklama katmanlarını yükleme (sistem bileşeni)

DirectML'yi sistem bileşeni olarak kullanırken (bkz . DirectML sürüm geçmişi), hata ayıklama katmanı isteğe bağlı özellik (FOD) olarak dağıtılmış ayrı bir Grafik Araçları paketinin parçasıdır (bkz. İsteğe Bağlı Özellikler). Hata ayıklama katmanını DirectML'nin sistem sürümüyle kullanabilmek için Grafik Araçları FOD'sinin sisteminize eklenmesi gerekir. FOD ayrıca DirectML uygulamalarında hata ayıklamak için yararlı (ancak gerekli olmayan) Direct3D 12 hata ayıklama katmanını da içerir.

İsteğe bağlı Grafik Araçları FOD paketini eklemek için yönetici PowerShell isteminden aşağıdaki komutu çalıştırın.

Add-WindowsCapability -Online -Name "Tools.Graphics.DirectX~~~~0.0.1.0"

Alternatif olarak, Grafik Araçları paketini Windows Ayarları'ndan da ekleyebilirsiniz. Windows 10 22H2 ve Windows 11'de Ayarlar>Sistem>İsteğe bağlı özellikler>İsteğe bağlı özellik ekle'ye gidin ve Grafik Araçları'nı arayın. Windows 10 22H2'den eski sürümlerde Ayarlar>Uygulamalar Uygulamalar>ve özellikler>>Bunun yerine isteğe bağlı özellik ekleyin seçeneğine gidin.

DirectML hata ayıklama katmanını yükleme (tek başına yeniden dağıtılabilir)

DirectML'yi tek başına yeniden dağıtılabilir kitaplık olarak kullanırken (bkz . Microsoft.AI.DirectML), çekirdek çalışma zamanı kitaplığının yanı sıra pakette DirectML hata ayıklama katmanı sağlanır. Uygulamanızın yürütülebilir dosyasının yanına hem DirectML.Debug.dll hem de DirectML.dll yerleştirin.

Visual Studio'yu kullanarak Microsoft.AI.DirectML'yi bir NuGet paketi bağımlılığı olarak eklerseniz, proje yapılandırma sayfasında çekirdek çalışma zamanı ve hata ayıklama katmanı kütüphanelerini kopyalama veya kopyalamama seçeneklerini gösterir. Varsayılan olarak, DirectML NuGet paketi her zaman her iki DLL'yi de proje çıkış klasörünüze kopyalanacak şekilde yapılandırılır. Ancak, hata ayıklama katmanı kullanılmıyorsa sürüm derlemelerinde hata ayıklama katmanını kopyalamayı atlamak isteyebilirsiniz.

Direct3D 12 Hata Ayıklama Katmanını Etkinleştirme

Direct3D 12 (d3d12sdklayers.dll) için hata ayıklama katmanı DirectML hata ayıklama katmanından (DirectML.Debug.dll) bağımsızdır: DirectML hata ayıklama katmanı DirectML API kullanımı için gelişmiş doğrulama sağlar ve Direct3D 12 hata ayıklama katmanı Direct3D 12 API kullanımını kapsar. Ancak uygulamada, DirectML uygulamaları geliştirirken her iki hata ayıklama katmanını da etkinleştirmek en iyisidir. Direct3D 12 hata ayıklama katmanı, yukarıda açıklanan Grafik Araçları FOD'sinin bir parçası olarak yüklenir. Direct3D 12 hata ayıklama katmanını etkinleştirme örneği için ID3D12Debug::EnableDebugLayer'a bakın.

Önemli

Önce Direct3D 12 hata ayıklama katmanını etkinleştirmeniz gerekir. ArdındanDMLCreateDevice'i çağırarak DirectML hata ayıklama katmanını etkinleştirin.

DirectML hata ayıklama katmanını etkinleştirme

DMLCreateDevice çağırdığınızda DML_CREATE_DEVICE_FLAG_DEBUG sağlayarak DirectML hata ayıklama katmanını etkinleştirebilirsiniz.

DirectML hata ayıklama katmanını etkinleştirdikten sonra, tüm DirectML hataları veya geçersiz API çağrıları hata ayıklama bilgilerinin hata ayıklama çıkışı olarak yayımlanmasına neden olur. İşte bir örnek.

DML_OPERATOR_CONVOLUTION: invalid D3D12_HEAP_TYPE. DirectML requires all bound buffers to be D3D12_HEAP_TYPE_DEFAULT.

DML_FEATURE_LEVEL_5_2 kadar DirectML hata ayıklama katmanını etkinleştirmek için Direct3D 12 hata ayıklama katmanını etkinleştirmeniz gerekir. DirectML'nin önceki sürümlerinde , bayraklarda DML_CREATE_DEVICE_FLAG_DEBUG bayrağı belirtilirse ve hata ayıklama katmanları yüklü değilse , DMLCreateDeviceDXGI_ERROR_SDK_COMPONENT_MISSING döndürür. DirectML'nin daha yeni sürümlerinde, ID3D12InfoQueue kullanılamadığında iletiler OutputDebugStringA'ya gönderilir.

Kod örneği

Aşağıdaki kod, yalnızca hata ayıklama derlemeleri için hem Direct3D 12 hem de DirectML hata ayıklama katmanlarını etkinleştirmeyi gösterir.

// By default, disable the DirectML debug layer.
DML_CREATE_DEVICE_FLAGS dmlCreateDeviceFlags = DML_CREATE_DEVICE_FLAG_NONE;

#if defined(_DEBUG)
// If the project is in a debug build, then enable the Direct3D 12 debug layer.
// This is optional (starting in DML_FEATURE_LEVEL_5_2) but strongly recommended!
Microsoft::WRL::ComPtr<ID3D12Debug> debugController;
if (SUCCEEDED(D3D12GetDebugInterface(IID_PPV_ARGS(&debugController))))
{
    debugController->EnableDebugLayer();
}

// If the project is in a debug build, then enable debugging via DirectML debug layers with this flag.
dmlCreateDeviceFlags |= DML_CREATE_DEVICE_FLAG_DEBUG;
#endif

// Create the DirectML device.
Microsoft::WRL::ComPtr<IDMLDevice> dmlDevice;
THROW_IF_FAILED(DMLCreateDevice(
    d3D12Device.Get(),
    dmlCreateDeviceFlags,
    IID_PPV_ARGS(&dmlDevice));

Ayrıca bakınız

• Windows AI
• DMLCreateDevice işlevi
• İsteğe bağlı kullanılabilir özellikler
• Direct3D 12 Hata Ayıklama Katmanı ile GPU tabanlı doğrulamayı kullanma
• Direct3D 12 Hata Ayıklama Katmanı Referansı