Manage adaptive scheduler partitions
Syntax:
aps cmd [options] [arguments]
Options:
- cmd
- One of the following:
- create — create a partition
- join — make a process or thread join a partition
- modify — modify a partition or the scheduler
- show — display partition information
The options and arguments depend on the command.
Description:
Use the aps command to create, modify, and query
adaptive partitions from the command line, as well as to set the
averaging window, and the security and bankruptcy policies for the entire
system.
Note:
You can't include slashes (/) in a partition name.
To launch an application into a partition, use the -Xaps option to the
on
command.
The commands include:
- create [-B critical_budget] -b budget
[-m max_budget] [-P critical_priority]
[partition_name]
- Create a partition.
The options and arguments include:
- -B milliseconds — specify the critical CPU budget, in milliseconds.
The default is 0.
- -b budget — specify the CPU budget as a percentage.
The value can include decimal places.
- -m max_budget — specify the maximum CPU time, in percent, that
the partition may consume if it has no competition (i.e., freetime).
The value can include decimal places.
The -m option has an effect only if limit_cpu_usage is set (e.g.,
aps modify -S limit_cpu_usage).
- -P critical_priority — specify the critical priority for the partition.
Only threads at the critical priority or higher can use the critical budget.
- partition_name — the name of the new partition.
The name must not start with a digit or include any slashes,
and must be a maximum of 15 characters.
If you don't specify a name, the partition's ID is used as its name.
- join -p pid -t tid
partition_id | partition_name
- Make a process or thread join a partition.
The options and arguments include:
- -p pid — the process ID.
- -t tid — the thread ID.
- partition_id — the ID of the partition.
- partition_name — the name of the partition.
If both pid and tid are zero, the current shell joins the specified partition.
If tid is -1, the process with ID pid joins the partition.
This doesn't change the partitions that the process's threads are in;
it just sets the partition that the threads run in when they're handling a pulse.
- modify [-B critical_budget] [-b budget]
[-m max_budget] partition_id | partition_name
- Modify a partition.
The options and arguments include:
- -B milliseconds — specify the critical CPU budget, in milliseconds.
The default is 0.
- -b budget — specify the CPU budget as a percentage.
The value can include decimal places.
- -m max_budget — specify the maximum CPU time, in percent,
that the partition may consume if it has no competition (i.e., freetime).
The value can include decimal places.
The -m option has an effect only if limit_cpu_usage is set (e.g.,
aps modify -S limit_cpu_usage).
- partition_id — the ID of the partition.
- partition_name — the name of the partition.
The name must not start with a digit or include any slashes,
and must be a maximum of 15 characters.
- modify
[-S scheduling_policy...] [-s security_policy ...]
[-w windowsize_ms] [-y bankruptcy_policy ...]
- Modify the scheduler.
The options include:
- -S scheduling_policy … — specify the policies for the
adaptive partitioning scheduler.
Each scheduling_policy must be one of:
- normal
- freetime_by_ratio
- partition_local_priorities
- limit_cpu_usage
The default is normal.
For more information about the policies, see
Scheduling policies
in the entry for SchedCtl() in the
QNX Neutrino C Library Reference.
- -s security_policy … — specify the security policies to add to
the system.
Each security_policy must be one of:
- root0_overall
- root_makes_partitions
- sys_makes_partitions
- parent_modifies
- nonzero_budgets
- root_makes_critical
- sys_makes_critical
- root_joins
- sys_joins
- parent_joins
- join_self_only
- partitions_locked
- recommended
- flexible
- basic
- none
The default is none.
For more information about the policies, see the description of
SCHED_APS_ADD_SECURITY
in the entry for SchedCtl() in the
QNX Neutrino C Library Reference.
Note:
Once you've added a security policy, you can't remove it, except by
rebooting the system.
- -w windowsize_ms — set the size of the averaging window, in milliseconds, for the system.
You can set the window size to any value from 8 ms to 400 ms.
Note:
If you change the tick size of the system at runtime, do so before defining
the adaptive partitioning scheduler's window size.
That's because QNX Neutrino converts the window size from milliseconds to
clock ticks for internal use.
For more information, see
Choosing the window size
in the System Considerations chapter of the
Adaptive Partitioning User's Guide.
- -y bankruptcy_policy … — set the bankruptcy policy for the system to the specified items.
Each bankruptcy_policy must be one of:
- cancel_budget — set the offending partition's
critical budget to zero, which forces the
partition to be scheduled by its percentage CPU budget only.
This also means that a second bankruptcy can't occur.
- reboot — cause the system to crash with a brief
message identifying the offending partition.
This is the most severe response, suggested for use while
testing a product, to make sure bankruptcies are never ignored.
You probably shouldn't use this option in your finished product.
- basic — deliver bankruptcy-notification events and
make the partition out-of-budget for the rest of the scheduling window
(nominally 100 ms).
- none — do nothing.
The default is basic.
For more information about the policies, see
Handling bankruptcy
in the entry for SchedCtl() in the
QNX Neutrino C Library Reference.
- show [-d delay] [-f shorthand] [-l]
[-v...] [partition_name ...]
- Display information about the partitions.
The options and arguments include:
- -d delay — the delay period, in tenths of a second, when using the
-l option.
The default is 50.
- -f shorthand — display the information specified by
shorthand:
- all — all the below
- overall_stats — information about the last bankruptcy
- scheduler — parameters for the thread scheduler, including
the current security setting, bankruptcy policy, and the size of the
averaging window
- partitions — information about the partitions,
including their names, IDs, parent IDs, budgets, critical budgets,
and the process and thread IDs of the last thread to go bankrupt
- usage — the amount of budget and critical budget
that each partition is currently using
The default is usage.
- -l — (el) Loop mode; display the information at the interval
specified by the -d option.
- -v... — be verbose; display more information with the show command, especially with the
usage shorthand:
- -v — display the budget usage over the last averaging window
- -vv — display the budget usage and critical budget usage over the last averaging window
- partition_name — the name of the partition.
If you don't specify any partition names, aps displays information about all partitions.
Examples:
Create a partition called Drivers with a budget of 20%
and a critical budget of 5 milliseconds:
aps create -b 20 -B 5 Drivers
Change the Drivers partition's budget to 25% and its critical
budget to 7 milliseconds:
aps modify -b 25 -B 7 Drivers
Specify a bankruptcy policy of recommended and a
security policy of root_makes_partitions for the entire system:
aps modify -y recommended -s root_makes_partitions
Every 2 seconds, display the amount of the budget and critical budget that the partitions
are using:
aps show -l -d 20 -f usage
Since usage is the default shorthand for the -f option,
the above command is the same as:
aps show -l -d 20