[ANNOUNCE] resctrltool: command line tool to manage CAT reservations from userspace

[Marcelo Tosatti]

Hello,

Reviews, comments and questions are appreciated on this python
script, called resctrltool.py, a utility to manage CAT reservations
from the command line.

Why: There are two main reasons for writing this tool, they are:

1) The kernel resctrlfs filesystem format is not functional for being
maintained in userspace, since its machine dependant (number of bits in
cbm mask changes with L3 size) and dependent on the other allocations
registered in resctrlfs.

Users want to specify their reservations in bytes, and
not care about position of mask for the reservation.

So the tool performs the translation


    kbytes,                         cbm mask to use for
    type,                   --->    each cacheid
    cacheid specification

2) Since each application, such as libvirt, would
have to reimplement the translation above, i decided
to write a command line interface. Support
for systemd being written, which uses this tool.

The tarball can be found at http://people.redhat.com/~mtosatti/resctrltool/


USAGE EXAMPLES

$ ./resctrltool.py 
Command: list
=============

list lists the reservations in place
syntax: resctrltool list [--all-tasks] [--pid-to-name]
options:
--all-tasks: by default list truncates the list of the tasks for a given
reservation, this option disables the truncation
--pid-to-name perform pid to name convertion when listing tasks

Command: create
===============

create creates a new reservation
syntax: resctrltool create --name name --size size --type
{both,data,cache} [--cache-id=ID]
options:
--name: name of the reservation to be created, directory name on
resctrlfs filesystem
--size size: size of reservation in Kbytes
There are two types of reservations: global ones
(which apply to all cacheid's), and local ones (when
--cache-id is specified).
The required order for local ones is as follows:
--type {both,data,code} --size size --cache-id id
That is, --cache-id refers to the size and type options which precede
it.
The required order for global ones is as follows:

Automatic filling for --cache-id:
---------------------------------
When --cache-id is not specified for all cacheid's in
the system, the not specified ones are set to the default group mask

Conversion of types
-------------------
When the machine supports CDP, and the user specification
has type=both, or when the machine does not support CDP,
and the user specification has type=code or type=data
the following convertions are performed:
-------------------------------------------------------
USER_SPECIFICATION    AVAILABLE HW      BEHAVIOUR
-------------------------------------------------------
both                   code/data        code/data regions
                                        using same addresses
-------------------------------------------------------
code/data               both            code+data region with size
                                        equals to codesize+datasize
-------------------------------------------------------

Command: assign
===============

assign pid to reservation name
syntax: resctrltool assign pid name

Command: delete
===============

delete deletes a reservation (removes resctrlfs directory), and updates
the default reservation
syntax: resctrltool delete name

Command: list-cache-ids
=======================

list-cache-ids lists the cache-id -> socket mapping
syntax: resctrltool list-cache-ids

Command: help
=============

help prints help for a particular command
syntax: resctrltool help command

$ ./resctrltool.py  list
=============================
Name: default
Cpus: 000000
Tasks: 1,2,3,5,6,8,9,10,11,12,13,14,15,16,17,18,19,20,21,23,24,25,2 ...
CacheID-0: 6144 KiB (40.000000 %) (ff000) (code and data)
CacheID-1: 6144 KiB (40.000000 %) (ff000) (code and data)
=============================
Name: res1
Cpus: 000000
Tasks: 
CacheID-0: 3072 KiB (20.000000 %) (f) (code and data)
CacheID-1: 3072 KiB (20.000000 %) (f) (code and data)
====== additional info =======
free mask for cache-id 0 is ffff0 (total 12288 KiB)
free mask for cache-id 1 is ffff0 (total 12288 KiB)

$ ./resctrltool.py create --type both --size 1mb --name httpd
$ ./resctrltool.py  list 
=============================
Name: default
Cpus: 000000
Tasks: 1,2,3,5,6,8,9,10,11,12,13,14,15,16,17,18,19,20,21,23,24,25,2 ...
CacheID-0: 10752 KiB (70.000000 %) (fffc0) (code and data)
CacheID-1: 10752 KiB (70.000000 %) (fffc0) (code and data)
=============================
Name: httpd
Cpus: 
Tasks: 
CacheID-0: 1536 KiB (10.000000 %) (30) (code and data)
CacheID-1: 1536 KiB (10.000000 %) (30) (code and data)
=============================
Name: res1
Cpus: 000000
Tasks: 
CacheID-0: 3072 KiB (20.000000 %) (f) (code and data)
CacheID-1: 3072 KiB (20.000000 %) (f) (code and data)
====== additional info =======
free mask for cache-id 0 is fffc0 (total 10752 KiB)
free mask for cache-id 1 is fffc0 (total 10752 KiB)