【Backup】Xen Interface Xen Info Pages

The Shared info page is used to share various CPU-related state between the guest OS and the hypervisor. This information includes VCPU status, time information and event channel (virtual interrupt) state.
The Start info page is used to pass build-time information to the guest when it boots and when it is resumed from a suspended state.

1. Shared info page
The shared_info_t is accessed at run time by both Xen and the guest OS.
It is used to pass information relating to the virtual CPU and virtual machine state between the OS and the hypervisor.
The structure is declared in xen/include/public/xen.h:
typedef struct shared_info {
vcpu_info_t vcpu_info[XEN_LEGACY_MAX_VCPUS];
/*An array of vcpu info t structures, each of which holds either runtime information about a virtual CPU, or is “empty” if the corresponding VCPU does not exist.*/
/*
* A domain can create "event channels" on which it can send and receive
* asynchronous event notifications. There are three classes of event that
* are delivered by this mechanism:
* 1. Bi-directional inter- and intra-domain connections. Domains must arrange out-of-band to set up a        
*     connection (usually by allocating an unbound ’listener’ port and advertising that via a storage service such *     as xenstore).
*
* 2. Physical interrupts. A domain with suitable hardware-access privileges can bind an event-channel port to a *     physical interrupt source.
*
* 3. Virtual interrupts (’events’). A domain can bind an event-channel port to a virtual interrupt source, such as *     the virtual-timer device or the emergency console.
*
*
* Event channels are addressed by a "port index". Each channel is
* associated with two bits of information:
* 1. PENDING -- notifies the domain that there is a pending notification to be processed. This bit is cleared by *     the guest.
*
* 2. MASK -- if this bit is clear then a 0->1 transition of PENDING will cause an asynchronous upcall to be
*     scheduled. This bit is only updated by the guest. It is read-only within Xen. If a channel becomes pending *     while the channel is masked then the ’edge’ is lost (i.e., when the channel is unmasked, the guest must *     manually handle pending notifications as no upcall will be scheduled by Xen).
*
*
* To expedite scanning of pending notifications, any 0->1 pending
* transition on an unmasked channel causes a corresponding bit in a
* per-vcpu selector word to be set. Each bit in the selector covers a
* ’C long’ in the PENDING bitfield array.
*/
unsigned long evtchn_pending[sizeof(unsigned long) * 8];
/*Guest-global array, with one bit per event channel. Bits are set if an event is currently pending on that channel.*/
unsigned long evtchn_mask[sizeof(unsigned long) * 8];
/*Guest-global array for masking notifications on event channels.*/
/*
* Wallclock time: updated only by control software. Guests should base
* their gettimeofday() syscall on this wallclock-base value.
*/
uint32_t wc_version;
/* Version counter: see vcpu_time_info_t. */
uint32_t wc_sec;   /* Secs 00:00:00 UTC, Jan 1, 1970. */
uint32_t wc_nsec;   /* Nsecs 00:00:00 UTC, Jan 1, 1970. */
arch_shared_info_t arch;   /*Host architecture-dependent portion of the shared info structure*/
} shared_info_t;

1.1 vcpu_info_t
typedef struct vcpu_info {
/*
* 'evtchn_upcall_pending' is written non-zero by Xen to indicate
* a pending notification for a particular VCPU. It is then cleared
* by the guest OS /before/ checking for pending work, thus avoiding
* a set-and-check race. Note that the mask is only accessed by Xen
* on the CPU that is currently hosting the VCPU. This means that the
* pending and mask flags can be updated by the guest without special
* synchronisation (i.e., no need for the x86 LOCK prefix).
* This may seem suboptimal because if the pending flag is set by
* a different CPU then an IPI may be scheduled even when the mask
* is set. However, note:
* 1. The task of ’interrupt holdoff’ is covered by the per-event-channel mask bits. A ’noisy’ event that is
*     continually being triggered can be masked at source at this very precise granularity.
*
* 2. The main purpose of the per-VCPU mask is therefore to restrict reentrant execution: whether for
*     concurrency control, or to prevent unbounded stack usage. Whatever the purpose, we expect that the       
*     mask will be asserted only for short periods at a time, and so the likelihood of a ’spurious’ IPI is suitably *     small.
*
* The mask is read before making an event upcall to the guest: a
* non-zero mask therefore guarantees that the VCPU will not receive
* an upcall activation. The mask is cleared when the VCPU requests
* to block: this avoids wakeup-waiting races.
*/
uint8_t evtchn_upcall_pending;
/*This is set non-zero by Xen to indicate that there are pending events to be received.*/
uint8_t evtchn_upcall_mask;
/*This is set non-zero to disable all interrupts for this CPU for short periods of time. If individual event channels need to be masked, the evtchn mask in the shared info t is used instead.*/
unsigned long evtchn_pending_sel;
/*When an event is delivered to this VCPU, a bit is set in this selector to indicate which word of the evtchn pending array in the shared_info_t contains the event in question.*/
arch_vcpu_info_t arch;
/*Architecture-specific VCPU info. On x86 this contains the virtualized CR2 register (page fault linear address) for this VCPU.*/
vcpu_time_info_t time;
/*Time values for this VCPU.*/
} vcpu_info_t; /* 64 bytes (x86) */

