libcontainer: add support for Intel RDT/CAT in runc

About Intel RDT/CAT feature:
Intel platforms with new Xeon CPU support Intel Resource Director Technology
(RDT). Cache Allocation Technology (CAT) is a sub-feature of RDT, which
currently supports L3 cache resource allocation.

This feature provides a way for the software to restrict cache allocation to a
defined 'subset' of L3 cache which may be overlapping with other 'subsets'.
The different subsets are identified by class of service (CLOS) and each CLOS
has a capacity bitmask (CBM).

For more information about Intel RDT/CAT can be found in the section 17.17
of Intel Software Developer Manual.

About Intel RDT/CAT kernel interface:
In Linux 4.10 kernel or newer, the interface is defined and exposed via
"resource control" filesystem, which is a "cgroup-like" interface.

Comparing with cgroups, it has similar process management lifecycle and
interfaces in a container. But unlike cgroups' hierarchy, it has single level
filesystem layout.

Intel RDT "resource control" filesystem hierarchy:
mount -t resctrl resctrl /sys/fs/resctrl
tree /sys/fs/resctrl
/sys/fs/resctrl/
|-- info
|   |-- L3
|       |-- cbm_mask
|       |-- min_cbm_bits
|       |-- num_closids
|-- cpus
|-- schemata
|-- tasks
|-- <container_id>
    |-- cpus
    |-- schemata
    |-- tasks

For runc, we can make use of `tasks` and `schemata` configuration for L3 cache
resource constraints.

