Megjegyzés
Az oldalhoz való hozzáféréshez engedély szükséges. Megpróbálhat bejelentkezni vagy módosítani a címtárat.
Az oldalhoz való hozzáféréshez engedély szükséges. Megpróbálhatja módosítani a címtárat.
A DirectML hibakeresési réteg egy nem kötelező fejlesztési idő összetevő, amely segít a DirectML-kód hibakeresésében. Ha engedélyezve van, a DirectML hibakeresési réteg körbefuttatja a DirectML API-hívásokat, és további érvényesítési és üzeneteket biztosít Önnek fejlesztőként. A hibakeresési réteg egy külön kódtárban van implementálva, DirectML.Debug.dllamelyet a központi futtatókörnyezeti kódtár DirectML.dllfeltételesen tölt be futásidőben.
Javasoljuk, hogy engedélyezze a hibakeresési réteget az alkalmazások DirectML használatával történő fejlesztése során, mert érvénytelen API-használat esetén felbecsülhetetlen értékű információkat biztosíthat.
A hibakeresési rétegüzenetek áttekintése
Az alábbi kód példája bemutatja, hogyan segíthet a hibakeresési réteg a helytelen API-használat diagnosztizálásában. Ez a kód directML-identitásműveletet próbál létrehozni; így a bemeneti és kimeneti tenzoroknak azonos alakúnak és adattípusúnak kell lennie. Ebben a példában azonban egy hibát mutatunk be a kimeneti tenzorparaméterekben.
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)));
A DirectML hibakeresési réteg nélkül az operátor létrehozásához használt utolsó sor meghiúsul, és visszaadja E_INVALIDARG (0x80070057). A THROW_IF_FAILED makró (további részletekért lásd a WIL-t) lefordítja a hibakódot a "paraméter helytelen" általános üzenetre, és kinyomtatja a hibakereső kimeneti ablakába.
TensorValidator.h(203)\DirectML.dll!00007FF83D25ADC9: (caller: 00007FF83D267523) Exception(1) tid(3b54) 80070057 The parameter is incorrect.
Ha azonban engedélyezve van a DirectML hibakeresési rétege, további információ jelenik meg az ok szűkítéséhez:
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.
Figyelje meg, hogyan kezdődik a kiterjesztett információ a D3D12 ERROR-vel. Amikor a DirectML hibakeresési réteg hibát észlel, mindig előnyben részesíti, hogy a hibaüzeneteket az ID3D12InfoQueue küldje, amely a DirectML-eszköz létrehozása során átadott ID3D12Device-hez van társítva. Az információs üzenetsor hibaüzenetei mindig D3D12 HIBA előtaggal vannak elnevezve, a fent látható módon; és programozott módon is elérhetők a Direct3D 12 hibakeresési rétegbeli üzenetvisszahívással (lásd a D3D12 hibakeresési rétegbeli üzenetvisszahívását).
Az ID3D12InfoQueue csak akkor érhető el, ha a Direct3D 12 hibakeresési réteg engedélyezve van az ID3D12Debug::EnableDebugLayer beállítással. Bár mindig előnyös a Direct3D 12 és a DirectML hibakeresési rétegeinek engedélyezése (vagy letiltása), a DirectML újabb verziói támogatják az alapszintű paraméterérvényesítést a Direct3D 12 hibakeresési réteg nélkül. Ha egy DirectML-eszközt hoz létre a DML_CREATE_DEVICE_FLAG_DEBUG zászlóval, miközben a Direct3D 12 hibakeresési réteget nem engedélyezték, a hibaüzenetek ekkor inkább az OutputDebugStringA használatával vannak kiírva:
[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.
Ahogy a figyelmeztető üzenet is sugallja, célszerű engedélyezni a Direct3D 12 hibakeresési réteget a DirectML hibakeresési réteg használatakor is. Bizonyos típusú ellenőrzés csak akkor lehetséges, ha mindkét hibakeresési réteg engedélyezve van.
A DirectML és a Direct3D 12 hibakeresési rétegeinek telepítése (rendszerösszetevő)
Ha a DirectML-t rendszerösszetevőként használja (lásd a DirectML verzióelőzményeit), a hibakeresési réteg egy külön Grafikus eszközök csomag része, amely igény szerinti szolgáltatásként (FOD) van elosztva (lásd: Igény szerinti szolgáltatások). A grafikus eszközök FOD-ját hozzá kell adni a rendszerhez, hogy a hibakeresési réteget a DirectML rendszerverziójával használhassa. A FOD tartalmazza a Direct3D 12 hibakeresési réteget is, amely szintén hasznos (de nem szükséges) a DirectML-alkalmazások hibakereséséhez.
Az opcionális Grafikus eszközök FOD-csomag hozzáadásához futtassa a következő parancsot egy rendszergazdai PowerShell-parancssorból.
Add-WindowsCapability -Online -Name "Tools.Graphics.DirectX~~~~0.0.1.0"
Másik lehetőségként hozzáadhatja a Grafikus eszközök csomagot a Windows beállításai között. Windows 10 22H2 és Windows 11 rendszeren keresse meg a Beállítások>rendszer>választható funkcióit>: Opcionális funkció hozzáadása, majd grafikus eszközök keresése. A Windows 10 22H2-nél régebbi verziókon keresse meg a Beállítások>Alkalmazások>Alkalmazások és funkciók>Opcionális funkciók>Opcionális funkció hozzáadása helyett.
A DirectML hibakeresési réteg telepítése (önállóan terjeszthető)
Ha a DirectML-et önálló terjeszthető kódtárként használja (lásd : Microsoft.AI.DirectML), a DirectML hibakeresési rétege a csomagban található az alapvető futtatókörnyezeti kódtár mellett. Helyezze el mind a DirectML.Debug.dll, mind a DirectML.dll az alkalmazás futtatható fájlja mellé.
Ha a Visual Studio-t használja Microsoft.AI.DirectML hozzáadásához NuGet-csomagfüggőségként, a projekt a projektkonfigurációs lapon megjeleníti az alapvető futtatókörnyezet és a hibakeresési rétegtárak másolásának vagy kihagyásának lehetőségeit. Alapértelmezés szerint a DirectML NuGet-csomag úgy van konfigurálva, hogy mindkét DLL-t mindig a projekt kimeneti mappájába másolja. Előfordulhat azonban, hogy kihagyja a hibakeresési réteg másolását a kiadási buildekben, ha a hibakeresési réteg nincs használatban.
A Direct3D 12 hibakeresési réteg engedélyezése
A Direct3D 12 hibakeresési rétege (d3d12sdklayers.dll) független a DirectML hibakeresési rétegétől (DirectML.Debug.dll): a DirectML hibakeresési réteg továbbfejlesztett ellenőrzést biztosít a DirectML API-használathoz, a Direct3D 12 hibakeresési réteg pedig a Direct3D 12 API használatát fedi le. A gyakorlatban azonban a directML-alkalmazások fejlesztésekor célszerű mindkét hibakeresési réteget engedélyezni. A Direct3D 12 hibakeresési réteg a grafikus eszközök FOD-jának részeként van telepítve, amely a fentiekben is ismertethető. Tekintse meg az ID3D12Debug::EnableDebugLayer parancsot, amely a Direct3D 12 hibakeresési réteg aktiválására mutat példát.
Fontos
Először engedélyeznie kell a Direct3D 12 hibakeresési réteget. Ezután engedélyezze a DirectML hibakeresési réteget a DMLCreateDevice meghívásával.
A DirectML hibakeresési réteg engedélyezése
A DirectML hibakeresési réteg engedélyezéséhez a DML_CREATE_DEVICE_FLAG_DEBUG megadása szükséges, amikor meghívja a DMLCreateDevice-t.
Ha engedélyezte a DirectML hibakeresési réteget, a DirectML-hibák vagy az érvénytelen API-hívások hibakeresési kimenetként hibakeresési információkat bocsátanak ki. Íme egy példa.
DML_OPERATOR_CONVOLUTION: invalid D3D12_HEAP_TYPE. DirectML requires all bound buffers to be D3D12_HEAP_TYPE_DEFAULT.
Eddig a DML_FEATURE_LEVEL_5_2-ig követelmény a Direct3D 12 hibakeresési réteg engedélyezése annak érdekében, hogy a DirectML hibakeresési réteg engedélyezhető legyen. A DirectML korábbi verzióiban, ha a DML_CREATE_DEVICE_FLAG_DEBUG jelző van megadva a jelölőkben, és a hibakeresési rétegek nincsenek telepítve, akkor a DMLCreateDevice DXGI_ERROR_SDK_COMPONENT_MISSING ad vissza. A DirectML újabb verzióiban a rendszer üzeneteket küld az OutputDebugStringA-nak , ha az ID3D12InfoQueue nem érhető el.
Kódrészlet
Az alábbi kód bemutatja, hogy a Direct3D 12 és a DirectML hibakeresési rétegei csak a hibakeresési buildekhez engedélyezve vannak.
// 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));