NAME

       rtdset - Task CPU affinity and Intel(R) Resource Director Technology/AMD PQoS control tool

SYNOPSIS

       rdtset -t <feature=value;...cpu=cpulist>... -c <cpulist> [-I] (-p <pidlist> | [-k] cmd [<args>...])
       rdtset  -r  <cpulist>  -t  <feature=value;...cpu=cpulist>...  -c  <cpulist> [-I] (-p <pidlist> | [-k] cmd
       [<args>...])
       rdtset -r <cpulist> -c <cpulist> (-p <pidlist> | [-k] cmd [<args>...])
       rdtset -r <cpulist> -t <feature=value;...cpu=cpulist>... [-I] -p <pidlist>
       rdtset -t <feature=value> -I [-c <cpulist>] (-p <pidlist> | [-k] cmd [<args>...])

DESCRIPTION

       For more details on Intel(R) Resource Director Technology see
       http://www.intel.com/content/www/us/en/architecture-and-technology/resource-director-technology.html
       or https://github.com/intel/intel-cmt-cat/wiki

       The rdtset tool provides support to set up the CAT (Cache Allocation Technology), MBA  (Memory  Bandwidth
       Allocation) and SMBA (Slow Memory Bandwidth Allocation) capabilities for a task and set its CPU affinity.
       For  MBA, rdtset offers two modes of operation, fixed MBA rate or closed-loop one monitoring local memory
       B/W usage and adjust MBA accordingly.  For OS interface,  it  uses  MBA  CTRL  via  libpqos  (OS  support
       available  in  Linux kernel 4.18 or later).  For MSRs, the tool adjusts MBA configuration by itself based
       on local memory B/W.  Intel(R) RDT/AMD PQoS allocation operations of the utility  are  done  via  libpqos
       library.  Class  of  service  0  (CLOS0) is assumed as default one. In command mode, rdtset forks and one
       process executes the command. Another process waits for  the  task  to  terminate  and  restores  default
       allocation state by assigning cpu's back to CLOS0.  This behavior is not in place in PID mode.

OPTIONS

       rdtset options are as follow:

       -h, --help
              Show help

       -v, --verbose
              Verbose mode

       -I, --iface-os
              Set  the  library  to  use  the kernel implementation. If not set the default implementation is to
              detect the interface automatically (MSR or kernel).

       -F <interface>, --iface <interface>
              Set the library interface to automatically detected one ('auto'), MSR ('msr') or kernel  interface
              ('os').
              <interface> can be set to either 'auto' (default), 'msr' or 'os'.
              If automatic detection is selected ('auto'), it:
              1) Takes RDT_IFACE environment variable into account if this variable is set
              2) Selects OS interface if the kernel interface is supported
              3) Selects MSR interface otherwise

       -t --rdt feature=value;...cpu=cpulist
              Specify  Intel(R)  RDT  configuration,  single  class  configuration  per  -t, multiple -t options
              allowed.
              Accepted values for features:
              2, l2 for level 2 cache
              3, l3 for level 3 cache
              m, mba for MBA
              s, smba for SMBA
              b, mba_max for max allowable local memory bandwidth

              For example:

              -t 'l3=0xf;cpu=1'
              CPU 1 uses four L3 cache-ways (mask 0xf)

              -t 'l3=0xf;cpu=2' -t 'l3=0xf0;cpu=3,4,5'
              CPU 2 uses four L3 cache-ways (mask 0xf), CPUs 3-5 share four L3 cache-ways (mask 0xf0), L3 cache-
              ways used by CPU 2 and 3-5 are non-overlapping

              -t 'l3=0xf;cpu=0-2' -t 'l3=0xf0;cpu=3,4,5'
              CPUs 0-2 share four L3 cache-ways (mask 0xf), CPUs 3-5 share four L3 cache-ways  (mask  0xf0),  L3
              cache-ways used by CPUs 0-2 and 3-5 are non-overlapping

              -t 'l3=0xf,0xf0;cpu=1'
              On CDP enabled system, CPU 1 uses four cache-ways for code (mask 0xf) and four cache-ways for data
              (mask 0xf0), data and code cache-ways are non-overlapping

              -t 'mba=70;cpu=0-2'
              CPUs 0-2 can utilize up to 70% of available memory bandwidth

              -t 'smba=64;cpu=0-2'
              CPUs 0-2 can utilize up to 64 units of available slow memory bandwidth

              -t 'mba=50;l3=0xf;cpu=1'
              CPU 1 uses four L3 (mask 0xf) cache-ways and can utilize up to 50% of available memory bandwidth

              -t 'mba_max=2000;cpu=1-2' Use SW controller to limit local memory B/W on cores 1-2 to 2000MBps (SW
              controller uses MBL monitoring and adjust MBA rate).

              Example PID type allocation configuration (requires -I option):

              -t 'l3=0xf'
              Allocate four L3 (mask 0xf) cache-ways to specified PIDs (-p option) or command

              -t 'l3=0xf;cpu=1;l3=0x1'
              CPU 1 uses four L3 (mask 0xf) cache-ways
              Specified PIDs (-p option) or command uses one L3 (mask 0x1) cache-way

       -c <cpulist>, --cpu <cpulist>
              Specify  CPU  affinity configuration, a numerical list of processors. The numbers are separated by
              commas and may include ranges. For example: 1-3,4,5.

       -p <pidlist>, --pid <pidlist>
              Operate on existing PIDs

       -r <cpulist>, --reset <cpulist>
              Reset allocation for CPUs (assign COS#0 to listed CPUs)
              For example:

              -r 0-5
              Reset allocation for CPUs 0-5

              -r 0-5 -t 'l3=0xf0;cpu=0-5' -c 0-5 -p $BASHPID
              Reconfigure allocation for CPUs 0-5
              In order to reconfigure allocation, it is needed to reset current configuration

       -k, --sudokeep
              Do not drop sudo elevated privileges

NOTES

       If kernel interface is not selected neither manually (e.g. --iface=msr) nor automatically,  CAT  and  MBA
       are  configured using Model Specific Registers (MSRs) to set up the class of service masks and manage the
       association of the cores/logical threads to a class of service.  The rdtset  software  executes  in  user
       space, and access to the MSRs is obtained through a standard Linux*/FreeBSD* interface.  Under Linux, the
       virtual file system structure /dev/cpu/CPUNUM/msr provides an interface to read and write the MSRs, under
       FreeBSD  it  is  /dev/cpuctlCPUNUM.   The  msr/cpuctl  file  interface  is  protected  and  requires root
       privileges. The msr/cpuctl driver might not be auto-loaded and on some modular  kernels  the  driver  may
       need to be loaded manually:

       Under Linux:
       sudo modprobe msr

       Under FreeBSD:
       sudo kldload cpuctl

       Interface enforcement:
       If  you  require  system  wide interface enforcement you can do so by setting the "RDT_IFACE" environment
       variable.

       OS interface (--iface-os, -I)
       With --iface-os (-I) parameter, rdtset uses resctrl filesystem  (/sys/fs/resctrl)  instead  of  accessing
       MSRs directly.

SEE ALSO

       msr(4)

AUTHOR

       rdtset   was   written   by   Wojciech   Andralojc   <wojciechx.andralojc@intel.com>,   Tomasz   Kantecki
       <tomasz.kantecki@intel.com>,   Michal    Aleksinski    <michalx.aleksinski@intel.com>,    Marcel    Cornu
       <marcel.d.cornu@intel.com>

       This  is  free  software;  see  the  source  for  copying  conditions. There is NO warranty; not even for
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

                                                January 10, 2019                                       RDTSET(8)