docs: Mention a common pitfall in ballooning

Several users have reported that their available free memory in the
guest when they used maxmem >> memory was much smaller than when
maxmem == memory.  This is the unavoidable consequence of how
ballooning works, but it's not something users expect.

Warn them of this effect in the place we tell them how to make it
happen, so they aren't surprised.

Signed-off-by: George Dunlap <george.dunlap@eu.citrix.com>
Acked-by: Ian Campbell <ian.campbell@citrix.com>

diff --git a/docs/man/xl.cfg.pod.5 b/docs/man/xl.cfg.pod.5
index ec2853052705e2a7477bafa758bd61060e909839..f936dfc5ffa68da087bb9d0ad871830295e9856e 100644 (file)
--- a/docs/man/xl.cfg.pod.5
+++ b/docs/man/xl.cfg.pod.5
@@ -264,6 +264,13 @@ if the values of B<memory=> and B<maxmem=> differ.
 A "pre-ballooned" HVM guest needs a balloon driver, without a balloon driver
 it will crash.
 
+NOTE: Because of the way ballooning works, the guest has to allocate
+memory to keep track of maxmem pages, regardless of how much memory it
+actually has available to it.  A guest with maxmem=262144 and
+memory=8096 will report significantly less memory available for use
+than a system with maxmem=8096 memory=8096 due to the memory overhead
+of having to track the unused pages.
+
 =back
 
 =head3 Guest Virtual NUMA Configuration