[PATCH] docs: Mention a common pitfall in ballooning

[PATCH] docs: Mention a common pitfall in ballooning

[George Dunlap]

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>
---
CC: Ian Campbell <ian.campbell@citrix.com>
CC: Ian Jackson <ian.jackson@citrix.com>
CC: Wei Liu <wei.liu2@citrix.com>
---
 docs/man/xl.cfg.pod.5 | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/man/xl.cfg.pod.5 b/docs/man/xl.cfg.pod.5
index 93cd7d2..4432f95 100644
--- 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
-- 
1.9.1

Re: [PATCH] docs: Mention a common pitfall in ballooning

[Ian Campbell]

On Thu, 2015-03-19 at 17:09 +0000, George Dunlap wrote:
> 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 + applied, thanks.