1.2 vcpu time info
typedef struct vcpu_time_info {
/*
* Updates to the following values are preceded and followed by an
* increment of ’version’. The guest can therefore detect updates by
* looking for changes to ’version’. If the least-significant bit of
* the version number is set then an update is in progress and the guest
* must wait to read a consistent set of values.
* The correct way to interact with the version number is similar to
* Linux’s seqlock: see the implementations of read_seqbegin/read_seqretry.
*/
uint32_t version; /*Used to ensure the guest gets consistent time updates.*/
uint32_t pad0;
uint64_t tsc_timestamp;
/*Cycle counter timestamp of last time value; could be used to expolate in between updates, for instance.*/
/* TSC at last update of time vals. */
uint64_t system_time; /*Time since boot (nanoseconds).*/
/* Time, in nanosecs, since boot.*/
/*
* Current system time:
system_time + ((tsc - tsc_timestamp) << tsc_shift) * tsc_to_system_mul
*
* CPU frequency (Hz):
((10ˆ9 << 32) / tsc_to_system_mul) >> tsc_shift
*
*/
uint32_t tsc_to_system_mul; /*Cycle counter to nanoseconds multiplier (used in extrapolating current time).*/
int8_t tsc_shift; /*Cycle counter to nanoseconds shift (used in extrapolating current time).*/
int8_t pad1[3];
} vcpu_time_info_t; /* 32 bytes */

1.3 arch_shared_info_t
On x86, the arch shared info t is defined as follows (from xen/public/arch-x86 32.h):
typedef struct arch_shared_info {
unsigned long max_pfn; /*The maximum PFN listed in the physical-to-machine mapping table (P2M table).*/
/* max pfn that appears in table */
/* Frame containing list of mfns containing list of mfns containing p2m. */
unsigned long pfn_to_mfn_frame_list_list;
/*Machine address of the frame that contains the machine addresses of the P2M table frames.*/
} arch_shared_info_t;

2. Start info page
The start info structure is declared as the following (in xen/include/public/xen.h):
/*The fields are in two groups: the first group are always filled in when a domain is booted or resumed, the second set are only used at boot time.*/
#define MAX_GUEST_CMDLINE 1024
typedef struct start_info {
/* THE FOLLOWING ARE FILLED IN BOTH ON INITIAL BOOT AND ON RESUME.*/
char magic[32]; /*A text string identifying the Xen version to the guest.*/
/* "Xen-.". */
unsigned long nr_pages; /*The number of real machine pages available to the guest.*/
/* Total pages allocated to this domain.*/
unsigned long shared_info; /* MACHINE address of shared info struct. Machine address of the shared info structure, allowing the guest to map it during initialisation.*/
uint32_t flags; /*Flags for describing optional extra settings to the guest.*/
/* SIF_xxx flags.*/
unsigned long store_mfn; /*Machine address of the Xenstore communications page.*/
/* MACHINE page number of shared page.*/
uint32_t store_evtchn; /*Event channel to communicate with the store.*/
/* Event channel for store communication.*/
unsigned long console_mfn; /* MACHINE address of console page. Machine address of the console data page.*/
uint32_t console_evtchn; /*Event channel to notify the console backend.*/
/* Event channel for console messages.*/
/* THE FOLLOWING ARE ONLY FILLED IN ON INITIAL BOOT (NOT RESUME).The boot-only group may only be safely referred to during system boot:*/
unsigned long pt_base; /*Virtual address of the page directory created for us by the domain builder.*/
/* VIRTUAL address of page directory.*/
unsigned long nr_pt_frames; /* Number of bootstrap p.t. frames. Number of frames used by the builders’ bootstrap pagetables.*/
unsigned long mfn_list; /*Virtual address of the list of machine frames this domain owns.*/
/* VIRTUAL address of page-frame list.*/
unsigned long mod_start; /*Virtual address of any pre-loaded modules (e.g. ramdisk)*/
/* VIRTUAL address of pre-loaded module.*/
unsigned long mod_len; /*Size of pre-loaded module (if any).*/
/* Size (bytes) of pre-loaded module.*/
int8_t cmd_line[MAX_GUEST_CMDLINE];  /*Kernel command line passed by the domain builder.*/
} start_info_t;