Loading...
Searching...
No Matches
Scheduler
Base API » Kernel Objects

C interface of the Scheduler kernel object, see L4::Scheduler for the C++ interface. More...

Collaboration diagram for Scheduler:

## Data Structures

struct | l4_sched_cpu_set_t
| CPU sets. More...
struct | l4_sched_param_t
| Scheduler parameter set. More...

## Typedefs

typedef struct l4_sched_cpu_set_t | l4_sched_cpu_set_t
| CPU sets.
typedef struct l4_sched_param_t | l4_sched_param_t
| Scheduler parameter set.

## Enumerations

enum | L4_scheduler_classes { L4_SCHEDULER_CLASS_FIXED_PRIO = 1UL << 1 , L4_SCHEDULER_CLASS_WFQ = 1UL << 2 }
| Supported scheduler classes. More...
enum | L4_scheduler_ops { L4_SCHEDULER_INFO_OP = 0UL , L4_SCHEDULER_RUN_THREAD_OP = 1UL , L4_SCHEDULER_IDLE_TIME_OP = 2UL }
| Operations on the Scheduler object. More...

## Functions

l4_sched_cpu_set_t | l4_sched_cpu_set (l4_umword_t offset, unsigned char granularity, l4_umword_t map=1) L4_NOTHROW
l4_msgtag_t | l4_scheduler_info (l4_cap_idx_t scheduler, l4_umword_t *cpu_max, l4_sched_cpu_set_t *cpus) L4_NOTHROW))
| Get scheduler information.
l4_msgtag_t | l4_scheduler_info_with_classes (l4_cap_idx_t scheduler, l4_umword_t *cpu_max, l4_sched_cpu_set_t *cpus, l4_umword_t *sched_classes) L4_NOTHROW))
| Get scheduler information.
l4_sched_param_t | l4_sched_param (unsigned prio, l4_umword_t quantum=0) L4_NOTHROW
| Construct scheduler parameter.
l4_msgtag_t | l4_scheduler_run_thread (l4_cap_idx_t scheduler, l4_cap_idx_t thread, l4_sched_param_t const *sp) L4_NOTHROW)
| Run a thread on a Scheduler.
l4_msgtag_t | l4_scheduler_idle_time (l4_cap_idx_t scheduler, l4_sched_cpu_set_t const *cpus, l4_kernel_clock_t *us) L4_NOTHROW)
| Query the idle time (in µs) of a CPU.
int | l4_scheduler_is_online (l4_cap_idx_t scheduler, l4_umword_t cpu) L4_NOTHROW
| Query if a CPU is online.

## Detailed Description

C interface of the Scheduler kernel object, see L4::Scheduler for the C++ interface.

The Scheduler interface allows a client to manage CPU resources. The API provides functions to query scheduler information, check the online state of CPUs, query CPU idle time and to start threads on defined CPU sets.

The scheduler offers a virtual device IRQ which triggers when the number of online cores changes, e.g. due to hotplug events. In contrast to hardware IRQs, this IRQ implements a limited functionality:

- Only IRQ line 0 is supported, no MSI vectors.
- The IRQ is edge-triggered and the IRQ mode cannot be changed.
- As the IRQ is edge-triggered, it does not have to be explicitly unmasked.

It depends on the platform, which hotplug events actually trigger the IRQ. Many platforms only support triggering the IRQ when a CPU core different from the boot CPU goes online.

Include File
  #include <l4/sys/scheduler.h>
  scheduler.h
  Scheduler object functions.

## Enumeration Type Documentation

## L4_scheduler_classes

enum L4_scheduler_classes

Supported scheduler classes.

Enumerator
L4_SCHEDULER_CLASS_FIXED_PRIO | Fixed-priority scheduler.
L4_SCHEDULER_CLASS_WFQ | Weighted fair queuing scheduler.

Definition at line 46 of file scheduler.h.

## L4_scheduler_ops

enum L4_scheduler_ops

Operations on the Scheduler object.

Enumerator
L4_SCHEDULER_INFO_OP | Query infos about the scheduler.
L4_SCHEDULER_RUN_THREAD_OP | Run a thread on this scheduler.
L4_SCHEDULER_IDLE_TIME_OP | Query idle time for the scheduler.

Definition at line 269 of file scheduler.h.

## Function Documentation

## l4_sched_cpu_set()

l4_sched_cpu_set_t l4_sched_cpu_set | ( | l4_umword_t | offset,
|  | unsigned char | granularity,
|  | l4_umword_t | map = 1 )

inline

Parameters

  offset | Offset. Must be a multiple of 2^granularity.
  granularity | Granularity in log2 notation.
  map | Bitmap of CPUs, defaults to 1 in C++.

Returns
  CPU set.

Examples
  examples/sys/migrate/thread_migrate.cc.

Definition at line 279 of file scheduler.h.

References l4_sched_cpu_set_t::gran_offset, L4_NOTHROW, and l4_sched_cpu_set_t::map.

Referenced by l4_sched_param().

Here is the caller graph for this function:

## l4_sched_param()

l4_sched_param_t l4_sched_param | ( | unsigned | prio,
|  | l4_umword_t | quantum = 0 )

inline

Construct scheduler parameter.

Parameters

  prio | Thread priority (1-255).
  quantum | Timeslice in micro seconds.

The l4_sched_param_t::affinity of the returned value contains all CPUs.

Examples
  examples/sys/aliens/main.c, examples/sys/migrate/thread_migrate.cc, examples/sys/singlestep/main.c, examples/sys/start-with-exc/main.c, and examples/sys/utcb-ipc/main.c.