The file `tasks` has a list of tasks that belongs to this group (e.g.,
<container_id>" group). Tasks can be added to a group by writing the task ID
to the "tasks" file  (which will automatically remove them from the previous
group to which they belonged). New tasks created by fork(2) and clone(2) are
added to the same group as their parent. If a pid is not in any sub group, it
Is in root group.

The file `schemata` has allocation bitmasks/values for L3 cache on each socket,
which contains L3 cache id and capacity bitmask (CBM).
	Format: "L3:<cache_id0>=<cbm0>;<cache_id1>=<cbm1>;..."
For example, on a two-socket machine, L3's schema line could be `L3:0=ff;1=c0`
which means L3 cache id 0's CBM is 0xff, and L3 cache id 1's CBM is 0xc0.

The valid L3 cache CBM is a *contiguous bits set* and number of bits that can
be set is less than the max bit. The max bits in the CBM is varied among
supported Intel Xeon platforms. In Intel RDT "resource control" filesystem
layout, the CBM in a group should be a subset of the CBM in root. Kernel will
check if it is valid when writing. e.g., 0xfffff in root indicates the max bits
of CBM is 20 bits, which mapping to entire L3 cache capacity. Some valid CBM
values to set in a group: 0xf, 0xf0, 0x3ff, 0x1f00 and etc.

For more information about Intel RDT/CAT kernel interface:
https://www.kernel.org/doc/Documentation/x86/intel_rdt_ui.txt

An example for runc:
Consider a two-socket machine with two L3 caches where the default CBM is
0xfffff and the max CBM length is 20 bits. With this configuration, tasks
inside the container only have access to the "upper" 80% of L3 cache id 0 and
the "lower" 50% L3 cache id 1:

"linux": {
	"intelRdt": {
		"l3CacheSchema": "L3:0=ffff0;1=3ff"
	}
}

Signed-off-by: Xiaochen Shen <xiaochen.shen@intel.com>

events.go

@@ -24,11 +24,12 @@ type event struct {
 
 // stats is the runc specific stats structure for stability when encoding and decoding stats.
 type stats struct {
-	CPU     cpu                `json:"cpu"`
-	Memory  memory             `json:"memory"`
-	Pids    pids               `json:"pids"`
-	Blkio   blkio              `json:"blkio"`
-	Hugetlb map[string]hugetlb `json:"hugetlb"`
+	CPU      cpu                `json:"cpu"`
+	Memory   memory             `json:"memory"`
+	Pids     pids               `json:"pids"`
+	Blkio    blkio              `json:"blkio"`
+	Hugetlb  map[string]hugetlb `json:"hugetlb"`
+	IntelRdt intelRdt           `json:"intel_rdt"`
 }
 
 type hugetlb struct {
@@ -95,6 +96,12 @@ type memory struct {
 	Raw       map[string]uint64 `json:"raw,omitempty"`
 }
 
+type intelRdt struct {
+	// The read-only default "schema" in root, for reference
+	L3CacheSchemaRoot string `json:"l3_cache_schema_root,omitempty"`
+	L3CacheSchema     string `json:"l3_cache_schema,omitempty"`
+}
+
 var eventsCommand = cli.Command{
 	Name:  "events",
 	Usage: "display container events such as OOM notifications, cpu, memory, and IO usage statistics",
@@ -226,6 +233,14 @@ func convertLibcontainerStats(ls *libcontainer.Stats) *stats {
 	for k, v := range cg.HugetlbStats {
 		s.Hugetlb[k] = convertHugtlb(v)
 	}
+
+	is := ls.IntelRdtStats
+	if is == nil {
+		return &s
+	}
+	s.IntelRdt.L3CacheSchemaRoot = is.IntelRdtRootStats.L3CacheSchema
+	s.IntelRdt.L3CacheSchema = is.IntelRdtStats.L3CacheSchema
+
 	return &s
 }
 

libcontainer/configs/config.go

@@ -186,6 +186,10 @@ type Config struct {
 
 	// Rootless specifies whether the container is a rootless container.
 	Rootless bool `json:"rootless"`
+
+	// IntelRdt specifies specific settings for Intel RDT/CAT group that the container is
+	// placed into to limit the resources (e.g., L3 cache) the container has available
+	IntelRdt *IntelRdt `json:"intel_rdt,omitempty"`
 }
 
 type Hooks struct {

libcontainer/configs/intelrdt.go

@@ -0,0 +1,7 @@
+package configs
+
+type IntelRdt struct {
+	// The schema for L3 cache id and capacity bitmask (CBM)
+	// Format: "L3:<cache_id0>=<cbm0>;<cache_id1>=<cbm1>;..."
+	L3CacheSchema string `json:"l3_cache_schema,omitempty"`
+}

libcontainer/configs/validate/validator.go

@@ -7,6 +7,7 @@ import (
 	"strings"
 
 	"github.com/opencontainers/runc/libcontainer/configs"
+	"github.com/opencontainers/runc/libcontainer/intelrdt"
 	selinux "github.com/opencontainers/selinux/go-selinux"
 )
 
@@ -40,6 +41,9 @@ func (v *ConfigValidator) Validate(config *configs.Config) error {
 	if err := v.sysctl(config); err != nil {
 		return err
 	}
+	if err := v.intelrdt(config); err != nil {
+		return err
+	}
 	if config.Rootless {
 		if err := v.rootless(config); err != nil {
 			return err
@@ -153,6 +157,19 @@ func (v *ConfigValidator) sysctl(config *configs.Config) error {
 	return nil
 }
 
+func (v *ConfigValidator) intelrdt(config *configs.Config) error {
+	if config.IntelRdt != nil {
+		if !intelrdt.IsIntelRdtEnabled() {
+			return fmt.Errorf("intelRdt is specified in config, but Intel RDT is not supported")
+		}
+		if config.IntelRdt.L3CacheSchema == "" {
+			return fmt.Errorf("intelRdt is specified in config, but intelRdt.l3CacheSchema is empty")
+		}
+	}
+
+	return nil
+}
+
 func isSymbolicLink(path string) (bool, error) {
 	fi, err := os.Lstat(path)
 	if err != nil {

libcontainer/container_linux.go

@@ -22,6 +22,7 @@ import (
 	"github.com/opencontainers/runc/libcontainer/cgroups"
 	"github.com/opencontainers/runc/libcontainer/configs"
 	"github.com/opencontainers/runc/libcontainer/criurpc"
+	"github.com/opencontainers/runc/libcontainer/intelrdt"
 	"github.com/opencontainers/runc/libcontainer/resourcemanager"
 	"github.com/opencontainers/runc/libcontainer/system"
 	"github.com/opencontainers/runc/libcontainer/utils"
@@ -65,6 +66,9 @@ type State struct {
 
 	// Container's standard descriptors (std{in,out,err}), needed for checkpoint and restore
 	ExternalDescriptors []string `json:"external_descriptors,omitempty"`
+
+	// Intel RDT "resource control" filesystem path
+	IntelRdtPath string `json:"intel_rdt_path"`
 }
 
 // Container is a libcontainer container object.
@@ -163,6 +167,13 @@ func (c *linuxContainer) Stats() (*Stats, error) {
 	if err != nil {
 		return stats, newSystemErrorWithCause(err, "getting container stats from cgroups")
 	}
+	if intelRdtManager, ok := c.resourceManagers["intelrdt"]; ok == true {
+		intelRdtStats, err := intelRdtManager.GetStats()
+		if err != nil {
+			return stats, newSystemErrorWithCause(err, "getting container's Intel RDT stats")
+		}
+		stats.IntelRdtStats = intelRdtStats.(*intelrdt.Stats)
+	}
 	for _, iface := range c.config.Networks {
 		switch iface.Type {
 		case "veth":
@@ -444,6 +455,7 @@ func (c *linuxContainer) newSetnsProcess(p *Process, cmd *exec.Cmd, parentPipe,
 	return &setnsProcess{
 		cmd:           cmd,
 		cgroupPaths:   c.resourceManagers["cgroups"].GetPaths(),
+		intelRdtPath:  state.IntelRdtPath,
 		childPipe:     childPipe,
 		parentPipe:    parentPipe,
 		config:        c.newInitConfig(p),
@@ -1418,6 +1430,10 @@ func (c *linuxContainer) currentState() (*State, error) {
 		startTime, _ = c.initProcess.startTime()
 		externalDescriptors = c.initProcess.externalDescriptors()
 	}
+	intelRdtPath, err := intelrdt.GetIntelRdtPath(c.ID())
+	if err != nil {
+		intelRdtPath = ""
+	}
 	state := &State{
 		BaseState: BaseState{
 			ID:                   c.ID(),
@@ -1428,6 +1444,7 @@ func (c *linuxContainer) currentState() (*State, error) {
 		},
 		Rootless:            c.config.Rootless,
 		CgroupPaths:         c.resourceManagers["cgroups"].GetPaths(),
+		IntelRdtPath:        intelRdtPath,
 		NamespacePaths:      make(map[configs.NamespaceType]string),
 		ExternalDescriptors: externalDescriptors,
 	}

libcontainer/container_linux_test.go

@@ -9,6 +9,7 @@ import (
 
 	"github.com/opencontainers/runc/libcontainer/cgroups"
 	"github.com/opencontainers/runc/libcontainer/configs"
+	"github.com/opencontainers/runc/libcontainer/intelrdt"
 	"github.com/opencontainers/runc/libcontainer/resourcemanager"
 )
 
@@ -19,6 +20,13 @@ type mockCgroupManager struct {
 	paths   map[string]string
 }
 
+type mockIntelRdtManager struct {
+	pids    []int
+	allPids []int
+	stats   *intelrdt.Stats
+	path    string
+}
+
 func (m *mockCgroupManager) GetPids() ([]int, error) {
 	return m.pids, nil
 }
@@ -51,6 +59,40 @@ func (m *mockCgroupManager) Freeze(state configs.FreezerState) error {
 	return nil
 }
 
+func (m *mockIntelRdtManager) GetPids() ([]int, error) {
+	return m.pids, nil
+}
+
+func (m *mockIntelRdtManager) GetAllPids() ([]int, error) {
+	return m.allPids, nil
+}
+
+func (m *mockIntelRdtManager) GetStats() (interface{}, error) {
+	return m.stats, nil
+}
+
+func (m *mockIntelRdtManager) Apply(pid int) error {
+	return nil
+}
+
+func (m *mockIntelRdtManager) Set(container *configs.Config) error {
+	return nil
+}
+
+func (m *mockIntelRdtManager) Destroy() error {
+	return nil
+}
+
+func (m *mockIntelRdtManager) GetPaths() map[string]string {
+	paths := make(map[string]string)
+	paths["intelrdt"] = m.path
+	return paths
+}
+
+func (m *mockIntelRdtManager) Freeze(state configs.FreezerState) error {
+	return nil
+}
+
 type mockProcess struct {
 	_pid    int
 	started string
@@ -121,6 +163,14 @@ func TestGetContainerStats(t *testing.T) {
 			},
 		},
 	}
+	container.resourceManagers["intelrdt"] = &mockIntelRdtManager{
+		pids: []int{1, 2, 3},
+		stats: &intelrdt.Stats{
+			IntelRdtStats: intelrdt.IntelRdtStats{
+				L3CacheSchema: "L3:0=ffff0;1=fff00",
+			},
+		},
+	}
 	stats, err := container.Stats()
 	if err != nil {
 		t.Fatal(err)
@@ -131,13 +181,22 @@ func TestGetContainerStats(t *testing.T) {
 	if stats.CgroupStats.MemoryStats.Usage.Usage != 1024 {
 		t.Fatalf("expected memory usage 1024 but recevied %d", stats.CgroupStats.MemoryStats.Usage.Usage)
 	}
+	if intelrdt.IsIntelRdtEnabled() {
+		if stats.IntelRdtStats == nil {
+			t.Fatal("intel rdt stats are nil")
+		}
+		if stats.IntelRdtStats.IntelRdtStats.L3CacheSchema != "L3:0=ffff0;1=fff00" {
+			t.Fatalf("expected L3CacheSchema L3:0=ffff0;1=fff00 but recevied %s", stats.IntelRdtStats.IntelRdtStats.L3CacheSchema)
+		}
+	}
 }
 
 func TestGetContainerState(t *testing.T) {
 	var (
-		pid                 = os.Getpid()
-		expectedMemoryPath  = "/sys/fs/cgroup/memory/myid"
-		expectedNetworkPath = "/networks/fd"
+		pid                  = os.Getpid()
+		expectedMemoryPath   = "/sys/fs/cgroup/memory/myid"
+		expectedNetworkPath  = "/networks/fd"
+		expectedIntelRdtPath = "/sys/fs/resctrl/myid"
 	)
 	container := &linuxContainer{
 		id: "myid",
@@ -170,6 +229,15 @@ func TestGetContainerState(t *testing.T) {
 			"memory": expectedMemoryPath,
 		},
 	}
+	container.resourceManagers["intelrdt"] = &mockIntelRdtManager{
+		pids: []int{1, 2, 3},
+		stats: &intelrdt.Stats{
+			IntelRdtStats: intelrdt.IntelRdtStats{
+				L3CacheSchema: "L3:0=ffff0;1=fff00",
+			},
+		},
+		path: expectedIntelRdtPath,
+	}
 	container.state = &createdState{c: container}
 	state, err := container.State()
 	if err != nil {
@@ -188,6 +256,15 @@ func TestGetContainerState(t *testing.T) {
 	if memPath := paths["memory"]; memPath != expectedMemoryPath {
 		t.Fatalf("expected memory path %q but received %q", expectedMemoryPath, memPath)
 	}
+	if intelrdt.IsIntelRdtEnabled() {
+		intelRdtPath := state.IntelRdtPath
+		if intelRdtPath == "" {
+			t.Fatal("intel rdt path should not be empty")
+		}
+		if intelRdtPath != expectedIntelRdtPath {
+			t.Fatalf("expected intel rdt path %q but received %q", expectedIntelRdtPath, intelRdtPath)
+		}
+	}
 	for _, ns := range container.config.Namespaces {
 		path := state.NamespacePaths[ns.Type]
 		if path == "" {

libcontainer/factory_linux.go

@@ -19,6 +19,7 @@ import (
 	"github.com/opencontainers/runc/libcontainer/cgroups/systemd"
 	"github.com/opencontainers/runc/libcontainer/configs"
 	"github.com/opencontainers/runc/libcontainer/configs/validate"
+	"github.com/opencontainers/runc/libcontainer/intelrdt"
 	"github.com/opencontainers/runc/libcontainer/resourcemanager"
 	"github.com/opencontainers/runc/libcontainer/utils"
 )
@@ -89,6 +90,19 @@ func RootlessCgroups(l *LinuxFactory) error {
 	return nil
 }
 
+// IntelRdtfs is an options func to configure a LinuxFactory to return
+// containers that use the Intel RDT "resource control" filesystem to
+// create and manage Intel Xeon platform shared resources (e.g., L3 cache).
+func IntelRdtFs(l *LinuxFactory) error {
+	l.NewIntelRdtManager = func(config *configs.Config, id string) intelrdt.Manager {
+		return &intelrdt.IntelRdtManager{
+			Config: config,
+			Id:     id,
+		}
+	}
+	return nil
+}
+
 // TmpfsRoot is an option func to mount LinuxFactory.Root to tmpfs.
 func TmpfsRoot(l *LinuxFactory) error {
 	mounted, err := mount.Mounted(l.Root)
@@ -153,6 +167,9 @@ type LinuxFactory struct {
 
 	// NewCgroupsManager returns an initialized cgroups manager for a single container.
 	NewCgroupsManager func(config *configs.Cgroup, paths map[string]string) cgroups.Manager
+
+	// NewIntelRdtManager returns an initialized Intel RDT manager for a single container.
+	NewIntelRdtManager func(config *configs.Config, id string) intelrdt.Manager
 }
 
 func (l *LinuxFactory) Create(id string, config *configs.Config) (Container, error) {
@@ -197,6 +214,9 @@ func (l *LinuxFactory) Create(id string, config *configs.Config) (Container, err
 	}
 	resourceManagers := make(map[string]resourcemanager.ResourceManager)
 	resourceManagers["cgroups"] = l.NewCgroupsManager(config.Cgroups, nil)
+	if intelrdt.IsIntelRdtEnabled() {
+		resourceManagers["intelrdt"] = l.NewIntelRdtManager(config, id)
+	}
 	c.resourceManagers = resourceManagers
 	c.state = &stoppedState{c: c}
 	return c, nil
@@ -232,6 +252,9 @@ func (l *LinuxFactory) Load(id string) (Container, error) {
 	}
 	resourceManagers := make(map[string]resourcemanager.ResourceManager)
 	resourceManagers["cgroups"] = l.NewCgroupsManager(state.Config.Cgroups, state.CgroupPaths)
+	if intelrdt.IsIntelRdtEnabled() {
+		resourceManagers["intelrdt"] = l.NewIntelRdtManager(&state.Config, id)
+	}
 	c.resourceManagers = resourceManagers
 	c.state = &loadedState{c: c}
 	if err := c.refreshState(); err != nil {

libcontainer/factory_linux_test.go

@@ -49,6 +49,32 @@ func TestFactoryNew(t *testing.T) {
 	}
 }
 
+func TestFactoryNewIntelRdt(t *testing.T) {
+	root, rerr := newTestRoot()
+	if rerr != nil {
+		t.Fatal(rerr)
+	}
+	defer os.RemoveAll(root)
+	factory, err := New(root, Cgroupfs, IntelRdtFs)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if factory == nil {
+		t.Fatal("factory should not be nil")
+	}
+	lfactory, ok := factory.(*LinuxFactory)
+	if !ok {
+		t.Fatal("expected linux factory returned on linux based systems")
+	}
+	if lfactory.Root != root {
+		t.Fatalf("expected factory root to be %q but received %q", root, lfactory.Root)
+	}
+
+	if factory.Type() != "libcontainer" {
+		t.Fatalf("unexpected factory type: %q, expected %q", factory.Type(), "libcontainer")
+	}
+}
+
 func TestFactoryNewTmpfs(t *testing.T) {
 	root, rerr := newTestRoot()
 	if rerr != nil {
@@ -163,7 +189,7 @@ func TestFactoryLoadContainer(t *testing.T) {
 	if err := marshal(filepath.Join(root, id, stateFilename), expectedState); err != nil {
 		t.Fatal(err)
 	}
-	factory, err := New(root, Cgroupfs)
+	factory, err := New(root, Cgroupfs, IntelRdtFs)
 	if err != nil {
 		t.Fatal(err)
 	}