Documentation/x86: Document that resctrl bandwidth control units are MiB

[sfrench/cifs-2.6.git] / Documentation / arch / x86 / resctrl.rst

diff --git a/Documentation/arch/x86/resctrl.rst b/Documentation/arch/x86/resctrl.rst
index cb05d90111b4f5d8380f9a858d5b6d7c4ffb698c..3712d81cb50c67ac567c16ed7e768f2a79876ca4 100644 (file)
--- a/Documentation/arch/x86/resctrl.rst
+++ b/Documentation/arch/x86/resctrl.rst
@@ -35,7 +35,7 @@ about the feature from resctrl's info directory.
 
 To use the feature mount the file system::
 
- # mount -t resctrl resctrl [-o cdp[,cdpl2][,mba_MBps]] /sys/fs/resctrl
+ # mount -t resctrl resctrl [-o cdp[,cdpl2][,mba_MBps][,debug]] /sys/fs/resctrl
 
 mount options are:
 
@@ -45,7 +45,10 @@ mount options are:
        Enable code/data prioritization in L2 cache allocations.
 "mba_MBps":
        Enable the MBA Software Controller(mba_sc) to specify MBA
-       bandwidth in MBps
+       bandwidth in MiBps
+"debug":
+       Make debug files accessible. Available debug files are annotated with
+       "Available only with debug option".
 
 L2 and L3 CDP are controlled separately.
 
@@ -124,6 +127,13 @@ related to allocation:
                        "P":
                              Corresponding region is pseudo-locked. No
                              sharing allowed.
+"sparse_masks":
+               Indicates if non-contiguous 1s value in CBM is supported.
+
+                       "0":
+                             Only contiguous 1s value in CBM is supported.
+                       "1":
+                             Non-contiguous 1s value in CBM is supported.
 
 Memory bandwidth(MB) subdirectory contains the following files
 with respect to allocation:
@@ -299,7 +309,14 @@ All groups contain the following files:
 "tasks":
        Reading this file shows the list of all tasks that belong to
        this group. Writing a task id to the file will add a task to the
-       group. If the group is a CTRL_MON group the task is removed from
+       group. Multiple tasks can be added by separating the task ids
+       with commas. Tasks will be assigned sequentially. Multiple
+       failures are not supported. A single failure encountered while
+       attempting to assign a task will cause the operation to abort and
+       already added tasks before the failure will remain in the group.
+       Failures will be logged to /sys/fs/resctrl/info/last_cmd_status.
+
+       If the group is a CTRL_MON group the task is removed from
        whichever previous CTRL_MON group owned the task and also from
        any MON group that owned the task. If the group is a MON group,
        then the task must already belong to the CTRL_MON parent of this
@@ -342,6 +359,10 @@ When control is enabled all CTRL_MON groups will also contain:
        file. On successful pseudo-locked region creation the mode will
        automatically change to "pseudo-locked".
 
+"ctrl_hw_id":
+       Available only with debug option. The identifier used by hardware
+       for the control group. On x86 this is the CLOSID.
+
 When monitoring is enabled all MON groups will also contain:
 
 "mon_data":
@@ -355,6 +376,10 @@ When monitoring is enabled all MON groups will also contain:
        the sum for all tasks in the CTRL_MON group and all tasks in
        MON groups. Please see example section for more details on usage.
 
+"mon_hw_id":
+       Available only with debug option. The identifier used by hardware
+       for the monitor group. On x86 this is the RMID.
+
 Resource allocation rules
 -------------------------
 
@@ -445,12 +470,13 @@ For cache resources we describe the portion of the cache that is available
 for allocation using a bitmask. The maximum value of the mask is defined
 by each cpu model (and may be different for different cache levels). It
 is found using CPUID, but is also provided in the "info" directory of
-the resctrl file system in "info/{resource}/cbm_mask". Intel hardware
+the resctrl file system in "info/{resource}/cbm_mask". Some Intel hardware
 requires that these masks have all the '1' bits in a contiguous block. So
 0x3, 0x6 and 0xC are legal 4-bit masks with two bits set, but 0x5, 0x9
-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.
+and 0xA are not. Check /sys/fs/resctrl/info/{resource}/sparse_masks
+if non-contiguous 1s value is supported. 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 bandwidth Allocation and monitoring
 ==========================================
@@ -500,7 +526,7 @@ threads start using more cores in an rdtgroup, the actual bandwidth may
 increase or vary although user specified bandwidth percentage is same.
 
 In order to mitigate this and make the interface more user friendly,
-resctrl added support for specifying the bandwidth in MBps as well.  The
+resctrl added support for specifying the bandwidth in MiBps as well.  The
 kernel underneath would use a software feedback mechanism or a "Software
 Controller(mba_sc)" which reads the actual bandwidth using MBM counters
 and adjust the memory bandwidth percentages to ensure::
@@ -547,13 +573,13 @@ Memory b/w domain is L3 cache.
 
        MB:<cache_id0>=bandwidth0;<cache_id1>=bandwidth1;...
 
-Memory bandwidth Allocation specified in MBps
+Memory bandwidth Allocation specified in MiBps
 ---------------------------------------------
 
 Memory bandwidth domain is L3 cache.
 ::
 
-       MB:<cache_id0>=bw_MBps0;<cache_id1>=bw_MBps1;...
+       MB:<cache_id0>=bw_MiBps0;<cache_id1>=bw_MiBps1;...
 
 Slow Memory Bandwidth Allocation (SMBA)
 ---------------------------------------