Cpuset Management Utilty/shield writeup

From RTwiki
(Difference between revisions)
Jump to: navigation, search
(New page: Back up to cpuset page. ==Usage: <code>cset shield [options] [path/program]</code>== This is a ''supercommand'' that creates basic cpu shielding. The norm...)
 
 
(10 intermediate revisions by 4 users not shown)
Line 1: Line 1:
[[Cpuset management utility | Back up to cpuset page.]]
+
[[Cpuset Management Utility | Back up to cpuset page.]]
 +
 
 +
Version 1.5.0
  
 
==Usage: <code>cset shield [options] [path/program]</code>==
 
==Usage: <code>cset shield [options] [path/program]</code>==
  
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.
+
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.
+
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.
+
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.
+
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.
+
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).
+
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:
 
For example:
    # cset shield --cpu=3
+
    # 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).
+
        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.
+
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.
+
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:
 
For example:
  
    # cset shield --sysset=free --userset=cage --cpu=2,3 --kthread=on
+
# 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.
+
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.
+
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 --shield (or -s) subcommand 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.
+
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:
 
For example:
 
 
     1,2,5              Means processes 1, 2 and 5
 
     1,2,5              Means processes 1, 2 and 5
 
     1,2,600-700        Means processes 1, 2 and from 600 to 700
 
     1,2,600-700        Means processes 1, 2 and from 600 to 700
  
     # cset shield --shield=50-65
+
     # 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.
  
The above 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.
  
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.
  
DANGER: Please note that there is no checking of processes you request to move into the shield with the --shield command. This means that the tool will happily move, for example, kernel threads that are bound to specific CPUs with this command. You can hang your system by indiscriminately specifying arbitrary PIDs to the --shield command so please be careful.
+
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.
  
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 also takes a PIDSPEC argument, the same as for the --shield subcommand.
+
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.
  
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 to these commands, then just that status is output. 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.
+
You can adjust which CPUs are in the shielded cpuset by issuing
 +
the --cpu subcommand again anytime after the shield has been
 +
initialized.
  
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.
+
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.
  
You can adjust which CPUs are in the shielded cpuset by issuing the --cpu subcommand again anytime after the shield has been initialized.
+
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.
  
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:
+
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.
  
    # cset shield --cpu=1,2,3
+
===Options:===
  
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, mem and proc) directly.
 
 
===Options:===
 
<code>
 
 
   -c CPUSPEC, --cpu=CPUSPEC
 
   -c CPUSPEC, --cpu=CPUSPEC
 
                         modifies or initializes the shield cpusets
 
                         modifies or initializes the shield cpusets
 
   -r, --reset          destroys the shield
 
   -r, --reset          destroys the shield
 
   -e, --exec            executes args in the shield
 
   -e, --exec            executes args in the shield
   --user=USER          use this USER to --run (id or name)
+
   --user=USER          use this USER for --exec (id or name)
   --group=GROUP        use this GROUP to --run (id or name)
+
   --group=GROUP        use this GROUP for --exec (id or name)
 
   -s, --shield          shield specified PIDSPEC of processes or threads
 
   -s, --shield          shield specified PIDSPEC of processes or threads
 
   -u, --unshield        remove specified PIDSPEC of processes or threads from
 
   -u, --unshield        remove specified PIDSPEC of processes or threads from
 
                         shield
 
                         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
 
   -k on|off, --kthread=on|off
                         shield from interrupt threads as well
+
                         shield from unbound interrupt threads as well
 
   -f, --force          force operation, use with care
 
   -f, --force          force operation, use with care
 
   -v, --verbose        prints more detailed output, additive
 
   -v, --verbose        prints more detailed output, additive
Line 82: Line 164:
 
   --userset=USERSET    optionally specify user cpuset name
 
   --userset=USERSET    optionally specify user cpuset name
 
   -h, --help            show this help message and exit
 
   -h, --help            show this help message and exit
</code>
+
 
 
----
 
----
[[Cpuset management utility | Back up to cpuset page.]]
+
[[Cpuset Management Utility | Back up to cpuset page.]]

Latest revision as of 19:40, 6 September 2011

Back up to cpuset page.

Version 1.5.0

[edit] Usage: cset shield [options] [path/program]

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.

[edit] 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

Back up to cpuset page.

Personal tools