Merge pull request #136 from djs55/memory-accounting

Improve the memory accounting a bit

Author: djs55

xapi/design/memory-accounting.md

@@ -4,6 +4,7 @@ layout: default
 ---
 
 Memory is used for many things:
+
 - the hypervisor code: this is the Xen executable itself
 - the hypervisor heap: this is needed for per-domain structures and per-vCPU
   structures
@@ -23,15 +24,19 @@ at system boot time and model the per-VM overheads.
 Host overhead
 -------------
 
-TBD
+The host overhead is not managed by xapi, instead it is sampled. After the host
+boots and before any VMs start, xapi asks Xen how much memory the host has in
+total, and how much memory is currently free. Xapi subtracts the free from the
+total and stores this as the host overhead.
 
 VM overhead
 ------------
 
 The inputs to the model are
-- VM.memory_static_max: the maximum amount of RAM the domain will be able to use
-- VM.HVM_shadow_multiplier: allows the shadow memory to be increased
-- VM.VCPUs_max: the maximum number of vCPUs the domain will be able to use
+
+- `VM.memory_static_max`: the maximum amount of RAM the domain will be able to use
+- `VM.HVM_shadow_multiplier`: allows the shadow memory to be increased
+- `VM.VCPUs_max`: the maximum number of vCPUs the domain will be able to use
 
 First the shadow memory is calculated, in MiB
 
@@ -44,9 +49,18 @@ Second the VM overhead is calculated, in MiB
 Memory required to start a VM
 -----------------------------
 
-TBD
+If ballooning is disabled, the memory required to start a VM is the same as the VM
+overhead above.
+
+If ballooning is enabled then the memory calculation above is modified to use the
+`VM.memory_dynamic_max` rather than the `VM.memory_static_max`.
 
 Memory required to migrate a VM
 -------------------------------
 
-TBD
+If ballooning is disabled, the memory required to receive a migrating VM is the same
+as the VM overhead above.
+
+If ballooning is enabled, then the VM will first be ballooned down to `VM.memory_dynamic_min`
+and then it will be migrated across. If the VM fails to balloon all the way down, then
+correspondingly more memory will be required on the receiving side.