L4Re - L4 Runtime Environment
scheduler
Go to the documentation of this file.
1 // vi:set ft=cpp: -*- Mode: C++ -*-
2 /**
3  * \file
4  * Scheduler object functions.
5  */
6 /*
7  * (c) 2008-2009 Adam Lackorzynski <adam@os.inf.tu-dresden.de>,
8  * Alexander Warg <warg@os.inf.tu-dresden.de>
9  * economic rights: Technische Universität Dresden (Germany)
10  *
11  * This file is part of TUD:OS and distributed under the terms of the
12  * GNU General Public License 2.
13  * Please see the COPYING-GPL-2 file for details.
14  *
15  * As a special exception, you may use this file as part of a free software
16  * library without restriction. Specifically, if other files instantiate
17  * templates or use macros or inline functions from this file, or you compile
18  * this file and link it with other files to produce an executable, this
19  * file does not by itself cause the resulting executable to be covered by
20  * the GNU General Public License. This exception does not however
21  * invalidate any other reasons why the executable file might be covered by
22  * the GNU General Public License.
23  */
24 #pragma once
25 
26 #include <l4/sys/icu>
27 #include <l4/sys/scheduler.h>
28 #include <l4/sys/capability>
29 #include <l4/sys/cxx/ipc_iface>
30 
31 namespace L4 {
32 
33 /**
34  * C++ interface of the Scheduler kernel object.
35  *
36  * The Scheduler interface allows a client to manage CPU resources. The API
37  * provides functions to query scheduler information, check the online state of
38  * CPUs, query CPU idle time and to start threads on defined CPU sets.
39  *
40  * \includefile{l4/sys/scheduler}
41  */
42 class L4_EXPORT Scheduler :
43  public Kobject_t<Scheduler, Icu, L4_PROTO_SCHEDULER,
44  Type_info::Demand_t<1> >
45 {
46 public:
47  // ABI function for 'info' call
48  L4_INLINE_RPC_NF_OP(L4_SCHEDULER_INFO_OP,
49  l4_msgtag_t, info, (l4_umword_t gran_offset, l4_umword_t *map,
50  l4_umword_t *cpu_max));
51 
52  /**
53  * Get scheduler information.
54  *
55  * \param[out] cpu_max Maximum number of CPUs ever available.
56  * \param[in,out] cpus \a cpus.offset is first CPU of interest.
57  * \a cpus.granularity (see l4_sched_cpu_set_t).
58  * \a cpus.map Bitmap of online CPUs.
59  * \param utcb UTCB pointer of the calling thread. This defaults
60  * to the UTCB of the current thread.
61  *
62  * \retval 0 Success.
63  * \retval -L4_ERANGE The given CPU offset is larger than the maximum number
64  * of CPUs.
65  */
66  l4_msgtag_t info(l4_umword_t *cpu_max, l4_sched_cpu_set_t *cpus,
67  l4_utcb_t *utcb = l4_utcb()) const throw()
68  {
69  l4_umword_t max = 0;
70  l4_msgtag_t t =
71  info_t::call(c(), cpus->gran_offset, &cpus->map, &max, utcb);
72  if (cpu_max) *cpu_max = max;
73  return t;
74  }
75 
76  /**
77  * Run a thread on a Scheduler.
78  *
79  * \param thread Capability of the thread to run.
80  * \param sp Scheduling parameters.
81  *
82  * \retval 0 Success.
83  * \retval -L4_EINVAL Invalid size of the scheduling parameter.
84  *
85  * This function launches a thread on a CPU determined by the scheduling
86  * parameter `sp.affinity`. A thread can be intentionally stopped by
87  * migrating it on an offline or an invalid CPU. The thread is only
88  * guaranteed to run if the CPU it is migrated to is currently online.
89  *
90  * \note A scheduler may impose a policy with regard to selecting CPUs.
91  * However the scheduler is required to ensure the following two properties:
92  * - Two threads with disjoint CPU sets must be scheduled to different
93  * physical CPUs.
94  * - Two threads with a single identical CPU selected in the CPU set must be
95  * scheduled to the same physical CPU.
96  */
97  L4_INLINE_RPC_OP(L4_SCHEDULER_RUN_THREAD_OP,
98  l4_msgtag_t, run_thread, (Ipc::Cap<Thread> thread, l4_sched_param_t const &sp));
99 
100  /**
101  * Query the idle time (in µs) of a CPU.
102  *
103  * \param cpus Set of CPUs to query. Only the idle time of the first
104  * selected CPU in `cpus.map` is queried.
105  * \param[out] us Idle time of queried CPU in µs.
106  *
107  * \retval 0 Success.
108  * \retval -L4_EINVAL Invalid CPU requested in cpu set.
109  *
110  * This function retrieves the idle time in µs of the first selected
111  * CPU in `cpus.map`. The idle time is the accumulated time a CPU has spent in
112  * the idle thread since its last reset. To calculate a load estimate `l` one
113  * has to retrieve the idle time at the beginning (`i1`) and the end (`i2`)
114  * of a known time interval `t`. The load is then calculated as
115  * l = 1 - (i2 - i1)/t.
116  *
117  * The idle time is only defined for online CPUs. Reading the idle time from
118  * offline CPUs is undefined and may result in either getting -L4_EINVAL or
119  * calculating an estimated (incorrect) load of 1.
120  *
121  * \note The idle time statistics of remote CPUs is updated on context switch
122  * events only, hence may not be up-to-date when requested cross-CPU. To get
123  * up-to-date idle time you should use a thread running on the same CPU of
124  * which the idle time is requested.
125  */
126  L4_INLINE_RPC_OP(L4_SCHEDULER_IDLE_TIME_OP,
127  l4_msgtag_t, idle_time, (l4_sched_cpu_set_t const &cpus,
128  l4_kernel_clock_t *us));
129 
130  /**
131  * Query if a CPU is online.
132  *
133  * \param cpu CPU number whose online status should be queried.
134  * \param utcb UTCB pointer of the calling thread. Defaults to \a l4_utcb().
135  *
136  * \retval true The CPU is online.
137  * \retval false The CPU is offline
138  */
139  bool is_online(l4_umword_t cpu, l4_utcb_t *utcb = l4_utcb()) const throw()
140  { return l4_scheduler_is_online_u(cap(), cpu, utcb); }
141 
142  typedef L4::Typeid::Rpcs_sys<info_t, run_thread_t, idle_time_t> Rpcs;
143 };
144 }