Buffer Access Restrictions

After the guest calls the HvMapEventLogBuffer hypercall function to map a buffer, the buffer remains read-only accessible to the guest until the guest subsequently calls the HvUnmapEventLogBuffer hypercall function to unmap the buffer. During this read-only-accessible period, the buffer can be in one of several states as described in Event Log Buffer States. The guest can access buffers that are in the free, in-use, complete, and ready states (buffers in the standby state are not mapped and are therefore not accessible).

Buffers in the free state can be allocated by the hypervisor at any time. A free buffer has no meaningful content and therefore is of no interest to the guest. A guest might need to deallocate a free buffer. Deallocation is a two-step process that involves unmapping (call to HvUnmapEventLogBuffer) and then deleting (call to HvDeleteEventLogBuffer) the buffer. Unmapping the buffer transitions the buffer from the free to the standby state, where the buffer can no longer be allocated for use by the hypervisor. Note that the hypervisor can allocate a free buffer between the time the guest examines the state and attempts to unmap the buffer.

In-use buffers are allocated by the hypervisor and are filled with individual event entries. Entries are appended to the buffer until the buffer is full, at which time the buffer transitions from the in-use to the complete state. In-use buffers can also be flushed by the guest, which places them into the complete state. While in the in-use state, the buffer's header is subject to modification at any time. Modification however, will only cause new entries to be appended to the buffer, and header updates are performed after the event data is copied. The guest can examine in-use buffers at any time but should be aware that the hypervisor could append more event data at any time.

The hypervisor places complete buffers onto a list to wait for guest notification. Buffers in this state no longer accept new entries and are therefore ready for examination. Note that the hypervisor could transition these buffers to the ready state at any time. The NextBufferIndex member of the HV_EVENTLOG_BUFFER_HEADER structure for the buffer header is subject to change at any time and should not be examined. The buffer's content however, will not change.

The hypervisor has either reported ready buffers to the guest or notification is in progress (that is, the message might be pending delivery). These ready buffers are in a guest-controlled state and the hypervisor cannot perform any operations on them until they are released. All fields of the buffers in the ready state that have been delivered to the guest are stable and can no longer be changed by the hypervisor.

Because buffers in the in-use and complete state can transition state at any time, guests should limit their access to event log buffers that are in the ready state. The hypervisor reports buffers in the ready state to the guests by using the "complete buffers notification" message (for more information about this notification, see Event Log Buffers Ready Message). Such buffers remain in the ready state under the exclusive control of the guest until the guest takes action to cause a change in state.

Send comments about this topic to Microsoft

Build date: 11/16/2013