5d61aa941ef69bdcd7645f3e24e70bd8ee787321
[dragonfly.git] / share / man / man9 / dsched.9
1 .\"
2 .\" Copyright (c) 2010
3 .\"     The DragonFly Project.  All rights reserved.
4 .\"
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
7 .\" are met:
8 .\"
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\"    notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\"    notice, this list of conditions and the following disclaimer in
13 .\"    the documentation and/or other materials provided with the
14 .\"    distribution.
15 .\" 3. Neither the name of The DragonFly Project nor the names of its
16 .\"    contributors may be used to endorse or promote products derived
17 .\"    from this software without specific, prior written permission.
18 .\"
19 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
22 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
23 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
24 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
25 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
26 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
27 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
29 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" SUCH DAMAGE.
31 .\"
32 .Dd September 29, 2010
33 .Dt DSCHED 9
34 .Os
35 .Sh NAME
36 .Nm dsched ,
37 .Nm dsched_cancel_bio ,
38 .Nm dsched_debug ,
39 .Nm dsched_disk_ctx_ref ,
40 .Nm dsched_disk_ctx_unref ,
41 .Nm dsched_new_policy_thread_tdio ,
42 .Nm dsched_register ,
43 .Nm dsched_strategy_async ,
44 .Nm dsched_strategy_raw ,
45 .Nm dsched_thread_io_ref ,
46 .Nm dsched_thread_io_unref ,
47 .Nm dsched_unregister ,
48 .Nm DSCHED_POLICY_MODULE ,
49 .Nm DSCHED_DISK_CTX_LOCK ,
50 .Nm DSCHED_DISK_CTX_UNLOCK ,
51 .Nm DSCHED_THREAD_IO_LOCK ,
52 .Nm DSCHED_THREAD_IO_UNLOCK ,
53 .Nm dsched_get_bio_dp ,
54 .Nm dsched_get_bio_priv ,
55 .Nm dsched_get_disk_priv
56 .Nd kernel disk scheduler framework
57 .Sh SYNOPSIS
58 .In sys/dsched.h
59 .Pp
60 Functions:
61 .Ft void
62 .Fn dsched_cancel_bio "struct bio *bp"
63 .Ft int
64 .Fn dsched_debug "int level" "char *fmt" "..."
65 .Ft void
66 .Fn dsched_disk_ctx_ref "struct dsched_disk_ctx *diskctx"
67 .Ft void
68 .Fn dsched_disk_ctx_unref "struct dsched_disk_ctx *diskctx"
69 .Ft struct dsched_thread_io *
70 .Fn dsched_new_policy_thread_tdio "struct dsched_disk_ctx *diskctx" "struct dsched_policy *pol"
71 .Ft int
72 .Fn dsched_register "struct dsched_policy *d_policy"
73 .Ft void
74 .Fn dsched_strategy_async "struct disk *dp" "struct bio *bp" "biodone_t *done" "void *priv"
75 .Ft void
76 .Fn dsched_strategy_raw "struct disk *dp" "struct bio *bp"
77 .Ft void
78 .Fn dsched_thread_io_ref "struct dsched_thread_io *tdio"
79 .Ft void
80 .Fn dsched_thread_io_unref "struct dsched_thread_io *tdio"
81 .Ft int
82 .Fn dsched_unregister "struct dsched_policy *d_policy"
83 .Pp
84 Macros:
85 .Fn DSCHED_POLICY_MODULE "name" "modeventhand_t evh"
86 .Fn DSCHED_DISK_CTX_LOCK "struct dsched_disk_ctx *diskctx"
87 .Fn DSCHED_DISK_CTX_UNLOCK "struct dsched_disk_ctx *diskctx"
88 .Fn DSCHED_THREAD_IO_LOCK "struct dsched_thread_io *tdio"
89 .Fn DSCHED_THREAD_IO_UNLOCK "struct dsched_thread_io *tdio"
90 .Fn dsched_get_bio_dp "struct bio *bio"
91 .Fn dsched_get_bio_priv "struct bio *bio"
92 .Fn dsched_get_disk_priv "struct disk *dp" "void *priv"
93 .Pp
94 Callbacks:
95 .Ft typedef int
96 .Fn dsched_prepare_t "struct dsched_disk_ctx *diskctx"
97 .Ft typedef void
98 .Fn dsched_teardown_t "struct dsched_disk_ctx *diskctx"
99 .Ft typedef void
100 .Fn dsched_cancel_t "struct dsched_disk_ctx *diskctx"
101 .Ft typedef int
102 .Fn dsched_queue_t "struct dsched_disk_ctx *diskctx" "struct dsched_thread_io *tdio" "struct bio *bio"
103 .Ft typedef void
104 .Fn dsched_new_tdio_t "struct dsched_thread_io *tdio"
105 .Ft typedef void
106 .Fn dsched_destroy_tdio_t "struct dsched_thread_io *tdio"
107 .Ft typedef void
108 .Fn dsched_new_diskctx_t "struct dsched_disk_ctx *diskctx"
109 .Ft typedef void
110 .Fn dsched_destroy_diskctx_t "struct dsched_disk_ctx *diskctx"
111 .Sh DESCRIPTION
112 To create a new dsched policy
113 .Sq foo
114 the following is required:
115 .Bd -literal
116 DSCHED_POLICY_MODULE(dsched_foo, foo_mod_handler);
117
118 struct dsched_policy dsched_foo_policy = {
119         .name = "foo",
120
121         .prepare = foo_prepare,
122         .teardown = foo_teardown,
123         .cancel_all = foo_cancel,
124         .bio_queue = foo_queue,
125
126         /* The following are optional */
127         .new_tdio = foo_tdio_ctor,
128         .new_diskctx = foo_diskctx_ctor,
129         .destroy_tdio = foo_tdio_dtor,
130         .destroy_diskctx = foo_diskctx_dtor
131 };
132 .Ed
133 .Pp
134 The
135 .Fa name
136 is the unique identifier of the dsched policy and the name the user
137 specifies to set this
138 .Nm
139 policy.
140 .Pp
141 The
142 .Fa prepare
143 callback is called whenever the new
144 .Nm
145 policy is set for a new disk.
146 This can be used to create per disk threads for the
147 .Nm
148 policy instance.
149 Note that any thread created during
150 .Fa prepare
151 will not have a
152 .Ft dsched_thread_ctx
153 or
154 .Ft dsched_thread_io
155 associated with it.
156 If this is required because the thread will do I/O, the thread itself
157 needs to call
158 .Fn dsched_new_policy_thread_tdio .
159 .Pp
160 The
161 .Fa teardown
162 callback is called whenever a
163 .Nm
164 policy is unset/detached from a disk or when a disk is disconnected.
165 It should clean up all per-disk resources such as any thread created in
166 .Fa prepare .
167 The
168 .Nm
169 framework guarantees that no more calls to any other method such as
170 .Fa bio_queue
171 will occur once
172 .Fa teardown
173 has been called.
174 .Pp
175 The
176 .Fa cancel_all
177 callback is called immediately before
178 .Fa teardown .
179 It is required to cancel all
180 .Vt bio Ns s
181 currently queued or stalled in the
182 .Nm
183 policy instance for the given disk.
184 The
185 .Nm
186 framework guarantees that no more calls to any other method such as
187 .Fa bio_queue
188 will occur once
189 .Fa cancel_all
190 has been called.
191 .Pp
192 The
193 .Fa bio_queue
194 callback is called for every
195 .Vt bio
196 intended for the disk(s) with the given
197 .Nm
198 policy.
199 It needs to either dispatch it, queue it in any other form for later
200 dispatch, or return a non-zero return value, in which case the
201 .Nm
202 framework will dispatch that
203 .Vt bio
204 directly.
205 If the function took care of the
206 .Vt bio
207 and does not want dsched to dispatch it, 0 must be returned.
208 .Pp
209 The
210 .Fa new_tdio
211 callback is called for every
212 .Vt dsched_thread_io
213 created for a disk with this
214 .Nm
215 policy.
216 Similarly, the
217 .Fa destroy_tdio
218 callback is called on destruction (release of all references) of the
219 .Vt dsched_thread_io .
220 These functions don't have to be specified; if they are left out or
221 set to
222 .Dv NULL
223 they simply won't be called.
224 .Pp
225 The
226 .Fa new_diskctx
227 callback is called for every
228 .Vt dsched_disk_ctx
229 created for a disk with this
230 .Nm
231 policy.
232 Similarly, the
233 .Fa destroy_diskctx
234 callback is called on destruction (release of all references) of the
235 .Vt dsched_disk_ctx .
236 These functions don't have to be specified; if they are left out or
237 set to
238 .Dv NULL ,
239 they simply won't be called.
240 .Pp
241 For convenience, the structs
242 .Vt dsched_thread_io
243 and
244 .Vt dsched_disk_ctx
245 are allocated with plenty of spare space, so that each policy can extend
246 these, for example as follows:
247 .Bd -literal
248 struct foo_thread_io {
249         struct dsched_thread_io head;
250         int foo;
251         int bar;
252 };
253
254 struct foo_disk_ctx {
255         struct dsched_disk_ctx head;
256         int foo;
257         int bar;
258 };
259
260 CTASSERT(sizeof(struct foo_thread_io) <= DSCHED_THREAD_IO_MAX_SZ);
261 CTASSERT(sizeof(struct foo_disk_ctx) <= DSCHED_DISK_CTX_MAX_SZ);
262 .Ed
263 .Pp
264 It is important that the first member of the new struct is one of type
265 .Vt dsched_thread_io
266 or
267 .Vt dsched_disk_ctx ,
268 respectively.
269 The
270 .Fn CTASSERT
271 must be used to ensure that the new structs fit into the space provided
272 by
273 .Nm dsched .
274 Not including these asserts can cause serious and difficult to debug
275 issues.
276 For all the functions described in
277 .Sx FUNCTIONS
278 that require a
279 .Vt dsched_thread_io
280 or
281 .Vt dsched_disk_ctx ,
282 the address of the
283 .Fa head
284 element should be passed, or alternatively the address of the new struct
285 be cast to the right type and that passed.
286 .Sh FUNCTIONS
287 The
288 .Fn DSCHED_POLICY_MODULE
289 macro declares a
290 .Nm
291 policy kernel module.
292 .Fa evh
293 is the event handler for the module (see
294 .Xr DECLARE_MODULE 9
295 for more information).
296 The event handler is supposed to register a
297 .Nm
298 policy with
299 .Fn dsched_register
300 on load and to unregister it using
301 .Fn dsched_unregister
302 when it is unloaded.
303 .Pp
304 The
305 .Fn dsched_strategy_async
306 function dispatches a
307 .Vt bio Fa bp
308 in an asynchronous manner to the disk specified by
309 .Fa dp .
310 The private data
311 .Fa priv
312 will be attached to the
313 .Vt bio
314 and is later retrievable via
315 .Fn dsched_get_bio_priv .
316 The
317 .Vt biodone_t
318 routine
319 .Fa done
320 will be called once the
321 .Vt bio
322 completes.
323 The
324 .Fa done
325 routine can use
326 .Fn dsched_get_disk_priv ,
327 .Fn dsched_get_bio_dp
328 and
329 .Fn dsched_get_bio_priv
330 to retrieve the context.
331 Since
332 .Fn dsched_strategy_async
333 also saves the current time (via
334 .Fn getmicrotime )
335 in
336 .Fa bio->bio_caller_info3.tv ,
337 the
338 .Fa done
339 routine can also calculate the time passed from dispatch to completion
340 by getting the current time again (via
341 .Fn getmicrotime )
342 and calculating the timeval difference to the value stored in
343 .Fa bio->bio_caller_info3.tv .
344 At the end of the
345 .Fa done
346 routine it needs to call
347 .Fn pop_bio
348 and
349 .Fn biodone
350 as for any other
351 .Vt biodone_t
352 routine.
353 .Pp
354 The
355 .Fn dsched_cancel_bio
356 function cancels the
357 .Vt bio
358 and sets
359 .Er ENXIO
360 as error on the buf.
361 .Pp
362 The
363 .Fn dsched_strategy_raw
364 function simply dispatches the
365 .Vt bio
366 directly to the disk specified by
367 .Fa dp
368 using
369 .Fn dev_dstrategy .
370 .Pp
371 The
372 .Fn dsched_debug
373 function works as a conditional
374 .Fn kprintf .
375 Depending on the setting of the
376 .Va dsched.debug
377 .Xr sysctl 8
378 variable, the debug info will be shown or not.
379 .Pp
380 The
381 .Fn dsched_register
382 function registers the policy described by
383 .Fa d_policy
384 as a valid
385 .Nm
386 policy which can then be used as a scheduler policy for the disks.
387 If a policy with the given name already exists,
388 .Er EEXIST
389 is returned (otherwise 0).
390 .Pp
391 The
392 .Fn dsched_unregister
393 function unregisters the policy described by
394 .Fa d_policy .
395 The given
396 .Nm
397 policy will no longer be valid as a scheduler policy.
398 If the given policy is currently in use,
399 .Er EBUSY
400 will be returned and the policy won't be unregistered; otherwise 0 is returned.
401 .Pp
402 The
403 .Fn DSCHED_THREAD_IO_LOCK
404 and
405 .Fn DSCHED_THREAD_IO_UNLOCK
406 functions lock and unlock a
407 .Vt dsched_thread_io
408 .Fa tdio ,
409 respectively.
410 The lock must be held whenever the members
411 .Fa queue
412 and
413 .Fa qlength
414 are manipulated to avoid messing up the
415 .Vt TAILQ .
416 It can also be used to serialize any other access to the derived
417 .Vt foo_thread_io
418 members.
419 .Pp
420 The
421 .Fn DSCHED_DISK_CTX_LOCK
422 and
423 .Fn DSCHED_DISK_CTX_UNLOCK
424 functions lock and unlock a
425 .Vt dsched_disk_ctx
426 .Fa diskctx ,
427 respectively.
428 The lock must be held whenever the member
429 .Fa queue
430 is manipulated to avoid messing up the
431 .Vt TAILQ .
432 It can also be used to serialize any other access to the derived
433 .Vt foo_disk_ctx
434 members.
435 .Pp
436 The
437 .Fn dsched_thread_io_ref
438 and
439 .Fn dsched_thread_io_unref
440 functions increase and decrease the reference count on a
441 .Vt dsched_thread_io
442 .Fa tdio ,
443 respectively.
444 Whenever the reference count drops to 0, the
445 .Fa tdio
446 will be released.
447 Be aware that it is possible that the
448 .Nm
449 framework holds references on the
450 .Fa tdio ,
451 too, so it can be that the object is not freed when all
452 references are dropped.
453 .Pp
454 The
455 .Fn dsched_disk_ctx_ref
456 and
457 .Fn dsched_disk_ctx_unref
458 functions increase and decrease the reference count on a
459 .Vt dsched_disk_ctx
460 .Fa diskctx ,
461 respectively.
462 Whenever the reference count drops to 0, the
463 .Fa diskctx
464 will be released.
465 Be aware that it is possible that the
466 .Nm
467 framework holds references on the
468 .Fa diskctx ,
469 too, so it can be that the object is not freed when all
470 references are dropped.
471 .Pp
472 The
473 .Fn dsched_get_bio_dp ,
474 .Fn dsched_get_disk_priv
475 and
476 .Fn dsched_get_bio_priv
477 are intended for use in the
478 .Vt biodone_t
479 routine specified in the call to
480 .Fn dsched_strategy_async .
481 .Fn dsched_get_bio_dp
482 retrieves the
483 .Vt struct disk
484 associated with the
485 .Vt bio .
486 This can then be used to retrieve the
487 .Vt struct dsched_disk_ctx
488 via
489 .Fn dsched_get_disk_priv .
490 The
491 .Fn dsched_get_bio_priv
492 function returns the private data associated with the
493 .Fa bio
494 on the call to
495 .Fn dsched_strategy_async .
496 .Pp
497 The
498 .Fn dsched_new_policy_thread_tdio
499 function must be called from any thread created within the
500 .Fa prepare
501 method that will perform I/O, since these won't have a
502 .Vt dsched_thread_io
503 associated with them.
504 The function returns a new
505 .Vt dsched_thread_io
506 for the current thread, for
507 the
508 .Fa diskctx
509 and
510 .Fa policy
511 specified.
512 .Sh FILES
513 The uncontended path of the
514 .Nm
515 implementation is in
516 .Pa /sys/kern/kern_dsched.c .
517 The data structures are in
518 .Pa /sys/sys/dsched.h .
519 .Sh SEE ALSO
520 .Xr dsched 4
521 .Sh HISTORY
522 The
523 .Nm
524 framework first appeared in
525 .Dx 2.5 .
526 .Sh AUTHORS
527 The
528 .Nm
529 framework was written by
530 .An Alex Hornung .