specs-go/config: add Core Scheduling support

Linux kernel 5.14 adds the support for Core Scheduling.

This allows setting and copying core scheduling 'task cookies' between
the container process and the threads (PID), processes (TGID), and
process groups (PGID), which helps define groups of tasks that can be
co-scheduled on the same core. These groups can be specified either for
security usecases or for performance usecases.

opencontainers#1113

Signed-off-by: Kailun Qin <[email protected]>

config.md

@@ -212,6 +212,20 @@ For Linux-based systems, the `process` object supports the following process-spe
  For more information on how these two settings work together, see [the memory cgroup documentation section 10. OOM Contol][cgroup-v1-memory_2].
 * **`selinuxLabel`** (string, OPTIONAL) specifies the SELinux label for the process.
  For more information about SELinux, see [SELinux documentation][selinux].
+* **`coreSched`** (object, OPTIONAL) is an object containing the Core Scheduling config options for the container.
+ This provides support for setting and copying core scheduling 'task cookies' between the
+ container process and the threads (PID), processes (TGID), and process groups (PGID), which
+ helps define groups of tasks that can be co-scheduled on the same core.
+ These groups can be specified either for security usecases (one group of tasks don’t trust
+ another), or for performance usecases (some workloads may benefit from running on the same core
+ as they don’t need the same hardware resources of the shared core, or may prefer different cores
+ if they do share hardware resource needs).
+ For more information about Core Scheduling, see [Core Scheduling documentation][core-scheduling].
+ `coreSched` defines the following operations:
+
+ * **`create`** (bool, OPTIONAL) controls whether to create a new unique cookie for the process in the container.
+ * **`shareTo`** (array of objects, OPTIONAL) specifies the PIDs that the core_sched cookie of the current process should push to.
+ * **`shareFrom`** (array of objects, OPTIONAL) specifies the PIDs that the core_sched cookie of the current process should pull from.
 
 ### <a name="configUser" />User
 
@@ -253,6 +267,16 @@ _Note: symbolic name for uid and gid, such as uname and gname respectively, are
  ],
  "apparmorProfile": "acme_secure_profile",
  "selinuxLabel": "system_u:system_r:svirt_lxc_net_t:s0:c124,c675",
+ "coreSched": {
+ "create": true,
+ "shareTo": {
+ "tgids": [1, 3],
+ "pgids": [0]
+ },
+ "shareFrom": {
+ "tgids": [2, 8]
+ }
+ },
  "noNewPrivileges": true,
  "capabilities": {
  "bounding": [
@@ -958,6 +982,7 @@ Here is a full example `config.json` for reference.
 
 [apparmor]: https://wiki.ubuntu.com/AppArmor
 [cgroup-v1-memory_2]: https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt
+[core-scheduling]: https://www.kernel.org/doc/html/latest/admin-guide/hw-vuln/core-scheduling.html
 [selinux]:https://selinuxproject.org/page/Main_Page
 [no-new-privs]: https://www.kernel.org/doc/Documentation/prctl/no_new_privs.txt
 [proc_2]: https://www.kernel.org/doc/Documentation/filesystems/proc.txt

specs-go/config.go

@@ -58,6 +58,8 @@ type Process struct {
  OOMScoreAdj *int `json:"oomScoreAdj,omitempty" platform:"linux"`
  // SelinuxLabel specifies the selinux context that the container process is run as.
  SelinuxLabel string `json:"selinuxLabel,omitempty" platform:"linux"`
+ // CoreSched specifies the Core Scheduling config options for the container.
+ CoreSched *LinuxCoreSched `json:"coreSched,omitempty" platform:"linux"`
 }
 
 // LinuxCapabilities specifies the list of allowed capabilities that are kept for a process.
@@ -75,6 +77,27 @@ type LinuxCapabilities struct {
  Ambient []string `json:"ambient,omitempty" platform:"linux"`
 }
 
+// LinuxCoreSched defines the Core Scheduling config options for the container.
+type LinuxCoreSched struct {
+ // Create controls whether to create a new unique cookie for the process in the container.
+ Create bool `json:"create,omitempty" platform:"linux"`
+ // ShareTo specifies the PIDs that the core_sched cookie of the current process should push to.
+ ShareTo *LinuxCoreSchedPids `json:"shareTo,omitempty" platform:"linux"`
+ // ShareFrom specifies the PIDs that the core_sched cookie of the current process should pull from.
+ ShareFrom *LinuxCoreSchedPids `json:"shareFrom,omitempty" platform:"linux"`
+}
+
+// LinuxCoreSchedPids defines the PIDs that Core Scheduling supports for setting and copying 'task cookies'.
+// 'PID == 0' implies the current process.
+type LinuxCoreSchedPids struct {
+ // Pids are the threads.
+ Pids []int `json:"pids,omitempty" platform:"linux"`
+ // Tgids are the processes.
+ Tgids []int `json:"tgids,omitempty" platform:"linux"`
+ // Pgids are the process groups.
+ Pgids []int `json:"pgids,omitempty" platform:"linux"`
+}
+
 // Box specifies dimensions of a rectangle. Used for specifying the size of a console.
 type Box struct {
  // Height is the vertical dimension of a box.