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

#include <scheduler>

Inheritance diagram for L4::Scheduler:

Collaboration diagram for L4::Scheduler:

Public Member Functions
l4_msgtag_t	info (l4_umword_t cpu_max, l4_sched_cpu_set_t cpus, l4_umword_t sched_classes=nullptr, l4_utcb_t utcb=l4_utcb()) const noexcept
	Get scheduler information.

l4_msgtag_t	run_thread (Ipc::Cap< Thread > thread, l4_sched_param_t const &sp)
	Run a thread on a Scheduler.

l4_msgtag_t	idle_time (l4_sched_cpu_set_t const &cpus, l4_kernel_clock_t *us)
	Query the idle time (in µs) of a CPU.

bool	is_online (l4_umword_t cpu, l4_utcb_t *utcb=l4_utcb()) const noexcept
	Query if a CPU is online.

Public Member Functions inherited from L4::Icu
l4_msgtag_t	bind (unsigned irqnum, L4::Cap< Triggerable > irq, l4_utcb_t *utcb=l4_utcb()) noexcept
	Bind an interrupt line of an interrupt controller to an interrupt object.

l4_msgtag_t	unbind (unsigned irqnum, L4::Cap< Triggerable > irq, l4_utcb_t *utcb=l4_utcb()) noexcept
	Remove binding of an interrupt line from the interrupt controller object.

l4_msgtag_t	info (l4_icu_info_t info, l4_utcb_t utcb=l4_utcb()) noexcept
	Get information about the ICU features.

l4_msgtag_t	msi_info (l4_umword_t irqnum, l4_uint64_t source, l4_icu_msi_info_t *msi_info)
	Get MSI info about IRQ.

l4_msgtag_t	mask (unsigned irqnum, l4_umword_t label=0, l4_timeout_t to=L4_IPC_NEVER, l4_utcb_t utcb=l4_utcb()) noexcept
	Mask an IRQ line.

l4_msgtag_t	set_mode (unsigned irqnum, l4_umword_t mode, l4_utcb_t *utcb=l4_utcb()) noexcept
	Set interrupt mode.

Public Member Functions inherited from L4::Irq_eoi
l4_msgtag_t	unmask (unsigned irqnum, l4_umword_t label=0, l4_timeout_t to=L4_IPC_NEVER, l4_utcb_t utcb=l4_utcb()) noexcept
	Unmask the given interrupt line.

Additional Inherited Members
Protected Types inherited from L4::Kobject_t< Scheduler, Icu, L4_PROTO_SCHEDULER, Type_info::Demand_t< 1 > >
typedef Scheduler	Class
	The target interface type (inheriting from Kobject_t)

typedef Typeid::Iface< PROTO, Scheduler >	__Iface
	The interface description for the derived class.

typedef Typeid::Merge_list< Typeid::Iface_list< __Iface >, typename Base::__Iface_list >	__Iface_list
	The list of all RPC interfaces provided directly or through inheritance.

Protected Types inherited from L4::Kobject_t< Icu, Irq_eoi, L4_PROTO_IRQ, Type_info::Demand_t< 1 > >
typedef Icu	Class
	The target interface type (inheriting from Kobject_t)

typedef Typeid::Iface< PROTO, Icu >	__Iface
	The interface description for the derived class.

typedef Typeid::Merge_list< Typeid::Iface_list< __Iface >, typename Base::__Iface_list >	__Iface_list
	The list of all RPC interfaces provided directly or through inheritance.

Protected Member Functions inherited from L4::Kobject_t< Scheduler, Icu, L4_PROTO_SCHEDULER, Type_info::Demand_t< 1 > >
L4::Cap< Class >	c () const noexcept
	Get the capability to ourselves.

Protected Member Functions inherited from L4::Kobject_t< Icu, Irq_eoi, L4_PROTO_IRQ, Type_info::Demand_t< 1 > >
L4::Cap< Class >	c () const noexcept
	Get the capability to ourselves.

Static Protected Member Functions inherited from L4::Kobject_t< Scheduler, Icu, L4_PROTO_SCHEDULER, Type_info::Demand_t< 1 > >
static void	__check_protocols__ () noexcept
	Helper to check for protocol conflicts.

Static Protected Member Functions inherited from L4::Kobject_t< Icu, Irq_eoi, L4_PROTO_IRQ, Type_info::Demand_t< 1 > >
static void	__check_protocols__ () noexcept
	Helper to check for protocol conflicts.

Detailed Description

C++ interface of the Scheduler kernel object, see 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 IRQ number 0, which triggers when the number of online cores changes, e.g. due to hotplug events.

The Scheduler interface inherits from L4::Icu and L4::Irq_eoi for managing the scheduler virtual device IRQ which, in contrast to hardware IRQs, 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>

scheduler
Scheduler object functions.

Definition at line 57 of file scheduler.

Member Function Documentation

◆ idle_time()

l4_msgtag_t L4::Scheduler::idle_time	(	l4_sched_cpu_set_t const &	cpus,
		l4_kernel_clock_t *	us
	)

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

Parameters

	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.

◆ info()

l4_msgtag_t L4::Scheduler::info	(	l4_umword_t *	cpu_max,
		l4_sched_cpu_set_t *	cpus,
		l4_umword_t *	sched_classes = `nullptr`,
		l4_utcb_t *	utcb = `l4_utcb()`
	)		const

inlinenoexcept

Get scheduler information.

Parameters

[out]	cpu_max	Maximum number of CPUs ever available. Optional, can be nullptr.
[in,out]	cpus	cpus.offset is first CPU of interest. cpus.granularity (see l4_sched_cpu_set_t). cpus.map Bitmap of online CPUs. Pass nullptr to omit this information.
[out]	sched_classes	A bitmap of available scheduling classes (see L4_scheduler_classes). Pass nullptr to omit this information.
	utcb	UTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.

Return values

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

Definition at line 85 of file scheduler.

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

◆ is_online()

bool L4::Scheduler::is_online	(	l4_umword_t	cpu,
		l4_utcb_t *	utcb = `l4_utcb()`
	)		const

inlinenoexcept

Query if a CPU is online.

Parameters

cpu	CPU number whose online status should be queried.
utcb	UTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.

Return values

true	The CPU is online.
false	The CPU is offline

Definition at line 165 of file scheduler.

◆ run_thread()

l4_msgtag_t L4::Scheduler::run_thread	(	Ipc::Cap< Thread >	thread,
		l4_sched_param_t const &	sp
	)

Run a thread on a Scheduler.

Parameters

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.

The documentation for this class was generated from the following file:

l4/sys/scheduler

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ idle_time()

◆ info()

◆ is_online()

◆ run_thread()