Debug Sessions

Each guest operating system that uses the debugging facility manages a single session between the guest itself and the external debugger. A partition that needs to use a debug session must possess the Debugging privilege. The Debugging privilege can be set by setting the Debugging member of the HV_PARTITION_PRIVILEGE_MASK union in a call to the HvSetPartitionProperty hypercall function. The hypervisor will also test for the Debugging privilege at partition initialization time (in the call to HvInitializePartition). If the hypervisor grants the Debugging privilege, the hypervisor reserves resources for the incoming and outgoing debug data streams. The hypervisor allocates the resources from the partition's pool and provides buffer space for incoming and outgoing session data. At a minimum, the outgoing buffer will be large enough to accept the maximum amount of session data that can be posted by a single hypercall. The Debugging privilege also lets the partition have access to the hypervisor's debugging hypercall functions.

The debug session is assigned a unique debugging channel identifier that is used to identify the session over the physical connection. The debugging channel identifier is a partition property value and is assigned through a call to the HvSetPartitionProperty hypercall function. In this HvSetPartitionProperty call, the HvPartitionPropertyDebugChannelId value is set in the HV_PARTITION_PROPERTY_CODE enumeration that is passed to the PropertyCode parameter. The debugging channel identifier that is passed to the PropertyValue parameter is set to either zero or a unique nonzero value. The value is 16-bits wide. If the value is set to zero, which indicates that a channel identifier is not assigned, a call to any of the hypervisor's debugging hypercall functions will return an error.

When the partition is saved through a call to the HvSavePartitionState hypercall function, any debugging-related data that has been posted or not yet received is not part of the partition's save context. When the partition is subsequently restored through a call to the HvRestorePartitionState hypercall function, the Debugging privilege must be granted at partition creation to ensure that the necessary session infrastructure is manifested by partition initialization. The session will appear in a reset state, and the guest should be able to sense the loss of synchronization and be able to recover accordingly.

When the partition is finalized through a call to the HvFinalizePartition hypercall function, the process implicitly resets the debugging session and releases any related resources that were allocated during partition initialization. Any debugging data that is present in the incoming and outgoing buffers will be discarded.

Send comments about this topic to Microsoft

Build date: 11/16/2013