doc: Break out sample rules

Signed-off-by: Adam Litke <agl@us.ibm.com>

MANIFEST.in

@@ -1,3 +1,3 @@
-recursive-include doc *
+recursive-include doc * *.rules
 include momd
 include mom-guestd

doc/mom-balloon.rules → doc/balloon.rules

@@ -1,9 +1,6 @@
 # Mom Rules type=script
-#
-# Autoballooning Rules:
-#
 
-#require( ('Host', 'Guest', 'Balloon') )
+### Auto-Balloon ###############################################################
 
 ### Constants
 # If the percentage of host free memory drops below this value

doc/ksm.rules

@@ -0,0 +1,60 @@
+# Mom Rules type=script
+
+### KSM ########################################################################
+
+### Constants
+# The number of pages to add when increasing pages_to_scan
+ksm_pages_boost = 300
+
+# The number of pages to subtract when decreasing pages_to_scan
+ksm_pages_decay = -50
+
+# The min and max number of pages to scan per cycle when ksm is activated
+ksm_npages_min = 64
+ksm_npages_max = 1250
+
+# The number of ms to sleep between ksmd scans for a 16GB system.  Systems with
+# more memory will sleep less, while smaller systems will sleep more.
+ksm_sleep_ms_baseline = 10
+
+# A virtualization host tends to use most of its memory for running guests but
+# a certain amount is reserved for the host OS, non virtualization-related work,
+# and as a failsafe.  When free memory (including memory used for caches) drops
+# below this parcentage of total memory, the host is deemed under pressure. and
+# KSM will be started to try and free up some memory.
+ksm_free_percent = 0.20
+
+### Helper functions
+def change_npages(delta):
+    global ksm_npages_min, ksm_npages_max, Host, Output
+
+    newval = Host.ksm_pages_to_scan + delta
+    if newval > ksm_npages_max:
+        newval = ksm_npages_max
+    elif newval < ksm_npages_min:
+        newval = ksm_npages_min
+    Output.SetVar('ksm_pages_to_scan', newval)
+
+### Main Script
+# Methodology: Since running KSM does incur some overhead, try to run it only 
+# when necessary.  If the amount of committed KSM shareable memory is high or if
+# free memory is low, enable KSM to try to increase free memory.  Large memory
+# machines should scan more often than small ones.  Likewise, machines under
+# memory pressure should scan more aggressively then more idle machines.
+
+ksm_pressure_threshold = Host.mem_available * ksm_free_percent
+ksm_committed = Host.ksm_shareable
+
+if ksm_pressure_threshold + ksm_committed < Host.mem_available and \
+        Host.StatAvg('mem_free') > ksm_pressure_threshold:
+    # Disable KSM because memory isn't overcommited to qemu processes and
+    # there is enough free memory.
+    Output.SetVar('ksm_run', 0)
+else:
+    Output.SetVar('ksm_run', 1)
+    Output.SetVar('ksm_sleep_millisecs', ksm_sleep_ms_baseline * \
+                                         16 * 1024 * 1024 / Host.mem_available)
+    if Host.StatAvg('mem_free') < ksm_pressure_threshold:
+        change_npages(ksm_pages_boost)
+    else:
+        change_npages(ksm_pages_decay)