CSET-SHIELD(1) [FIXME: manual] CSET-SHIELD(1)NAMEcset-shield - cpuset supercommand which implements cpu shielding
SYNOPSIS
cset [cset options] shield [shield options] [args]
cset shield --help
cset shield
cset shield --cpu 1-7
cset shield --cpu 1-7 --kthread=on
cset shield --exec /opt/software/myapp/doit --my_opt1 --my_opt2
cset shield --user appuser --exec run_benchmark.sh
cset shield --shield --pid 1024,2048,5000-1000
cset shield --unshield --pid 6000-8500
cset shield --kthread=off
cset shield --kthread=on
cset shield --shield bash
OPTIONS-h, --help
prints the list of options for this command
-c CPUSPEC, --cpu=CPUSPEC
modifies or initializes the shield cpusets
-r, --reset
destroys the shield
-e, --exec
executes args in the shield
--user=USER
use this USER for --exec (id or name)
--group=GROUP
use this GROUP for --exec (id or name)
-s, --shield
shield PIDSPEC specified with -p/--pid of processes or threads
-u, --unshield
remove PIDSPEC specified with -p/--pid of processes or threads from
the shield, the tasks keep running in the unshielded cpuset
--threads
if specified, any processes found in the PIDSPEC to have multiple
threads will automatically have all their threads added to the
PIDSPEC (use to shield or unshield all related threads)
-k on|off, --kthread=on|off
shield from unbound interrupt threads as well
-f, --force
force operation, use with care
-v, --verbose
prints more detailed output, additive
--sysset=SYSSET
optionally specify system cpuset name
--userset=USERSET
optionally specify user cpuset name
DESCRIPTION
This is a supercommand that creates basic cpu shielding. The normal
cset commands can of course be used to create this basic shield, but
the shield command combines many such commands to create and manage a
common type of cpu shielding setup.
The concept of shielding implies at minimum three cpusets, for example:
root, user and system. The root cpuset always exists in all
implementations of cpusets and contains all available CPUs on the
machine. The system cpuset is so named because normal system tasks are
made to run on it. The user cpuset is so named because that is the
"shielded" cpuset on which you would run your tasks of interest.
Usually, CPU zero would be in the system set and the rest of the CPUs
would be in the user set. After creation of the cpusets, all processes
running in the root cpuset are moved to the system cpuset. Thus any new
processes or threads spawned from these processes will also run the
system cpuset.
If the optional --kthread=on option is given to the shield command,
then all kernel threads (with exception of the per-CPU bound interrupt
kernel threads) are also moved to the system set.
One executes processes on the shielded user cpuset with the --exec
subcommand or moves processes or threads to the shielded cpuset with
the --shield subcommand with a --pid option.
Note
You do not need to specify which cpuset a process or thread is
running in initially when using the --shield subcommand.
To create a shield, you would execute the shield command with the --cpu
option that specifies CPUSPEC argument that assigns CPUs to be under
the shield (this means assigned to the user cpuset, all other cpus will
be assigned to the system set).
For example:
# cset shield --cpu=1-3
On a 4-way machine, this command will dedicate the first processor,
CPU0, for the system set (unshielded) and the last three processors,
CPU1, CPU2, CPU3, for the user set (shielded).
The CPUSPEC will accept a comma separated list of CPUs and inclusive
range specifications. For example, --cpu=1,3,5-7 will assign CPU1,
CPU3, CPU5, CPU6, and CPU7 to the user (or shielded) cpuset and the
inverse of that to the system (or unshielded) cpuset.
If you do not like the names "system" and "user" for the unshielded and
shielded sets respectively, or if those names are used already, then
use the --sysset and --userset options.
For example:
# cset shield --sysset=free --userset=cage --cpu=2,3 --kthread=on
The above command will use the name "free" for the unshielded system
cpuset, the name "cage" for the shielded user cpuset, initialize these
cpusets and dedicate CPU0 and CPU1 to the "free" set and (on a 4-way
machine) dedicate CPU2 and CPU3 to the "cage" set. Further, the command
moves all processes and threads, including kernel threads from the root
cpuset to the "free" cpuset.
Note
If you do use the --syset/--userset options, then you must continue
to use those for every invocation of the shield supercommand.
After initialization, you can run the process of interest on the
shielded cpuset with the --exec subcommand, or move processes or
threads already running to the shielded cpuset with the --shield
subcommand and the --pid option.
Note that if your execed command takes options, then use the
traditional "--" marker to separate cset’s options from your command’s
options.
For example:
# cset shield --exec — ls -l
This command will execute "ls -l" inside the shield.
The PIDSPEC argument taken for the --pid (or -p) option is a comma
separated list of PIDs or TIDs. The list can also include brackets of
PIDs or TIDs that are inclusive of the endpoints.
For example:
1,2,5 Means processes 1, 2 and 5
1,2,600-700 Means processes 1, 2 and from 600 to 700
# cset shield --shield --pid=50-65
The above command moves all processes and threads with PID or TID in
the range 50-65 inclusive, from the system cpuset into the shielded
user cpuset. If they are running in the root cpuset, you must use the
--force option to actually move them into the shield.
Note
The range of PIDs or TIDs does not need to have every position
populated. In other words, for the example above, if there is only
one process, say PID 57, in the range of 50-65, then only that
process will be moved.
The --unshield (or -u) subcommand will remove the specified processes
or threads from the shielded cpuset and move them into the unshielded
(or system) cpuset. This command is also used in conjuction with a
-p/--pid option that specifies a PIDSPEC argument, the same as for the
--shield subcommand.
Both the --shield and the --unshield commands will also finally output
the number of tasks running in the shield and out of the shield if you
do not specify a PIDSPEC with --pid. By specifying also a --verbose in
addition, then you will get a listing of every task that is running in
either the shield or out of the shield.
Using no subcommand, ie. only "cset shield", will output the status of
both shield and non-shield. Tasks will be listed if --verbose is used.
You can adjust which CPUs are in the shielded cpuset by issuing the
--cpu subcommand again anytime after the shield has been initialized.
For example if the original shield contained CPU0 and CPU1 in the
system set and CPU2 and CPU3 in the user set, if you then issue the
following command:
# cset shield --cpu=1,2,3
then that command will move CPU1 into the shielded "user" cpuset. Any
processes or threads that were running on CPU1 that belonged to the
unshielded "system" cpuset are migrated to CPU0 by the system.
The --reset subcommand will in essence destroy the shield. For example,
if there was a shield on a 4-way machine with CPU0 in system and CPUs
1-3 in user with processes running on the user cpuset (i.e. in the
shield), and a --reset subcommand was issued, then all processes
running in both system and user cpusets would be migrated to the root
cpuset (which has access to all CPUs and never goes away), after which
both system and user cpusets would be destroyed.
Note
Even though you can mix general usage of cpusets with the shielding
concepts described here, you generally will not want to. For more
complex shielding or usage scenarios, one would generally use the
normal cpuset commands (i.e. cset set and proc) directly.
LICENSE
Cpuset is licensed under the GNU GPL V2 only.
COPYRIGHT
Copyright (c) 2008-2010 Novell Inc.
AUTHOR
Written by Alex Tsariounov <alext@novell.com>.
SEE ALSOcset(1), cset-set(1), cset-proc(1)
/usr/share/doc/packages/cpuset/html/tutorial.html
taskset(1), chrt(1)
/usr/src/linux/Documentation/cpusets.txt
[FIXME: source] 02/11/2010 CSET-SHIELD(1)
