sbin/geom/class/sched/gsched.8

   1 .\" Copyright (c) 2009-2010 Fabio Checconi
   2 .\" Copyright (c) 2009-2010 Luigi Rizzo, Universita` di Pisa
   3 .\" 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 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd April 12, 2010
  29 .Dt GSCHED 8
  30 .Os
  31 .Sh NAME
  32 .Nm gsched
  33 .Nd "control utility for disk scheduler GEOM class"
  34 .Sh SYNOPSIS
  35 .Nm
  36 .Cm create
  37 .Op Fl v
  38 .Op Fl a Ar algorithm
  39 .Ar provider ...
  40 .Nm
  41 .Cm insert
  42 .Op Fl v
  43 .Op Fl a Ar algorithm
  44 .Ar provider ...
  45 .Nm
  46 .Cm configure
  47 .Op Fl v
  48 .Op Fl a Ar algorithm
  49 .Ar node ...
  50 .Nm
  51 .Cm destroy
  52 .Op Fl fv
  53 .Ar node ...
  54 .Nm
  55 .Cm reset
  56 .Op Fl v
  57 .Ar node ...
  58 .Nm
  59 .Cm { list | status | load | unload }
  60 .Sh DESCRIPTION
  61 The
  62 .Nm
  63 utility (also callable as
  64 .Nm geom sched ... )
  65 changes the scheduling policy of the requests going to a provider.
  66 .Pp
  67 The first argument to
  68 .Nm
  69 indicates an action to be performed:
  70 .Bl -tag -width ".Cm configure"
  71 .It Cm create
  72 Create a new provider and geom node using the specified scheduling algorithm.
  73 .Ar algorithm
  74 is the name of the scheduling algorithm used for the provider.
  75 Available algorithms include:
  76 .Ar rr ,
  77 which implements anticipatory scheduling with round robin service
  78 among clients;
  79 .Ar as ,
  80 which implements a simple form of anticipatory scheduling with
  81 no per-client queue.
  82 .Pp
  83 If the operation succeeds, the new provider should appear with name
  84 .Pa /dev/ Ns Ao Ar dev Ac Ns Pa .sched. .
  85 The kernel module
  86 .Pa geom_sched.ko
  87 will be loaded if it is not loaded already.
  88 .It Cm insert
  89 Operates as "create", but the insertion is "transparent",
  90 i.e. the existing provider is rerouted to the newly created geom,
  91 which in turn forwards requests to the existing geom.
  92 This operation allows one to start/stop a scheduling service
  93 on an already existing provider.
  94 .Pp
  95 A subsequent 'destroy' will remove the newly created geom and
  96 hook the provider back to the original geom.
  97 .Ar algorithm
  98 .It Cm configure
  99 Configure existing scheduling provider.  It supports the same options
 100 as the
 101 .Nm create
 102 command.
 103 .It Cm destroy
 104 Destroy the geom specified in the parameter.
 105 .It Cm reset
 106 Do nothing.
 107 .It Cm list | status | load | unload
 108 See
 109 .Xr geom 8 .
 110 .El
 111 .Pp
 112 Additional options:
 113 .Bl -tag -width ".Fl f"
 114 .It Fl f
 115 Force the removal of the specified provider.
 116 .It Fl v
 117 Be more verbose.
 118 .El
 119 .Sh SYSCTL VARIABLES
 120 The following
 121 .Xr sysctl 8
 122 variables can be used to control the behavior of the
 123 .Nm SCHED
 124 GEOM class.
 125 The default value is shown next to each variable.
 126 .Bl -tag -width indent
 127 .It Va kern.geom.sched.debug : No 0
 128 Debug level of the
 129 .Nm SCHED
 130 GEOM class.
 131 This can be set to a number between 0 and 2 inclusive.
 132 If set to 0 minimal debug information is printed, and if set to 2 the
 133 maximum amount of debug information is printed.
 134 .El
 135 .Sh EXIT STATUS
 136 Exit status is 0 on success, and 1 if the command fails.
 137 .Sh EXAMPLES
 138 The following example shows how to create a scheduling provider for disk
 139 .Pa /dev/da0
 140 , and how to destroy it.
 141 .Bd -literal -offset indent
 142 # Load the geom_sched module:
 143 kldload geom_sched
 144 # Load some scheduler classes used by geom_sched:
 145 kldload gsched_rr gsched_as
 146 # Configure device ad0 to use scheduler 'rr':
 147 geom sched insert -s rr ad0
 148 # Now provider ad0 uses the 'rr' algorithm;
 149 # the new geom is ad0.sched.
 150 # Remove the scheduler on the device:
 151 geom sched destroy -v ad0.sched.
 152 .Ed
 153 .Pp
 154 .Sh SEE ALSO
 155 .Xr geom 4 ,
 156 .Xr geom 8
 157 .Sh HISTORY
 158 The
 159 .Nm
 160 utility appeared in April 2010.
 161 .Sh AUTHORS
 162 .An Fabio Checconi Aq fabio@FreeBSD.org
 163 .An Luigi Rizzo Aq luigi@FreeBSD.org