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 ) and
 342 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 .