config-linux: add schemata field to IntelRdt (#1230)

* config-linux: add schemata field to IntelRdt

Add a new "schemata" field to the Linux IntelRdt configuration. This
addresses the complexity of separate schema fields and resolves the
issue of supporting currently uncovered RDT features like L2 cache
allocation and CDP (Code and Data Prioritization).

The new field is for specifying the complete schemata (all schemas) to
be written to the schemata file in Linux resctrl fs. The aim is for
simple usage and runtime implementation (by not requiring any
parsing/filtering of data or otherwise re-implement parsing or
validation of the Linux resctrl interface) and also to support all RDT
features now and in the future (i.e. schemas like L2, L2CODE, L2DATA,
L3CODE and L3DATA and who knows L4 or something else in the future).

Behavior of existing fields is not changed but it is required that the
new schemata field is applied last.

Signed-off-by: Markus Lehtonen <[email protected]>

* Add linux.intelRdt.schemata to features.md

Signed-off-by: Markus Lehtonen <[email protected]>

---------

Signed-off-by: Markus Lehtonen <[email protected]>

Author: marquiz

config-linux.md

@@ -747,6 +747,7 @@ The following parameters can be specified for the container:
     The value SHOULD start with `L3:` and SHOULD NOT contain newlines.
 * **`memBwSchema`** *(string, OPTIONAL)* - specifies the schema of memory bandwidth per L3 cache id.
     The value MUST start with `MB:` and MUST NOT contain newlines.
+* **`schemata`** *(array of strings, OPTIONAL)* - specifies the schemata to be written to the `schemata` file in resctrlfs. Each element represents one line in the `schemata` file. The value MUST NOT contain newlines.
 
 The following rules on parameters MUST be applied:
 
@@ -756,15 +757,17 @@ The following rules on parameters MUST be applied:
 
 * If either `l3CacheSchema` or `memBwSchema` is set, runtimes MUST write the value to the `schemata` file in the that sub-directory discussed in `closID`.
 
-* If neither `l3CacheSchema` nor `memBwSchema` is set, runtimes MUST NOT write to `schemata` files in any `resctrl` pseudo-filesystems.
+* If `schemata` field is set, runtimes MUST write the value to the `schemata` file in the that sub-directory discussed in `closID`. If also `l3CacheSchema` or `memBwSchema` is set the value of `schemata` field must be written last, after the values from `l3CacheSchema` and `memBwSchema` has been written.
+
+* If none of `l3CacheSchema`, `memBwSchema` or `schemata` is set, runtimes MUST NOT write to `schemata` files in any `resctrl` pseudo-filesystems.
 
 * If `closID` is not set, runtimes MUST use the container ID from [`start`](runtime.md#start) and create the `<container-id>` directory.
 
-* If `closID` is set, `l3CacheSchema` and/or `memBwSchema` is set
+* If `closID` is set, `l3CacheSchema` and/or `memBwSchema` and/or `schemata` is set
   * if `closID` directory in a mounted `resctrl` pseudo-filesystem doesn't exist, the runtimes MUST create it.
   * if `closID` directory in a mounted `resctrl` pseudo-filesystem exists, runtimes MUST compare `l3CacheSchema` and/or `memBwSchema` value with `schemata` file, and [generate an error](runtime.md#errors) if doesn't match.
 
-* If `closID` is set, and neither of `l3CacheSchema` and `memBwSchema` are set, runtime MUST check if corresponding pre-configured directory `closID` is present in mounted `resctrl`. If such pre-configured directory `closID` exists, runtime MUST assign container to this `closID` and [generate an error](runtime.md#errors) if directory does not exist.
+* If `closID` is set, and none of `l3CacheSchema`, `memBwSchema` or `schemata` are set, runtime MUST check if corresponding pre-configured directory `closID` is present in mounted `resctrl`. If such pre-configured directory `closID` exists, runtime MUST assign container to this `closID` and [generate an error](runtime.md#errors) if directory does not exist.
 
 * **`enableCMT`** *(boolean, OPTIONAL)* - specifies if Intel RDT CMT should be enabled:
     * CMT (Cache Monitoring Technology) supports monitoring of the last-level cache (LLC) occupancy
@@ -776,18 +779,27 @@ The following rules on parameters MUST be applied:
 
 ### Example
 
-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 bandwidth of 10% with a memory bandwidth granularity of 10%.
+Consider a two-socket machine with:
+
+- two L3 caches where the default CBM is 0x7ff (11 bits)
+- eight L2 caches where the default CBM is 0xFF (8 bits)
+- minimum memory bandwidth of 10% with a memory bandwidth granularity of 10%
+
+Tasks inside the container:
 
-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 bandwidth of 20% on socket 0 and 70% on socket 1.
+- have access to the "upper" 7/11 of L3 cache on socket 0 and the "lower" 5/11 L3 cache on socket 1
+- have access to the "lower" 4/8 of L2 cache on socket 0 (socket 1 is left out from this example)
+- may use a maximum memory bandwidth of 20% on socket 0 and 70% on socket 1.
 
 ```json
 "linux": {
     "intelRdt": {
         "closID": "guaranteed_group",
-        "l3CacheSchema": "L3:0=7f0;1=1f",
-        "memBwSchema": "MB:0=20;1=70"
+        "schemata": [
+            "L3:0=7f0;1=1f",
+            "L2:0=f;1=f;2=f;3=f",
+            "MB:0=20;1=70"
+        ]
     }
 }
 ```

features-linux.md

@@ -201,12 +201,15 @@ Irrelevant to the availability of SELinux on the host operating system.
 Irrelevant to the availability of Intel RDT on the host operating system.
 
 * **`enabled`** (bool, OPTIONAL) represents whether the runtime supports Intel RDT.
+* **`schemata`** (bool, OPTIONAL) represents whether the
+  (`schemata` field of `linux.intelRdt` in `config.json`)[config-linux.md#intelrdt] is supported.
 
 ### Example
 
 ```json
 "intelRdt": {
-  "enabled": true
+  "enabled": true,
+  "schemata": true
 }
 ```
 

features.md

@@ -355,7 +355,8 @@ Here is a full example for reference.
       "enabled": true
     },
     "intelRdt": {
-      "enabled": true
+      "enabled": true,
+      "schemata": true
     }
   },
   "annotations": {

schema/config-linux.json

@@ -268,6 +268,9 @@
                     "closID": {
                         "type": "string"
                     },
+                    "schemata": {
+                        "$ref": "defs.json#/definitions/ArrayOfStrings"
+                    },
                     "l3CacheSchema": {
                         "type": "string"
                     },

specs-go/config.go

@@ -836,14 +836,23 @@ type LinuxSyscall struct {
 type LinuxIntelRdt struct {
 	// The identity for RDT Class of Service
 	ClosID string `json:"closID,omitempty"`
+
+	// Schemata specifies the complete schemata to be written as is to the
+	// schemata file in resctrl fs. Each element represents a single line in the schemata file.
+	// NOTE: This will overwrite schemas specified in the L3CacheSchema and/or
+	// MemBwSchema fields.
+	Schemata []string `json:"schemata,omitempty"`
+
 	// The schema for L3 cache id and capacity bitmask (CBM)
 	// Format: "L3:<cache_id0>=<cbm0>;<cache_id1>=<cbm1>;..."
+	// NOTE: Should not be specified if Schemata is non-empty.
 	L3CacheSchema string `json:"l3CacheSchema,omitempty"`
 
 	// The schema of memory bandwidth per L3 cache id
 	// Format: "MB:<cache_id0>=bandwidth0;<cache_id1>=bandwidth1;..."
 	// The unit of memory bandwidth is specified in "percentages" by
 	// default, and in "MBps" if MBA Software Controller is enabled.
+	// NOTE: Should not be specified if Schemata is non-empty.
 	MemBwSchema string `json:"memBwSchema,omitempty"`
 
 	// EnableCMT is the flag to indicate if the Intel RDT CMT is enabled. CMT (Cache Monitoring Technology) supports monitoring of