specs-go/config: add Intel RDT/MBA Linux support

Add support for Intel Resource Director Technology (RDT) / Memory Bandwidth Allocation (MBA). Add memory bandwidth resource constraints in Linux-specific configuration. This is the prerequisite of this runc proposal: opencontainers/runc#1596 For more information about Intel RDT/MBA, please refer to: opencontainers/runc#1596 Signed-off-by: Xiaochen Shen <[email protected]>
xiaochenshen · Oct 18, 2017 · 4bc6ff6 · 4bc6ff6
1 parent 4ebb31e
commit 4bc6ff6
Show file tree

Hide file tree

Showing 4 changed files with 59 additions and 9 deletions.
diff --git a/config-linux.md b/config-linux.md
@@ -466,19 +466,37 @@ The following parameters can be specified to set up the controller:
 The following parameters can be specified for the container:
 
 * **`l3CacheSchema`** *(string, OPTIONAL)* - specifies the schema for L3 cache id and capacity bitmask (CBM).
-    If `l3CacheSchema` is set, runtimes MUST write the value to the `schemata` file in the `<container-id>` directory discussed in `intelRdt`.
+* **`memBandwidth`** *(array of objects, OPTIONAL)* - an array of memory bandwidth (b/w) percentage per L3 cache id.
+    Each entry has the following structure:
+    * **`id`** *(uint32, REQUIRED)* - L3 cache id
+    * **`value`** *(uint32, REQUIRED)* - memory bandwidth (b/w) percentage
+
+    If `l3CacheSchema` or `memBandwidth` is set, runtimes MUST write the value to the `schemata` file in the `<container-id>` directory discussed in `intelRdt`.
 
-    If `l3CacheSchema` is not set, runtimes MUST NOT write to `schemata` files in any `resctrl` pseudo-filesystems.
+    If neither `l3CacheSchema` nor `memBandwidth` is set, runtimes MUST NOT write to `schemata` files in any `resctrl` pseudo-filesystems.
 
 ### Example
 
-Consider a two-socket machine with two L3 caches where the default CBM is 0xfffff and the max CBM length is 20 bits.
-Tasks inside the container only have access to the "upper" 80% of L3 cache id 0 and the "lower" 50% L3 cache id 1:
+Consider a two-socket machine with two L3 caches where the default CBM is 0x7ff and the max CBM length is 11 bits,
+and minimum memory b/w of 10% with a memory b/w granularity of 10%.
+
+Tasks inside the container only have access to the "upper" 7/11 of L3 cache on socket 0 and the "lower" 5/11 L3 cache on socket 1,
+and may use a maximum memory b/w of 20% on socket 0 and 70% on socket 1.
 
 ```json
 "linux": {
     "intelRdt": {
-        "l3CacheSchema": "L3:0=ffff0;1=3ff"
+        "l3CacheSchema": "L3:0=7f0;1=1f",
+        "memBandwidth": [
+            {
+                "id": 0,
+                "value": 20
+            },
+            {
+                "id": 1,
+                "value: 70
+            },
+        ]
     }
 }
 ```

diff --git a/schema/config-linux.json b/schema/config-linux.json
@@ -273,6 +273,13 @@
                     "l3CacheSchema": {
                         "id": "https://opencontainers.org/schema/bundle/linux/intelRdt/l3CacheSchema",
                         "type": "string"
+                    },
+                    "memBandwidth": {
+                        "id": "https://opencontainers.org/schema/bundle/linux/intelRdt/memBandwidth",
+                        "type": "array",
+                        "items": {
+                            "$ref": "defs-linux.json#/definitions/IntelRdtMemBandwidth"
+                        }
                     }
                 }
             }

diff --git a/schema/defs-linux.json b/schema/defs-linux.json
@@ -265,6 +265,21 @@
             "required": [
                 "type"
             ]
+        },
+        "IntelRdtMemBandwidth": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "$ref": "defs.json#/definitions/uint32"
+                },
+                "value": {
+                    "$ref": "defs.json#/definitions/uint32"
+                }
+            },
+            "required": [
+                "id",
+                "value"
+            ]
         }
     }
 }
diff --git a/specs-go/config.go b/specs-go/config.go
@@ -158,8 +158,8 @@ type Linux struct {
 	ReadonlyPaths []string `json:"readonlyPaths,omitempty"`
 	// MountLabel specifies the selinux context for the mounts in the container.
 	MountLabel string `json:"mountLabel,omitempty"`
-	// IntelRdt contains Intel Resource Director Technology (RDT) information
-	// for handling resource constraints (e.g., L3 cache) for the container
+	// IntelRdt contains Intel Resource Director Technology (RDT) information for
+	// handling resource constraints (e.g., L3 cache, memory bandwidth) for the container
 	IntelRdt *LinuxIntelRdt `json:"intelRdt,omitempty"`
 }
 
@@ -561,10 +561,20 @@ type LinuxSyscall struct {
 	Args   []LinuxSeccompArg  `json:"args,omitempty"`
 }
 
-// LinuxIntelRdt has container runtime resource constraints
-// for Intel RDT/CAT which introduced in Linux 4.10 kernel
+// LinuxMemBandwidth specifies memory bandwidth (b/w) percentage per L3 cache id
+type LinuxMemBandwidth struct {
+	id    uint32 `json:"id"`
+	value uint32 `json:"value"`
+}
+
+// LinuxIntelRdt has container runtime resource constraints for Intel RDT
+// CAT and MBA features which introduced in Linux 4.10 and 4.12 kernel
 type LinuxIntelRdt struct {
 	// The schema for L3 cache id and capacity bitmask (CBM)
 	// Format: "L3:<cache_id0>=<cbm0>;<cache_id1>=<cbm1>;..."
 	L3CacheSchema string `json:"l3CacheSchema,omitempty"`
+
+	// The schema of memory bandwidth (b/w) percentage per L3 cache id
+	// Format: "MB:<cache_id0>=bandwidth0;<cache_id1>=bandwidth1;..."
+	MemBandwidth []LinuxMemBandwidth `json:"memBandwidth,omitempty"`
 }