Event Log Buffer States

When a buffer is created, it is part of the event log buffer group that is associated with an event log type. The hypervisor initializes the buffer in an internal standby state. While in this standby state, the buffer is neither accessible from the guest nor usable by the hypervisor. The partition calls the HvMapEventLogBuffer hypercall function to reveal the location of the buffer's constituent pages and to make the buffer available to the hypervisor for recording events. The partition calls the HvUnmapEventLogBuffer hypercall function to unmap the buffer and to return the buffer to the internal standby state.

While the event log type is enabled (through a call to the HvSetEventLogGroupSources hypercall function), all related buffers of the group have a guest-accessible state that is described by one of the following HV_EVENTLOG_BUFFER_STATE enumeration values:

HvEventLogBufferStateFree: The buffer is currently available to be allocated by the hypervisor as an "in use" buffer. With the exception of the BufferState member of the HV_EVENTLOG_BUFFER_HEADER structure that describes the buffer header, the guest should not read the buffer's contents. A buffer enters the free state when it is either mapped or released by the guest. It remains in this state until it is either unmapped by the guest (therefore, taken out of service) or allocated by the hypervisor as an "in use" buffer. Note that the hypervisor can change the state of this buffer at any time.
HvEventLogBufferStateInUse: The buffer is currently active and will accept event messages. The hypervisor can write to buffers of this type, and the guest can access buffers of this type in a limited fashion (for more information about these access limitations, see Buffer Access Restrictions). Buffers leave the "in use" state when they are full or when the guest calls the HvFlushEventLogBuffer hypercall function to request that the hypervisor flush the buffers. Note that the buffer can become full at any time and the hypervisor could therefore change the state at any time.
HvEventLogBufferStateComplete: The buffer is no longer active and contains valid data. The hypervisor is no longer writing to buffers of this type, and the guest can read buffers of this type. Buffers in the "complete" state are on a list waiting for the hypervisor to notify the guest of their completion. For more information about this notification, see Event Log Buffers Ready Message. Buffers leave the HvEventLogBufferStateComplete state when either the guest flushes them or the threshold value is reached. The hypervisor changes the state of all "complete" buffers on the list to HvEventLogBufferStateReady and sends the list to the guest with a notification message. While the hypervisor can transition buffers on the completed list to the ready state at any time, the content of the buffer (aside from the state) will not change.
HvEventLogBufferStateReady: The buffer is complete (as with the HvEventLogBufferStateComplete state), and the hypervisor has sent the buffer to the guest with a notification message. Buffers in the "ready" state are under the exclusive control of the guest. Buffers leave the HvEventLogBufferStateReady state when the guest either unmaps them or releases them (through calls to the HvReleaseEventLogBuffer hypercall function) back to the hypervisor for reuse.

Note that the internal "standby" state is absent in the preceding description values because a buffer in the standby state is not accessible from the guest. While in the standby state, the buffer is not mapped, which makes the state information inaccessible. When the buffer is in the standby state, it can either be mapped by a guest (which transitions the buffer to the HvEventLogBufferStateFree state) or deleted by the guest.

The following figure shows how buffers transition between states. Items that are labeled "guest" are guest actions (that is, a hypercall), and items that are labeled "hypervisor" are actions taken by the hypervisor as event logging proceeds.

Diagram illustrating how buffers transition between states

The following table summarizes the event logging operations that can be performed based on the state of the buffer.

	Standby	Free	In Use	Complete	Ready
Initialize Buffer Group	N/A	N/A	N/A	N/A	N/A
Create Buffer	N/A	N/A	N/A	N/A	N/A
MapBuffer	Places the buffer into the free state	Error	Error	Error	Error
Request Flush	N/A	N/A	Places the buffer into the complete state	Places buffers into the ready state and sends a message	N/A
Release Buffer	Error	Error	Error	Error	Places the buffer into the free state
Unmap Buffer	Error	Places the buffer into the standby state	Error	Error	Places the buffer into the standby state
Delete Buffer	Deallocates the buffer	Error	Error	Error	Error
Finalize Buffer Group	N/A	N/A	N/A	N/A	N/A

Send comments about this topic to Microsoft

Build date: 11/16/2013