DXGKDDI_RESTOREIMMUTABLEMIGRATIONDATA callback function (d3dkmddi.h)
The receiving-side OS calls DxgkDdiRestoreImmutableMigrationData to restore immutable data that was saved by the sending-side driver in a previous call to DxgkDdiSaveImmutableMigrationData.
Syntax
DXGKDDI_RESTOREIMMUTABLEMIGRATIONDATA DxgkddiRestoreimmutablemigrationdata;
NTSTATUS DxgkddiRestoreimmutablemigrationdata(
IN_CONST_HANDLE hAdapter,
IN_CONST_PDXGKARG_GPUP_RESTORE_IMMUTABLE_MIGRATION_DATA pArgs
)
{...}
Parameters
hAdapter
[in] A handle to a context block associated with a display adapter. The display miniport driver previously provided this handle to Dxgkrnl in the MiniportDeviceContext output parameter of the DXGKDDI_ADD_DEVICE function.
pArgs
[in] Pointer to a DXGKARG_GPUP_RESTORE_IMMUTABLE_MIGRATION_DATA structure that contains information needed to restore the immutable data.
Return value
DxgkDdiRestoreImmutableMigrationData returns STATUS_SUCCESS if the call is successful. Otherwise, it returns an appropriate NTSTATUS code such as the STATUS_OBJECT_TYPE_MISMATCH error code (see Remarks).
Remarks
Unlike the save/send side that is called twice, DxgkDdiRestoreImmutableMigrationData is called only once because it has all the data needed to present a full data buffer to the receiving side KMD. The driver should take the data and apply it to the VF being constructed, as well as any tracking for it, and it should validate the data invariants necessary for a successful restore.
The buffer is the content that was filled on the source side in DxgkDdiSaveImmutableMigrationData, so KMD should be tracking that data in a common type. There should also be a versioning scheme implemented in the content data if the data might potentially need to change with new drivers, and this scheme should be a part of the version checking done on the target.
If the data indicates that the target system isn't configured properly to have the VF migrated from the source, KMD should do the following:
- Report this issue through the DxgkCbLogEtwEvent with the GUID_DxgkAzureTriageEvent identifier and specific details on what failed validation so that the issue can be triaged and corrected.
- Return from this DDI call with the STATUS_OBJECT_TYPE_MISMATCH error.
DxgkDdiRestoreImmutableMigrationData should only ever be called for VFs that are currently paused.
For more information, see Live migration on GPU-P devices.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 11, version 24H2 (WDDM 3.2) |
| Header | d3dkmddi.h |
| IRQL | PASSIVE_LEVEL |