Cpuset Management Utilty/shield writeup

From RTwiki
(Difference between revisions)
Jump to: navigation, search
m (Protected "Cpuset Management Utilty/shield writeup": This page has been migrated to the Linux Foundation RT wiki. (‎[edit=sysop] (indefinite) ‎[move=sysop] (indefinite)))
(moved to new dokuwiki)
 
Line 1: Line 1:
[[Cpuset Management Utility | Back up to cpuset page.]]
 
  
Version 1.5.0
+
<div style="margin:0; margin-top:10px; margin-right:10px; border:1px solid #dfdfdf; padding:0 1em 1em 1em; background-color:#f9e9e9; align:right;">
 
+
<b>This wiki is being migrated to the Linux Foundation Real-Time Linux Project hosted wiki. The new page is available at: https://wiki.linuxfoundation.org/realtime/documentation/howto/tools/cpu-partitioning/cset. This page is now deprecated.</b>
==Usage: <code>cset shield [options] [path/program]</code>==
+
</div>
 
+
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.  Note that 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=3
+
        On a 4-way machine, this command will dedicate the first
+
        3 processors, CPU0-CPU2, for the system set (unshielded)
+
        and only the last processor, 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.
+
 
+
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 however that 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.
+
 
+
The PIDSPEC argument taken for the --pid (or -p) option (used in
+
conjunction with a --shield or --unshield command) 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
+
        This command moves all processes and threads with PID or
+
        TID in the range 50-65 inclusive, from any cpuset they may
+
        be running in into the shielded user cpuset.
+
 
+
Note that 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 option is use with a
+
--pid and 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 -p.  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 that 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.
+
 
+
===Options:===
+
 
+
  -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 specified PIDSPEC of processes or threads
+
  -u, --unshield        remove specified PIDSPEC of processes or threads from
+
                        shield
+
  -p PIDSPEC, --pid=PIDSPEC
+
                        specify pid or tid specification for shield/unshield
+
  --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 affect 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
+
  -h, --help            show this help message and exit
+
 
+
----
+
[[Cpuset Management Utility | Back up to cpuset page.]]
+

Latest revision as of 10:03, 21 December 2017

This wiki is being migrated to the Linux Foundation Real-Time Linux Project hosted wiki. The new page is available at: https://wiki.linuxfoundation.org/realtime/documentation/howto/tools/cpu-partitioning/cset. This page is now deprecated.

Personal tools