FN_VMB_CHANNEL_PACKET_GET_EXTERNAL_DATA callback function (vmbuskernelmodeclientlibapi.h)

Article
08/23/2021

[Some information relates to pre-released product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.]

The VmbChannelPacketGetExternalData function gets any external Memory Descriptor Lists (MDLs) associated with a packet during packet processing.

Syntax

FN_VMB_CHANNEL_PACKET_GET_EXTERNAL_DATA FnVmbChannelPacketGetExternalData;

NTSTATUS FnVmbChannelPacketGetExternalData(
  VMBPACKETCOMPLETION PacketCompletionContext,
  UINT32 Flags,
  PMDL *Mdl
)
{...}

Parameters

PacketCompletionContext

A handle that identifies the incoming packet and is used to refer to the packet once processing is finished.

Flags

Flags that control how the MDL is mapped. The possible flag values are:

Value	Meaning
VMBUS_CHANNEL_PACKET_EXTERNAL_DATA_FLAG_READ_ONLY	Map MDL as read-only.

Mdl

A pointer to the mapped MDL.

Return value

VmbChannelPacketGetExternalData returns a status code. If this function returns STATUS_PENDING, the caller must return from the packet processing callback, which will be called again, possibly at a different IRQL, when the external data is ready. At this point, a call to this function will succeed and return the external data.

Remarks

Creating an MDL which represents the memory described by this transaction causes these regions of the virtual machine to be pinned in memory for the remainder of the transaction lifetime. This is what may cause the function to return STATUS_PENDING, because the regions of the virtual machine may need to be paged in.

The MDL returned by this function describes memory that is already locked in place. Therefore, there is no need to call the MmProbeAndLockPages function. The MDL will, however, have neither a user-mode virtual address nor a kernel-mode virtual address. If the driver that calls this function requires a virtual address to manipulate the memory within the virtual machine, that driver must call MmMapLockedPagesSpecifyCache, or MmGetSystemAddressForMdlSafe, and the corresponding unlock function later, like MmUnmapLockedPages. An alternative to using a virtual address would be to just pass the MDL on down to a driver which uses it for direct memory access.

The driver calling this function is not required to release the MDL. It becomes invalid upon calling the VmbChannelPacketComplete function. The Kernel Mode Client Library (KMCL) later releases it.

Important

This function is called through the VMBus Kernel Mode Client Library (KMCL) interface, provided by the Vmbkmcl.sys bus driver. This is a client function accessed from the KMCL_CLIENT_INTERFACE_V1 structure.

For more information, see the Remarks section of the KMCL_CLIENT_INTERFACE_V1.

Requirements

Requirement	Value
Minimum supported client	Windows 10, version 1803
Header	vmbuskernelmodeclientlibapi.h