Definition at line 289 of file scheduler.h.

References l4_sched_param_t::affinity, L4_NOTHROW, l4_sched_cpu_set(), l4_sched_param_t::prio, and l4_sched_param_t::quantum.

Here is the call graph for this function:

## l4_scheduler_idle_time()

l4_msgtag_t l4_scheduler_idle_time | ( | l4_cap_idx_t | scheduler,
|  | l4_sched_cpu_set_t const * | cpus,
|  | l4_kernel_clock_t * | us )

inline

Query the idle time (in µs) of a CPU.

Parameters

  | scheduler | Scheduler object.
  | cpus | Set of CPUs to query. Only the idle time of the first selected CPU in cpus.map is queried.
  [out] | us | Idle time of queried CPU in µs.

Return values

  0 | Success.
  -L4_EINVAL | Invalid CPU requested in cpu set.

This function retrieves the idle time in µs of the first selected CPU in cpus.map. The idle time is the accumulated time a CPU has spent in the idle thread since its last reset. To calculate a load estimate l one has to retrieve the idle time at the beginning (i1) and the end (i2) of a known time interval t. The load is then calculated as l = 1 - (i2 - i1)/t.

The idle time is only defined for online CPUs. Reading the idle time from offline CPUs is undefined and may result in either getting -L4_EINVAL or calculating an estimated (incorrect) load of 1.

Note
  The idle time statistics of remote CPUs is updated on context switch events only, hence may not be up-to-date when requested cross-CPU. To get up-to-date idle time you should use a thread running on the same CPU of which the idle time is requested.

Definition at line 403 of file scheduler.h.

References L4_NOTHROW, and l4_utcb().

Here is the call graph for this function:

## l4_scheduler_info()

l4_msgtag_t l4_scheduler_info | ( | l4_cap_idx_t | scheduler,
|  | l4_umword_t * | cpu_max,
|  | l4_sched_cpu_set_t * | cpus )

inline

Get scheduler information.

Parameters

  | scheduler | Scheduler object.
  [out] | cpu_max | Maximum number of CPUs ever available. Optional, can be NULL.
  [in,out] | cpus | cpus.offset is first CPU of interest. cpus.granularity (see l4_sched_cpu_set_t). cpus.map Bitmap of online CPUs. Must not be NULL.

Return values

  0 | Success.
  -L4_ERANGE | The given CPU offset is larger than the maximum number of CPUs.

Definition at line 381 of file scheduler.h.

References L4_NOTHROW, and l4_utcb().

Here is the call graph for this function:

## l4_scheduler_info_with_classes()

l4_msgtag_t l4_scheduler_info_with_classes | ( | l4_cap_idx_t | scheduler,
|  | l4_umword_t * | cpu_max,
|  | l4_sched_cpu_set_t * | cpus,
|  | l4_umword_t * | sched_classes )

inline

Get scheduler information.

Parameters

  | scheduler | Scheduler object.
  [out] | cpu_max | Maximum number of CPUs ever available. Optional, can be NULL.
  [in,out] | cpus | cpus.offset is first CPU of interest. cpus.granularity (see l4_sched_cpu_set_t). cpus.map Bitmap of online CPUs. Must not be NULL.
  [out] | sched_classes | A bitmap of available scheduling classes (see L4_scheduler_classes). Optional, can be NULL.

Return values

  0 | Success.
  -L4_ERANGE | The given CPU offset is larger than the maximum number of CPUs.

This function delivers the same information as l4_scheduler_info plus the available scheduler classes (see L4_scheduler_classes).

Definition at line 388 of file scheduler.h.

References L4_NOTHROW, and l4_utcb().

Here is the call graph for this function:

## l4_scheduler_is_online()

int l4_scheduler_is_online | ( | l4_cap_idx_t | scheduler,
|  | l4_umword_t | cpu )

inline

Query if a CPU is online.

Parameters

  scheduler | Scheduler object.
  cpu | CPU number whose online status should be queried.

Return values

  true | The CPU is online.
  false | The CPU is offline

Definition at line 410 of file scheduler.h.

References L4_NOTHROW, and l4_utcb().

Here is the call graph for this function:

## l4_scheduler_run_thread()

l4_msgtag_t l4_scheduler_run_thread | ( | l4_cap_idx_t | scheduler,
|  | l4_cap_idx_t | thread,
|  | l4_sched_param_t const * | sp )

inline

Run a thread on a Scheduler.

Parameters

  scheduler | Scheduler object.
  thread | Capability of the thread to run.
  sp | Scheduling parameters.

Return values

  0 | Success.
  -L4_EINVAL | Invalid size of the scheduling parameter.

This function launches a thread on a CPU determined by the scheduling parameter sp.affinity. A thread can be intentionally stopped by migrating it on an offline or an invalid CPU. The thread is only guaranteed to run if the CPU it is migrated to is currently online.

Note
  If the target CPU is currently not online, there is no guarantee that the thread will ever run, even if the CPU comes online later on.
  A scheduler may impose a policy with regard to selecting CPUs. However the scheduler is required to ensure the following two properties:
  - Two threads with disjoint CPU sets must be scheduled to different CPUs.
  - Two threads with identical CPU sets selecting only a single CPU must be scheduled to the same CPU.

Examples
  examples/sys/aliens/main.c, examples/sys/singlestep/main.c, examples/sys/start-with-exc/main.c, and examples/sys/utcb-ipc/main.c.

Definition at line 396 of file scheduler.h.

References L4_NOTHROW, and l4_utcb().

Here is the call graph for this function: