Signed-off-by: Dario Faggioli <>
Cc: George Dunlap <>
Cc: Wei Liu <>
Cc: Lars Kurth <>
Cc: Andrew Cooper <>
Cc: Ian Jackson <>
Cc: Jan Beulich <>
Cc: Konrad Rzeszutek Wilk <>
Cc: Stefano Stabellini <>
 docs/features/credit.pandoc |   99 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 99 insertions(+)
 create mode 100644 docs/features/credit.pandoc

diff --git a/docs/features/credit.pandoc b/docs/features/credit.pandoc
new file mode 100644
index 0000000..fed0da2
--- /dev/null
+++ b/docs/features/credit.pandoc
@@ -0,0 +1,99 @@
+% Credit
+% Revision 1
+# Basics
+---------------- ----------------------------------------------------
+         Status: e.g. **Supported**
+Architecture(s): e.g. x86, arm
+      Component: e.g. Hypervisor
+---------------- ----------------------------------------------------
+# Overview
+Credit (also known as Credit1) is the default virtual CPU (vCPU) scheduler
+of the Xen hypervisor. The job of an hypervisor's scheduler is to decide,
+among all the various vCPUs of the various virtual machines, which ones
+should execute on the host's physical CPUs (pCPUs), at any given point in
+# User details
+Xen supports multiple schedulers. As said, Credit is the default, so it
+is used automatically, unless the `sched=$SCHED` (with `$SCHED` different
+than `credit`) parameter is passed to Xen via the bootloader.
+Once the system is live, for creating a cpupool with Credit as its
+scheduler, either compile a cpupool configuration file, as described
+in `docs/man/xlcpupool.cfg.pod.5` (and as exemplified in
+`tools/examples/cpupool`), or use just `xl` directly:
+    xl cpupool-create name=\"pool1\" sched=\"credit\" cpus=[4,8]
+Two kind of interactions with the scheduler are possible:
+* checking or changing the global parameters, via, e.g.:
+    * `xl sched-credit -s`
+    * `xl sched-credit -s -p pool1`
+    * `xl sched-credit -s -t 20`
+* checking or changing a VM's scheduling parameters, via, e.g.:
+    * `xl sched-credit -d vm1`
+    * `xl sched-credit -d vm1 -w 512`
+# Technical details
+Implementation entirely lives in the hypervisor. Xen has a pluggable, hook
+based, architecture for schedulers. Actual Credit code is all inside one
+file: `xen/common/sched_credit.c`.
+# Limitations
+In Credit, a vCPU has a priority, a status (i.e., active or inactive),
+a weight and some credits... and all these things interact in a rather
+involved way. Also, with years of use, things have gotten even more
+complex (due to, e.g., the introduction of boosting, caps and vCPU
+Dealing with such complexity is starting to be an issue. Odd behavior
+or subtle scheduling anomalies, that is not always possible to act upon,
+have been identified already. [1][2][3]
+A certain lack of scalability and difficulties and weakness in dealing
+with mixed workloads and VMs with low latency requirements are other
+known problems. [4] For all these reasons, effort is ongoing to have
+Credit2 become the new default scheduler.
+# Testing
+Any change to Credit code must to be tested by doing at least the following:
+* create a few virtual machine and verify that they boot and can
+  run some basic workload (e.g., login into them and run simple commands),
+* shutdown/reboot the virtual machines,
+* shutdown the system.
+Ideally, all the above steps should **also** be performed in a configuration
+that includes cpupools, better if with pools using different schedulers, and
+by also doing the following:
+* move the virtual machines between cpupools.
+# References
+* [potential non-ideal behavior on hyperthreaded 
+* [long standing BOOST vs. migration 
bug]( [2]
+* [priority handling 
+* "Scheduler development update", XenSummit Asia 2009 
+* "Scheduling in Xen" [XPDS15 
+* [Xen Project 
+# History
+Date       Revision Version  Notes
+---------- -------- -------- -------------------------------------------
+2016-10-10 1        Xen 4.8  Document written
+---------- -------- -------- -------------------------------------------

Xen-devel mailing list

Reply via email to