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 <>
Changes from v1:
* file renamed from credit.pandoc to sched_credit.pandoc;
* feature name is now 'Credit Scheduler';
* kill the 'e.g.'-s in the header (sorry!);
* removed 'Architecture' line from header, as this is arch independent;
* removed some text that was duplicated in other sched feature documents;
  it's redundant wrt what's in the wiki about schedulers, and the page
  is referenced.
 docs/features/sched_credit.pandoc |   97 +++++++++++++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)
 create mode 100644 docs/features/sched_credit.pandoc

diff --git a/docs/features/sched_credit.pandoc 
new file mode 100644
index 0000000..79587d8
--- /dev/null
+++ b/docs/features/sched_credit.pandoc
@@ -0,0 +1,97 @@
+% Credit Scheduler
+% Revision 1
+# Basics
+---------------- ----------------------------------------------------
+         Status: **Supported**
+      Component: Hypervisor
+---------------- ----------------------------------------------------
+# Overview
+Credit (also known as Credit1) is the default virtual CPU (vCPU) scheduler
+of the Xen hypervisor.
+It is a general purpose, weighted fair-share scheduler.
+# 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. Thanks to this, Credit code
+is all contained in `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 
+* "The Credit Scheduler" [on the Xen-Project 
+* "Xen Project Schedulers" [on the Xen-Project 
+# History
+Date       Revision Version  Notes
+---------- -------- -------- -------------------------------------------
+2016-10-14 1        Xen 4.8  Document written
+---------- -------- -------- -------------------------------------------

Xen-devel mailing list

Reply via email to