## Host boot
As Xen boots, it will enumerate the features it can see. This is stored as
-the _raw\_featureset_.
+the *raw_featureset*.
Errata checks and command line arguments are then taken into account to reduce
-the _raw\_featureset_ into the _host\_featureset_, which is the set of
+the *raw_featureset* into the *host_featureset*, which is the set of
features Xen uses. On hardware with masking/override MSRs, the default MSR
-values are picked from the _host\_featureset_.
+values are picked from the *host_featureset*.
-The _host\_featureset_ is then used to calculate the _pv\_featureset_ and
-_hvm\_featureset_, which are the maximum featuresets Xen is willing to offer
+The *host_featureset* is then used to calculate the *pv_featureset* and
+*hvm_featureset*, which are the maximum featuresets Xen is willing to offer
to PV and HVM guests respectively.
In addition, Xen will calculate how much control it has over non-cooperative
-PV `CPUID` instructions, storing this information as _levelling\_caps_.
+PV `CPUID` instructions, storing this information as *levelling_caps*.
## Domain creation
preventing a guest from using 1GB superpages if the hardware supports it.
Some information simply cannot be hidden from guests. There is no way to
-control certain behaviour such as the hardware MXCSR\_MASK or x87 FPU exception
+control certain behaviour such as the hardware MXCSR_MASK or x87 FPU exception
behaviour.
MSRs are another source of features for guests. There is no general provision
for controlling the available MSRs. E.g. 64bit versions of Windows notice
-changes in IA32\_MISC\_ENABLE, and suffer a BSOD 0x109 (Critical Structure
+changes in IA32_MISC_ENABLE, and suffer a BSOD 0x109 (Critical Structure
Corruption)
## libxl
-With migration v2 support, LIBXL\_HAVE\_SRM\_V2 and LIBXL\_HAVE\_SRM\_V1
+With migration v2 support, LIBXL_HAVE_SRM_V2 and LIBXL_HAVE_SRM_V1
are introduced to indicate support. `domain_restore_params` gains a new
parameter, `stream_version`, which is used to distinguish between legacy and
v2 migration streams, and hence whether legacy conversion is required.
Global scheduling parameters, such as context switching rate
limiting, is only available from Xen 4.8 onward. In libxl, the
-`LIBXL\_HAVE\_SCHED\_CREDIT2\_PARAMS` symbol is introduced to
+LIBXL_HAVE_SCHED_CREDIT2_PARAMS symbol is introduced to
indicate their availability.
# Testing
* vCPUs' reservations (similar to caps, but providing a vCPU with guarantees
about some pCPU time it will always be able to execute for);
* benchmarking for assessing the best combination of values for the various
- parameters (`sched\_credit2\_migrate\_resist`, `credit2\_balance\_over`,
- `credit2\_balance\_under`)
+ parameters (`sched_credit2_migrate_resist`, `credit2_balance_over`,
+ `credit2_balance_under`)
# Known issues
is all contained in `xen/common/sched_rtds.c`.
In libxl, the availability of the RTDS scheduler is advertised by
-the presence of the LIBXL\_HAVE\_SCHED\_RTDS symbol. The ability of
+the presence of the LIBXL_HAVE_SCHED_RTDS symbol. The ability of
specifying different scheduling parameters for each vcpu has been
introduced later, and is available if the following symbols are defined:
- * `LIBXL\_HAVE\_VCPU\_SCHED\_PARAMS`,
- * `LIBXL\_HAVE\_SCHED\_RTDS\_VCPU\_PARAMS`,
- * `LIBXL\_HAVE\_SCHED\_RTDS\_VCPU\_EXTRA`.
+ * LIBXL_HAVE_VCPU_SCHED_PARAMS,
+ * LIBXL_HAVE_SCHED_RTDS_VCPU_PARAMS,
+ * LIBXL_HAVE_SCHED_RTDS_VCPU_EXTRA.
# Limitations
pfn An array of count PFNs and their types.
- Bit 63-60: XEN\_DOMCTL\_PFINFO\_* type (from
+ Bit 63-60: XEN_DOMCTL_PFINFO_* type (from
`public/domctl.h` but shifted by 32 bits)
Bit 59-52: Reserved.
Bit 51-0: PFN.
-page\_data page\_size octets of uncompressed page contents for each
+page_data page_size octets of uncompressed page contents for each
page set as present in the pfn array.
--------------------------------------------------------------------
XTAB 0xF Invalid page.
--------------------------------------------------------------------
-Table: XEN\_DOMCTL\_PFINFO\_* Page Types.
+Table: XEN_DOMCTL_PFINFO_* Page Types.
PFNs with type `BROKEN`, `XALLOC`, or `XTAB` do not have any
corresponding `page_data`.
---------------------------------------------------------------------
Record type Accessor hypercalls
----------------------- ----------------------------------------
-X86\_PV\_VCPU\_BASIC XEN\_DOMCTL\_{get,set}vcpucontext
+X86_PV_VCPU_BASIC XEN_DOMCTL_{get,set}vcpucontext
-X86\_PV\_VCPU\_EXTENDED XEN\_DOMCTL\_{get,set}\_ext\_vcpucontext
+X86_PV_VCPU_EXTENDED XEN_DOMCTL_{get,set}\_ext_vcpucontext
-X86\_PV\_VCPU\_XSAVE XEN\_DOMCTL\_{get,set}vcpuextstate
+X86_PV_VCPU_XSAVE XEN_DOMCTL_{get,set}vcpuextstate
-X86\_PV\_VCPU\_MSRS XEN\_DOMCTL\_{get,set}\_vcpu\_msrs
+X86_PV_VCPU_MSRS XEN_DOMCTL_{get,set}\_vcpu_msrs
---------------------------------------------------------------------
\clearpage
--------
Domain TSC information, as accessed by the
-XEN\_DOMCTL\_{get,set}tscinfo hypercall sub-ops.
+XEN_DOMCTL_{get,set}tscinfo hypercall sub-ops.
0 1 2 3 4 5 6 7 octet
+------------------------+------------------------+
--------------------------------------------------------------------
Field Description
----------- ---------------------------------------------------
-mode TSC mode, TSC\_MODE\_* constant.
+mode TSC mode, TSC_MODE_* constant.
khz TSC frequency, in kHz.
-----------
HVM Domain context, as accessed by the
-XEN\_DOMCTL\_{get,set}hvmcontext hypercall sub-ops.
+XEN_DOMCTL_{get,set}hvmcontext hypercall sub-ops.
0 1 2 3 4 5 6 7 octet
+-------------------------------------------------+
----------
HVM Domain parameters, as accessed by the
-HVMOP\_{get,set}\_param hypercall sub-ops.
+HVMOP_{get,set}\_param hypercall sub-ops.
0 1 2 3 4 5 6 7 octet
+------------------------+------------------------+
1. Image header
2. Domain header
-3. X86\_PV\_INFO record
-4. X86\_PV\_P2M\_FRAMES record
-5. Many PAGE\_DATA records
-6. TSC\_INFO
-7. SHARED\_INFO record
+3. X86_PV_INFO record
+4. X86_PV_P2M_FRAMES record
+5. Many PAGE_DATA records
+6. TSC_INFO
+7. SHARED_INFO record
8. VCPU context records for each online VCPU
- a. X86\_PV\_VCPU\_BASIC record
- b. X86\_PV\_VCPU\_EXTENDED record
- c. X86\_PV\_VCPU\_XSAVE record
- d. X86\_PV\_VCPU\_MSRS record
+ a. X86_PV_VCPU_BASIC record
+ b. X86_PV_VCPU_EXTENDED record
+ c. X86_PV_VCPU_XSAVE record
+ d. X86_PV_VCPU_MSRS record
9. END record
There are some strict ordering requirements. The following records must
be present in the following order as each of them depends on information
present in the preceding ones.
-1. X86\_PV\_INFO record
-2. X86\_PV\_P2M\_FRAMES record
-3. PAGE\_DATA records
+1. X86_PV_INFO record
+2. X86_PV_P2M_FRAMES record
+3. PAGE_DATA records
4. VCPU records
x86 HVM Guest
1. Image header
2. Domain header
-3. Many PAGE\_DATA records
-4. TSC\_INFO
-5. HVM\_PARAMS
-6. HVM\_CONTEXT
+3. Many PAGE_DATA records
+4. TSC_INFO
+5. HVM_PARAMS
+6. HVM_CONTEXT
-HVM\_PARAMS must precede HVM\_CONTEXT, as certain parameters can affect
+HVM_PARAMS must precede HVM_CONTEXT, as certain parameters can affect
the validity of architectural state in the context.
1. For compatibility with older code, the receving side of a stream should
tolerate and ignore variable sized records with zero content. Xen releases
- between 4.6 and 4.8 could end up generating valid HVM\_PARAMS or
- X86\_PV\_VCPU\_{EXTENDED,XSAVE,MSRS} records with zero-length content.
+ between 4.6 and 4.8 could end up generating valid HVM_PARAMS or
+ X86_PV_VCPU_{EXTENDED,XSAVE,MSRS} records with zero-length content.
The end record contains no fields; its body_length is 0.
-LIBXC\_CONTEXT
---------------
+LIBXC_CONTEXT
+-------------
A libxc context record is a marker, indicating that the stream should be
handed to `xc_domain_restore()`. `libxc` shall be responsible for reading its
might write into the stream, especially for live migration where the quantity
of data is partially proportional to the elapsed time.
-EMULATOR\_XENSTORE\_DATA
-------------------------
+EMULATOR_XENSTORE_DATA
+----------------------
A set of xenstore key/value pairs for a specific emulator associated with the
domain.
although this path is free to change moving forward, thus should not be
assumed.
-EMULATOR\_CONTEXT
+EMULATOR_CONTEXT
----------------
A context blob for a specific emulator associated with the domain.
The *emulator_ctx* is a binary blob interpreted by the emulator identified by
*emulator_id*. Its format is unspecified.
-CHECKPOINT\_END
----------------
+CHECKPOINT_END
+--------------
A checkpoint end record marks the end of a checkpoint in the image.
The end record contains no fields; its body_length is 0.
-CHECKPOINT\_STATE
---------------
+CHECKPOINT_STATE
+----------------
A checkpoint state record contains the control information for checkpoint. It
is only used by COLO, more detail please reference README.colo.
1. Suspend primary vm
a. Suspend primary vm
- b. Read _CHECKPOINT\_SVM\_SUSPENDED_ sent by secondary
+ b. Read *CHECKPOINT_SVM_SUSPENDED* sent by secondary
2. Checkpoint
3. Resume primary vm
- a. Read _CHECKPOINT\_SVM\_READY_ from secondary
+ a. Read *CHECKPOINT_SVM_READY* from secondary
b. Resume primary vm
- c. Read _CHECKPOINT\_SVM\_RESUMED_ from secondary
+ c. Read *CHECKPOINT_SVM_RESUMED* from secondary
4. Wait a new checkpoint
- a. Send _CHECKPOINT\_NEW_ to secondary
+ a. Send *CHECKPOINT_NEW* to secondary
While Secondary is running in below loop:
1. Resume secondary vm
- a. Send _CHECKPOINT\_SVM\_READY_ to primary
+ a. Send *CHECKPOINT_SVM_READY* to primary
b. Resume secondary vm
- c. Send _CHECKPOINT\_SVM\_RESUMED_ to primary
+ c. Send *CHECKPOINT_SVM_RESUMED* to primary
2. Wait a new checkpoint
- a. Read _CHECKPOINT\_NEW_ from primary
+ a. Read *CHECKPOINT_NEW* from primary
3. Suspend secondary vm
a. Suspend secondary vm
- b. Send _CHECKPOINT\_SVM\_SUSPENDED_ to primary
+ b. Send *CHECKPOINT_SVM_SUSPENDED* to primary
4. Checkpoint
Future Extensions