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 July 26, 2012
  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 .It Cm configure
  98 Configure existing scheduling provider.  It supports the same options
  99 as the
 100 .Nm create
 101 command.
 102 .It Cm destroy
 103 Destroy the geom specified in the parameter.
 104 .It Cm reset
 105 Do nothing.
 106 .It Cm list | status | load | unload
 107 See
 108 .Xr geom 8 .
 109 .El
 110 .Pp
 111 Additional options:
 112 .Bl -tag -width ".Fl f"
 113 .It Fl f
 114 Force the removal of the specified provider.
 115 .It Fl v
 116 Be more verbose.
 117 .El
 118 .Sh SYSCTL VARIABLES
 119 The following
 120 .Xr sysctl 8
 121 variables can be used to control the behavior of the
 122 .Nm SCHED
 123 GEOM class.
 124 The default value is shown next to each variable.
 125 .Bl -tag -width indent
 126 .It Va kern.geom.sched.debug : No 0
 127 Debug level of the
 128 .Nm SCHED
 129 GEOM class.
 130 This can be set to a number between 0 and 2 inclusive.
 131 If set to 0 minimal debug information is printed, and if set to 2 the
 132 maximum amount of debug information is printed.
 133 .El
 134 .Sh EXIT STATUS
 135 Exit status is 0 on success, and 1 if the command fails.
 136 .Sh EXAMPLES
 137 The following example shows how to create a scheduling provider for disk
 138 .Pa /dev/ada0 ,
 139 and how to destroy it.
 140 .Bd -literal -offset indent
 141 # Load the geom_sched module:
 142 kldload geom_sched
 143 # Load some scheduler classes used by geom_sched:
 144 kldload gsched_rr
 145 # Configure device ada0 to use scheduler "rr":
 146 geom sched insert -a rr ada0
 147 # Now provider ada0 uses the "rr" algorithm;
 148 # the new geom is ada0.sched.
 149 # Remove the scheduler on the device:
 150 geom sched destroy -v ada0.sched.
 151 .Ed
 152 .Sh SEE ALSO
 153 .Xr geom 4 ,
 154 .Xr geom 8
 155 .Sh HISTORY
 156 The
 157 .Nm
 158 utility first appeared in
 159 .Fx 8.1 .
 160 .Sh AUTHORS
 161 .An Fabio Checconi Aq fabio@FreeBSD.org
 162 .An Luigi Rizzo Aq luigi@FreeBSD.org