Поделиться через

Использование слоя отладки DirectML

Слой отладки DirectML — это необязательный компонент времени разработки, который помогает выполнять отладку кода DirectML. При включении уровень отладки DirectML оборачивает вызовы API DirectML и предоставляет дополнительную проверку и сообщения вам как разработчику. Уровень отладки реализуется в отдельной библиотеке, DirectML.Debug.dllкоторая условно загружается во время выполнения основной библиотекой DirectML.dllсреды выполнения.

Настоятельно рекомендуется включить уровень отладки при разработке приложений с помощью DirectML, так как он может предоставлять бесценную информацию в случае недопустимого использования API.

Общие сведения о сообщениях слоя отладки

В приведенном ниже примере кода показано, как уровень отладки может помочь в диагностике неправильного использования API. Этот код пытается создать операцию тождества DirectML; поэтому входные и выходные тензоры должны иметь одинаковую форму и тип данных. Однако в этом примере мы проиллюстрируем ошибку в выходных параметрах тензора.

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 последняя строка для создания оператора неудачно завершается и возвращает E_INVALIDARG(0x80070057). Макрос THROW_IF_FAILED (дополнительные сведения см. в формате WIL) преобразует этот код ошибки в универсальное сообщение "параметр неверный" и выводит его в окно вывода отладчика.

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

Но если уровень отладки DirectML включен , вы увидите дополнительные сведения, чтобы сузить причину:

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.

Обратите внимание, как расширенная информация начинается с ошибки D3D12. Когда уровень отладки DirectML обнаруживает проблему, он всегда предпочитает отправлять сообщения об ошибках в ID3D12InfoQueue, связанный с ID3D12Device, переданным во время создания устройства DirectML. Сообщения об ошибках в информационной очереди всегда имеют префикс D3D12 ERROR, как показано; и они также доступны программным способом с помощью обратного вызова сообщения уровня отладки Direct3D 12 (см. запись блога обратный вызов сообщения уровня отладки Direct3D 12).

Id3D12InfoQueue доступен только в том случае, если уровень отладки Direct3D 12 включен с id3D12Debug::EnableDebugLayer. Хотя всегда желательно включить (или отключить) уровни отладки Direct3D 12 и DirectML вместе, более новые версии DirectML поддерживают базовую проверку параметров без уровня отладки Direct3D 12. Если вы создаете устройство DirectML с DML_CREATE_DEVICE_FLAG_DEBUG в то время как уровень отладки Direct3D 12 не включен, сообщения об ошибках печатаются с помощью OutputDebugStringA:

[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.

Как предполагает предупреждение, лучше всего включить уровень отладки Direct3D 12 при использовании уровня отладки DirectML. Некоторые типы проверки возможны только при включении обоих слоев отладки.

Установка уровней отладки DirectML и Direct3D 12 (системный компонент)

При использовании DirectML в качестве системного компонента (см. журнал версий DirectML), уровень отладки входит в отдельный пакет средств графики, распределенный как компонент по запросу (FOD) (см. функции по запросу). FOD графических инструментов необходимо добавить в вашу систему, чтобы использовать слой отладки с системной версией DirectML. FOD также содержит уровень отладки Direct3D 12, который также полезен (но не требуется) для отладки приложений DirectML.

Чтобы добавить необязательный пакет FOD для графических инструментов, выполните следующую команду из командной строки PowerShell администратора.

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

Кроме того, можно добавить пакет средств графики из параметров Windows. В Windows 10 22H2 и Windows 11 перейдите в Параметры>Система>Дополнительные возможности>Добавить дополнительную возможность, затем найдите графические инструменты. В версиях до Windows 10 22H2 перейдите к разделу Параметры>Приложения>Приложения и возможности>Дополнительные функции>Добавить необязательную функцию.

Установка уровня отладки DirectML (автономная распространяемая версия)

При использовании DirectML в качестве автономной распространяемой библиотеки (см. Microsoft.AI.DirectML), уровень отладки DirectML предоставляется в пакете вместе с основной библиотекой среды выполнения. Поместите и DirectML.Debug.dll, и DirectML.dll рядом с исполняемым файлом вашего приложения.

Если вы используете Visual Studio для добавления Microsoft.AI.DirectML в качестве зависимости пакета NuGet, проект отобразит параметры на странице конфигурации проекта, чтобы скопировать или пропустить копирование основных библиотек среды выполнения и библиотек уровня отладки. По умолчанию пакет NuGet DirectML настраивается для всегдаго копирования обоих библиотек DLL в папку выходных данных проекта. Если уровень отладки не используется, вы можете захотеть не копировать его в релизных сборках.

Распространяемый уровень отладки в Visual Studio

Включение уровня отладки Direct3D 12

Уровень отладки для Direct3D 12 (d3d12sdklayers.dll) не зависит от уровня отладки DirectML (DirectML.Debug.dll): уровень отладки DirectML обеспечивает расширенную проверку использования API DirectML, а уровень отладки Direct3D 12 охватывает использование API Direct3D 12. Однако на практике рекомендуется включить оба уровня отладки при разработке приложений DirectML. Уровень отладки Direct3D 12 устанавливается как часть FOD графических инструментов, как описано выше. Пример того, как активировать слой отладки Direct3D 12, можно найти в ID3D12Debug::EnableDebugLayer.

Это важно

Сначала необходимо включить уровень отладки Direct3D 12. Затем включите уровень отладки DirectML, вызвав DMLCreateDevice.

Включение уровня отладки DirectML

Уровень отладки DirectML можно включить, указав DML_CREATE_DEVICE_FLAG_DEBUG при вызове DMLCreateDevice.

После включения уровня отладки DirectML любые ошибки DirectML или недопустимые вызовы API будут вызывать сведения об отладке в качестве выходных данных отладки. Вот пример.

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

До DML_FEATURE_LEVEL_5_2 необходимо включить уровень отладки Direct3D 12, чтобы активировать уровень отладки DirectML. В более ранних версиях DirectML, если флаг DML_CREATE_DEVICE_FLAG_DEBUG указан в флагах, а слои отладки не установлены, то DMLCreateDevice возвращает DXGI_ERROR_SDK_COMPONENT_MISSING. В более новых версиях DirectML сообщения отправляются в OutputDebugStringA , когда ID3D12InfoQueue недоступен.

Пример кода

Следующий код иллюстрирует включение уровней отладки Direct3D 12 и DirectML только для отладочных сборок.

// 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));

См. также

  • Last updated on