## ia64/xen-unstable

### view docs/src/interface/scheduling.tex @ 6979:f8e7af29daa1

merge?
author cl349@firebug.cl.cam.ac.uk Tue Sep 20 09:43:46 2005 +0000 (2005-09-20) 750ad97f37b0 06d84bf87159
line source
1 \chapter{Scheduling API}
3 The scheduling API is used by both the schedulers described above and should
4 also be used by any new schedulers. It provides a generic interface and also
5 implements much of the boilerplate'' code.
7 Schedulers conforming to this API are described by the following
8 structure:
10 \begin{verbatim}
11 struct scheduler
12 {
13 char *name; /* full name for this scheduler */
14 char *opt_name; /* option name for this scheduler */
15 unsigned int sched_id; /* ID for this scheduler */
17 int (*init_scheduler) ();
22 void (*wake_up) (struct task_struct *);
23 void (*do_block) (struct task_struct *);
25 int (*control) (struct sched_ctl_cmd *);
28 s32 (*reschedule) (struct task_struct *);
29 void (*dump_settings) (void);
30 void (*dump_cpu_state) (int);
31 void (*dump_runq_el) (struct task_struct *);
32 };
33 \end{verbatim}
35 The only method that {\em must} be implemented is
36 {\tt do\_schedule()}. However, if there is not some implementation for the
37 {\tt wake\_up()} method then waking tasks will not get put on the runqueue!
39 The fields of the above structure are described in more detail below.
41 \subsubsection{name}
43 The name field should point to a descriptive ASCII string.
45 \subsubsection{opt\_name}
47 This field is the value of the {\tt sched=} boot-time option that will select
48 this scheduler.
50 \subsubsection{sched\_id}
52 This is an integer that uniquely identifies this scheduler. There should be a
53 macro corrsponding to this scheduler ID in {\tt <xen/sched-if.h>}.
55 \subsubsection{init\_scheduler}
57 \paragraph*{Purpose}
59 This is a function for performing any scheduler-specific initialisation. For
60 instance, it might allocate memory for per-CPU scheduler data and initialise it
61 appropriately.
63 \paragraph*{Call environment}
65 This function is called after the initialisation performed by the generic
66 layer. The function is called exactly once, for the scheduler that has been
67 selected.
69 \paragraph*{Return values}
71 This should return negative on failure --- this will cause an
72 immediate panic and the system will fail to boot.
76 \paragraph*{Purpose}
77 Called when a {\tt task\_struct} is allocated by the generic scheduler
78 layer. A particular scheduler implementation may use this method to
79 allocate per-task data for this task. It may use the {\tt
80 sched\_priv} pointer in the {\tt task\_struct} to point to this data.
82 \paragraph*{Call environment}
83 The generic layer guarantees that the {\tt sched\_priv} field will
84 remain intact from the time this method is called until the task is
85 deallocated (so long as the scheduler implementation does not change
86 it explicitly!).
88 \paragraph*{Return values}
89 Negative on failure.
93 \paragraph*{Purpose}
95 Called when a task is initially added by the generic layer.
97 \paragraph*{Call environment}
99 The fields in the {\tt task\_struct} are now filled out and available for use.
100 Schedulers should implement appropriate initialisation of any per-task private
101 information in this method.
105 \paragraph*{Purpose}
107 Schedulers should free the space used by any associated private data
108 structures.
110 \paragraph*{Call environment}
112 This is called when a {\tt task\_struct} is about to be deallocated.
113 The generic layer will have done generic task removal operations and
114 (if implemented) called the scheduler's {\tt rem\_task} method before
115 this method is called.
119 \paragraph*{Purpose}
121 This is called when a task is being removed from scheduling (but is
122 not yet being freed).
124 \subsubsection{wake\_up}
126 \paragraph*{Purpose}
128 Called when a task is woken up, this method should put the task on the runqueue
129 (or do the scheduler-specific equivalent action).
131 \paragraph*{Call environment}
135 \subsubsection{do\_block}
137 \paragraph*{Purpose}
139 This function is called when a task is blocked. This function should
140 not remove the task from the runqueue.
142 \paragraph*{Call environment}
144 The EVENTS\_MASTER\_ENABLE\_BIT is already set and the task state changed to
145 TASK\_INTERRUPTIBLE on entry to this method. A call to the {\tt
146 do\_schedule} method will be made after this method returns, in
147 order to select the next task to run.
149 \subsubsection{do\_schedule}
151 This method must be implemented.
153 \paragraph*{Purpose}
155 The method is called each time a new task must be chosen for scheduling on the
156 current CPU. The current time as passed as the single argument (the current
157 task can be found using the {\tt current} macro).
159 This method should select the next task to run on this CPU and set it's minimum
160 time to run as well as returning the data described below.
162 This method should also take the appropriate action if the previous
163 task has blocked, e.g. removing it from the runqueue.
165 \paragraph*{Call environment}
167 The other fields in the {\tt task\_struct} are updated by the generic layer,
168 which also performs all Xen-specific tasks and performs the actual task switch
169 (unless the previous task has been chosen again).
171 This method is called with the {\tt schedule\_lock} held for the current CPU
172 and local interrupts disabled.
174 \paragraph*{Return values}
176 Must return a {\tt struct task\_slice} describing what task to run and how long
177 for (at maximum).
179 \subsubsection{control}
181 \paragraph*{Purpose}
183 This method is called for global scheduler control operations. It takes a
184 pointer to a {\tt struct sched\_ctl\_cmd}, which it should either
185 source data from or populate with data, depending on the value of the
186 {\tt direction} field.
188 \paragraph*{Call environment}
190 The generic layer guarantees that when this method is called, the
191 caller selected the correct scheduler ID, hence the scheduler's
192 implementation does not need to sanity-check these parts of the call.
194 \paragraph*{Return values}
196 This function should return the value to be passed back to user space, hence it
197 should either be 0 or an appropriate errno value.
201 \paragraph*{Purpose}
203 This method is called to adjust the scheduling parameters of a particular
204 domain, or to query their current values. The function should check
205 the {\tt direction} field of the {\tt sched\_adjdom\_cmd} it receives in
206 order to determine which of these operations is being performed.
208 \paragraph*{Call environment}
210 The generic layer guarantees that the caller has specified the correct
211 control interface version and scheduler ID and that the supplied {\tt
212 task\_struct} will not be deallocated during the call (hence it is not
215 \paragraph*{Return values}
217 This function should return the value to be passed back to user space, hence it
218 should either be 0 or an appropriate errno value.
220 \subsubsection{reschedule}
222 \paragraph*{Purpose}
224 This method is called to determine if a reschedule is required as a result of a
227 \paragraph*{Call environment}
228 The generic layer will cause a reschedule if the current domain is the idle
229 task or it has exceeded its minimum time slice before a reschedule. The
230 generic layer guarantees that the task passed is not currently running but is
231 on the runqueue.
233 \paragraph*{Return values}
235 Should return a mask of CPUs to cause a reschedule on.
237 \subsubsection{dump\_settings}
239 \paragraph*{Purpose}
241 If implemented, this should dump any private global settings for this
242 scheduler to the console.
244 \paragraph*{Call environment}
246 This function is called with interrupts enabled.
248 \subsubsection{dump\_cpu\_state}
250 \paragraph*{Purpose}
252 This method should dump any private settings for the specified CPU.
254 \paragraph*{Call environment}
256 This function is called with interrupts disabled and the {\tt schedule\_lock}
257 for the specified CPU held.
259 \subsubsection{dump\_runq\_el}
261 \paragraph*{Purpose}
263 This method should dump any private settings for the specified task.
265 \paragraph*{Call environment}
267 This function is called with interrupts disabled and the {\tt schedule\_lock}
268 for the task's CPU held.