L4Re - L4 Runtime Environment

C interface of the Scheduler kernel object. 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_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. More...
 
l4_sched_param_t l4_sched_param (unsigned prio, l4_cpu_time_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. More...
 
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. More...
 
int l4_scheduler_is_online (l4_cap_idx_t scheduler, l4_umword_t cpu) L4_NOTHROW
 Query if a CPU is online. More...
 

Detailed Description

C interface of the Scheduler kernel object.

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.

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

Enumeration Type Documentation

◆ 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 200 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
offsetOffset.
granularityGranularitry in log2 notation.
mapBitmap of CPUs, defaults to 1 in C++.
Returns
CPU set.
Examples:
examples/sys/migrate/thread_migrate.cc.

Definition at line 210 of file scheduler.h.

References l4_sched_cpu_set_t::gran_offset, l4_sched_cpu_set_t::granularity(), l4_sched_cpu_set_t::map, and l4_sched_cpu_set_t::offset().

Referenced by l4_sched_param(), and l4_sched_cpu_set_t::set().

+ Here is the call graph for this function:
+ Here is the caller 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
schedulerScheduler object.
cpusSet of CPUs to query. Only the idle time of the first selected CPU in cpus.map is queried.
[out]usIdle time of queried CPU in µs.
Return values
0Success.
-L4_EINVALInvalid 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 322 of file scheduler.h.

◆ 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
schedulerScheduler object.
[out]cpu_maxMaximum number of CPUs ever available.
[in,out]cpuscpus.offset is first CPU of interest. cpus.granularity (see l4_sched_cpu_set_t). cpus.map Bitmap of online CPUs.
Return values
0Success.
-L4_EINVALThe given CPU offset is larger than the maximum number of CPUs.

Definition at line 308 of file scheduler.h.

◆ 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
schedulerScheduler object.
cpuCPU number whose online status should be queried.
Return values
trueThe CPU is online.
falseThe CPU is offline

Definition at line 329 of file scheduler.h.

◆ 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
schedulerScheduler object.
threadCapability of the thread to run.
spScheduling parameters.
Return values
0Success.
-L4_EINVALInvalid 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
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 physical CPUs.
  • Two threads with a single identical CPU selected in the CPU set must be scheduled to the same physical 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 315 of file scheduler.h.