[PATCH 1/8] Documentation, x86: Documentation for Intel Mem b/w allocation user interface

[Vikas Shivappa <vikas.shivappa@linux.intel.com>]

Memory b/w allocation is part of Intel RDT(resource director technology)
which lets user control the amount of memory b/w (L2 external b/w) per
thread. This is done programming MSR interfaces like cache allocation
technology and other RDT features.
This patch adds documentation for Memory b/w allocation interface usage.

Signed-off-by: Vikas Shivappa <vikas.shivappa@linux.intel.com>
---
 Documentation/x86/intel_rdt_ui.txt | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/Documentation/x86/intel_rdt_ui.txt b/Documentation/x86/intel_rdt_ui.txt
index d918d26..23959ba 100644
--- a/Documentation/x86/intel_rdt_ui.txt
+++ b/Documentation/x86/intel_rdt_ui.txt
@@ -4,6 +4,7 @@ Copyright (C) 2016 Intel Corporation
 
 Fenghua Yu <fenghua.yu@intel.com>
 Tony Luck <tony.luck@intel.com>
+Vikas Shivappa <vikas.shivappa@intel.com>
 
 This feature is enabled by the CONFIG_INTEL_RDT_A Kconfig and the
 X86 /proc/cpuinfo flag bits "rdt", "cat_l3" and "cdp_l3".
@@ -107,6 +108,19 @@ and 0xA are not.  On a system with a 20-bit mask each bit represents 5%
 of the capacity of the cache. You could partition the cache into four
 equal parts with masks: 0x1f, 0x3e0, 0x7c00, 0xf8000.
 
+Memory b/w throttle
+-------------------
+For Memory b/w resource, the portion of total memory b/w the user can
+restrict or 'throttle by' is indicated by the thrtl_by values.
+
+Throttle by values could be linear scale or non-linear scale.  In linear
+scale a thrtl_by value of say 20 would throttle the memory b/w by 20%
+allowing only 80% max b/w. In nonlinear scale currently SDM specifies
+throttle values in 2^n values. However the h/w does not guarantee a
+specific curve for the amount of memory b/w that is actually throttled.
+But for any thrtl_by value x > y, its guaranteed that x would throttle
+more b/w than y.  The info directory specifies the max thrtl_by value
+and thrtl_by granularity.
 
 L3 details (code and data prioritization disabled)
 --------------------------------------------------
@@ -129,6 +143,13 @@ schemata format is always:
 
 	L2:<cache_id0>=<cbm>;<cache_id1>=<cbm>;...
 
+Memory b/w Allocation details
+-----------------------------
+
+Memory b/w domain is L3 cache.
+
+	MB:<cache_id0>=thrtl_by;<cache_id1>=thrtl_by;...
+
 Example 1
 ---------
 On a two socket machine (one L3 cache per socket) with just four bits
@@ -185,6 +206,16 @@ Ditto for the second real time task (with the remaining 25% of cache):
 # echo 5678 > p1/tasks
 # taskset -cp 2 5678
 
+For the same 2 socket system with memory b/w resource and CAT L3 the
+schemata would look like:
+
+Assume max_thrtl_by is 90 and thrtl_gran is 10.
+
+# echo -e "L3:0=f8000;1=fffff\nMB:0=10;1=30" > p0/schemata
+
+This would throttle the socket 1 memory b/w by 10% and socket2 memory
+b/w by 30%
+
 Example 3
 ---------
 
-- 
1.9.1