Setting Up and Using the Adaptive partitioning Thread Scheduler

This chapter includes:

• Building an image
• Creating scheduler partitions
• Launching a process in a partition
• Viewing partition use

Building an image

To use the thread 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 Quickstart: Adaptive Partitioning Thread Scheduler chapter in this guide; for details, see Building Embedded Systems.

---

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

---

Creating scheduler partitions

On boot up, the system creates the initial partition, number 0, called System. The System partition initially has a budget of 100%. 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>. When you create a partition, its budget is subtracted from its parent partition's budget.

To see which partitions you've created, use the aps show command. For more information about the aps utility, see aps.

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%.

---

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 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 currently 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 thread 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. 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 option, the aps utility output results also shows you the critical budget usage over the longer windows.

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

For more information about the aps utility, see the Utilities Reference.