SchedCtl(), SchedCtl_r()

QNX SDP8.0C Library ReferenceAPIDeveloper

Control the scheduler

Synopsis:

#include <sys/neutrino.h>

int SchedCtl( int cmd,
              void *data,
              size_t length);

int SchedCtl_r( int cmd,
                void *data,
                size_t length);

Arguments:

cmd
The control command that you want to execute; one of:
  • SCHED_PROCESSOR_ONLINE — Mark a CPU as online.
  • SCHED_PROCESSOR_OFFLINE — Mark a CPU as offline.
  • SCHED_PROCESSORS_STATUS — Query the number of present CPUs and their status; either offline or online.
data
A pointer to the specific data structure for the command.
length
The size of the structure that data points to.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The SchedCtl() and SchedCtl_r() kernel calls control the scheduler. These functions are identical except in the way they indicate errors; refer to the Returns section for details.

When you call SchedCtl() with the SCHED_PROCESSOR_OFFLINE command, the kernel considers the CPU unavailable for scheduling. The call drains all pending IPI actions and ensures that no new IPIs can be sent to the processor. The thread should then disable interrupts and proceed to execute the code.

Once the thread restores the state of the processor, it notifies the kernel using SchedCtl() with the SCHED_PROCESSOR_ONLINE command. This call causes the kernel to resume normal scheduling on the processor. The following image summarizes the sequence of processor offlining and onlining:
Figure 1Basic sequence of processor offlining and onlining


For more information on CPU offlining, refer to the CPU offlining section in the System Architecture guide.

Returns:

The difference between these functions is how they indicate errors:
SchedCtl()
0 if the call succeeds. If an error occurs, SchedCtl() returns -1 and sets errno.
SchedCtl_r()
EOK is returned on success. This function does NOT set errno. If an error occurs, any of the error codes listed in the command descriptions above may be returned.

Classification:

QNX OS

Safety:
Cancellation point No
Signal handler Yes
Thread Yes

Examples:

The following code snippet shows how to query the status of your CPUs:
struct _sched_processors_status proc_status;
int const rc = SchedCtl(SCHED_PROCESSORS_STATUS,
                        &proc_status, sizeof(proc_status));
assert(rc == EOK);
printf("configured: %u, online: %u (bitmask: %lx)\n",
     proc_status.num_processors, proc_status.num_processors_online,
     proc_status.processors_online[0]);
On a 4-CPU system, the example above might output the following, where CPU 0 and 3 are online and CPU 1 and 2 are offline: 
configured: 4, online: 2 (bitmask: 9)
Page updated: