[Previous] [Contents] [Index] [Next]

Caution: This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

Setting Up and Using the Adaptive Partitioning Scheduler

This chapter includes:

Building an image

In order to use the adaptive partitioning scheduler, you must add the [module=aps] attribute to the command that launches procnto in your OS image's buildfile. For example:

[module=aps] PATH=/proc/boot procnto -vv

Once you've added this line, use mkifs to rebuild your OS image, and then put the image in /.boot. For an example, see the A Quick Introduction to the Adaptive Partitioning Scheduler chapter in this guide; for details, see Building Embedded Systems.


Note: You don't need to recompile your applications in order to run them in partitions.

Creating partitions

On boot up, the system creates the initial partition, number 0, called System. The System partition initially has a budget of 100%. Subsequently created partitions take their budget from the System partition. You can create partitions and set their budgets in your buildfile, with command-line utilities, or dynamically through the API defined in <sys/sched_aps.h>.

To see which partitions you've created, use the aps show command.

In a buildfile

To create a partition in your buildfile, add a line like this to the startup script:

sched_aps name budget

You can also use the aps in your startup script to set security options. For example, to create a partition called Drivers with a CPU budget of 20% and then use our recommended security option, add these lines to your buildfile's startup script:

sched_aps Drivers 20
aps modify -s recommended

From the command line

To create a partition from the command line, use the aps utility's create option. For example:

aps create -b15 DebugReserve

creates a partition named DebugReserve with a budget of 15%.


Note: When you create a partition, its budget is taken from its parent partition's budget. The parent partition is usually the system partition.

From a program

To create a partition from a program, use the SCHED_APS_CREATE_PARTITION command to SchedCtl(). For example:

sched_aps_create_parms creation_data;

memset(&creation_data, 0, sizeof(creation_data));
creation_data.budget_percent = 15;
creation_data.critical_budget_ms = 0;
creation_data.name = "DebugReserve";

ret = SchedCtl( SCHED_APS_CREATE_PARTITION, &creation_data,
                sizeof(creation_data));
if (ret != EOK) {
   printf("Couldn't create partition \"%s\": %s (%d).\n",
            creation_data.name, strerror(errno), errno);
} else {
   printf ("The new partition's ID is %d.\n", creation_data.id);
}

Note that SchedCtl() puts the partition's ID in the sched_aps_create_parms structure.

Launching a process in a partition

You can use options in your buildfile to launch applications at boot time. In general, you need to launch only the command that starts up a multiprocess application, since child processes of your initial command -- including shells and commands run from those shells -- run in the same partition.

You can also launch a process into a partition at the command line. The interface defined in <sys/sched_aps.h> lets you launch individual threads into a partition and move already running threads into another partition.

In a buildfile

To launch a command into a partition, use the [sched_aps=partition_name] attribute in your buildfile's startup script. For example:

[+session pri=35 sched_aps=DebugReserve] ksh &

launches a high-priority shell into the DebugReserve partition.

The statements you use to start a command in a partition may appear anywhere in the startup script after you've created the partition.

From the command line

To launch a command into a partition, use the -Xaps=partition_name option of the on command. (The X refers to an external scheduler, the adaptive partitioning scheduler in this case.) For example:

on -Xaps=DebugReserve ksh

launches a shell into the DebugReserve partition.

From a program

To launch a program into a partition from a program, start the program (e.g by calling spawn()), and then use the SCHED_APS_JOIN_PARTITION command to SchedCtl() to make the program run in the appropriate partition. For example, this code makes the current process join a given partition:

sched_aps_join_parms join_data;

memset(&join_data, 0, sizeof(join_data));
join_data.id = partition_ID;
join_data.pid = 0;
join_data.tid = 0;

ret = SchedCtl( SCHED_APS_JOIN_PARTITION, &join_data,
                sizeof(join_data));
if (ret != EOK) {
   printf("Couldn't join partition %d: %s (%d).\n",
            join_data.id, strerror(errno), errno);
} else {
   printf ("Process is now in partition %d.\n", join_data.id);
}

Viewing partition use

The most common use of aps is to list the partitions and the CPU time they're using. In order to list partitions and the CPU time they're consuming, use the aps show command:

$ aps show
                    +---- CPU Time ----+-- Critical Time --
Partition name   id | Budget |    Used | Budget |      Used
--------------------+------------------+-------------------
System            0 |    60% |  36.24% |  100ms |   0.000ms
partitionA        1 |    20% |   2.11% |    0ms |   0.000ms
partitionB        2 |    20% |   1.98% |    0ms |   0.000ms
--------------------+------------------+-------------------
Total               |   100% |  40.33% |

To display CPU usage over the longer windows (typically 10 times and 100 times the length of the averaging window), add the -v option:

$ aps show -v
                    +----------- CPU Time ------------+-- Critical Time --
                    |        |           Used         |        |
Partition name   id | Budget | 0.100s   1.00s   10.0s | Budget |      Used
--------------------+---------------------------------+-------------------
System            0 |    60% | 20.91%   3.23%   4.33% |  100ms |   0.000ms
partitionA        1 |    20% |  1.78%   2.09%   2.09% |    0ms |   0.000ms
partitionB        2 |    20% |  1.71%   2.03%   2.03% |    0ms |   0.000ms
--------------------+---------------------------------+-------------------
Total               |   100% | 24.40%   7.34%   8.44% |

If you specify more than one v, aps also shows you the critical budget usage over the longer windows.

If you want to display the output of aps show every 5 seconds, use the aps show -l command. You can use the -d option to change the length of the delay.

For more information about aps, see the Utilities Reference.


[Previous] [Contents] [Index] [Next]