Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add new per-device DMA remapping opt-in mechanism information #3901

Merged
merged 5 commits into from
Jan 21, 2025
Merged

Add new per-device DMA remapping opt-in mechanism information #3901

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
4294140
Add new per-device mechanism
Jan 6, 2025
8790a14
Fix link
Jan 7, 2025
48b2403
Update DMA remapping documentation formatting and date
barrygolden Jan 21, 2025
1b61656
Update titles and headings for consistency
barrygolden Jan 21, 2025
3eab1fb
Fix heading in DMA remapping documentation
barrygolden Jan 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 56 additions & 9 deletions windows-driver-docs-pr/pci/enabling-dma-remapping-for-device-drivers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
---
title: Enabling DMA remapping for device drivers
description: Enable and opt-into Direct Memory Access (DMA) remapping to ensure compatibility with Kernel DMA Protection and DMAGuard policies
ms.date: 06/21/2024
title: Enable DMA Remapping for Device Drivers
description: Enable and opt-into Direct Memory Access(DMA) remapping to ensure compatibility with Kernel DMA Protection and DMAGuard policies.
ms.date: 01/21/2025
---

# Enabling DMA remapping for device drivers
# Enable DMA remapping for device drivers

To ensure compatibility with [Kernel DMA Protection](/windows/security/information-protection/kernel-dma-protection-for-thunderbolt) and [DMAGuard Policy](/windows/client-management/mdm/policy-csp-dmaguard#dmaguard-deviceenumerationpolicy), PCIe device drivers can opt into Direct Memory Access (DMA) remapping.

Expand All @@ -22,7 +22,53 @@ Drivers perform DMA using the following interfaces:

- [NDIS interfaces](/windows-hardware/drivers/ddi/_netvista/)

To adjust the DMA remapping policy for your driver, add an INF directive such as the following to the service installation section:
To adjust the DMA remapping policy for your driver, add an INF directive. There are two methods to this: a per-device (strongly recommended and preferred) mechanism and a per-driver (legacy) mechanism.

## Per-device opt-in mechanism

For Windows 24H2 and above, please use this per-device method. Note that this per-device opt-in will completely override the legacy per-driver method, if present (i.e. **DmaRemappingCompatible** key is ignored if **RemappingSupported** is set).

Add an INF directive such as the following to the device enumeration section:

```inf
[MyDriver_Device.NT.HW]
AddReg=DMA_Remapping_OptIn_AddReg

[DMA_Remapping_OptIn_AddReg]
HKR,"DMA Management","RemappingSupported",0x00010001,1
```

Valid values for **DMA Management\RemappingSupported** are:

| Value | Meaning |
|-------|---------|
| 0 | Opt out. This indicates to the system that the device and driver are incompatible with DMA remapping. |
| 1 | Opt in. This indicates to the system that the device and driver is fully compatible with DMA remapping. |
| No registry key | Let the system determine the policy. |

Optionally, you add RemappingFlags to further control the behavior:

```inf
[DMA_Remapping_OptIn_AddReg]
HKR,"DMA Management","RemappingSupported",0x00010001,1
HKR,"DMA Management","RemappingFlags",0x00010001,0x00000001
```

Valid values for **DMA Management\RemappingFlags** are:

| Value | Meaning |
|-------|---------|
| 0 | If **RemappingSupported** is 1, opt in unconditionally. |
| 1 | If **RemappingSupported** is 1, opt in but only when one or more of the following conditions are met: A. If the device is an external device (eg. Thunderbolt); B. If DMA verification is enabled in Driver Verifier. |
| No registry key | Same as 0 value. |

These registry keys will appear under the enumeration tree: ``HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Enum\PCI\<device instance path>\Device Parameters\DMA Management``

### Per-driver opt-in mechanism

Only use this per-driver method for Windows versions up to Windows 11 23H2. It is strongly recommended to use the [per-device method as outlined above](#per-device-opt-in-mechanism).

Add an INF directive such as the following to the service installation section:

```inf
[MyServiceInstall_AddReg]
Expand All @@ -32,23 +78,24 @@ To adjust the DMA remapping policy for your driver, add an INF directive such as
Valid values for **DmaRemappingCompatible** are:

| Value | Meaning |
| ----- | ------- |
|-------|---------|
| 0 | Opt out. This indicates to the system that your driver is incompatible with DMA remapping. |
| 1 | Opt in. This indicates to the system that your driver is fully compatible with DMA remapping. |
| 2 | Opt in, but only when one or more of the following conditions are met: A. If the device is an external device (eg. Thunderbolt); B. If DMA verification is enabled in Driver Verifier. |
| 3 | Opt in
| No registry key | Let the system determine the policy. |

When testing your driver, enable Driver Verifier. For testing purposes under Driver Verifier, the value of the INF directive for opting in external devices is promoted to 1.

Use the latest Windows 10 build with VT-d/AMD-Vi enabled to test driver functionality on Intel x64 and AMD64 systems.
The registry key will appear under the service installation tree: ``HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\<driver name>\Parameters``.

> [!WARNING]
> DMA remapping is not supported for graphics device drivers.
>
> Support for version 3 is only available on Windows 11. On Windows 10, if you specify 3 in the INF, the system falls back to a value of 2.

## Validating that DMA remapping is enabled for a specific device driver instance

Use the latest Windows build with VT-d/AMD-Vi enabled to test driver functionality on Intel x64 and AMD64 systems.

To check if a specific driver has opted into DMA remapping, look in Device Manager, in the device's **Details** tab, for the values corresponding to the DMA remapping policy property. A driver can query the [**DEVPKEY_Device_DmaRemappingPolicy**](../install/devpkey-device-dmaremappingpolicy.md) property to determine the DMA remapping capability of the device. See potential return values on that page, and note that these return values are not the same as the values for **DmaRemappingCompatible** listed in the previous section.

![Device Manager Details Tab.](images/device-details-tab-1903.png)
Expand Down