share/man/man4/fx_dptbl.4

   1 '\" te
   2 .\" Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH FX_DPTBL 4 "Oct 15, 2002"
   7 .SH NAME
   8 fx_dptbl \- fixed priority dispatcher parameter table
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBfx_dptbl\fR
  13 .fi
  14
  15 .SH DESCRIPTION
  16 .sp
  17 .LP
  18 The process scheduler or dispatcher is the portion of the kernel that controls
  19 allocation of the CPU to processes. The scheduler supports the notion of
  20 scheduling classes, where each class defines a scheduling policy used to
  21 schedule processes within that class. Associated with each scheduling class is
  22 a set of priority queues on which ready-to-run processes are linked. These
  23 priority queues are mapped by the system configuration into a set of global
  24 scheduling priorities, which are available to processes within the class. The
  25 dispatcher always selects for execution the process with the highest global
  26 scheduling priority in the system. The priority queues associated with a given
  27 class are viewed by that class as a contiguous set of priority levels numbered
  28 from 0 (lowest priority) to \fIn\fR (highest priority\(ema
  29 configuration-dependent value). The set of global scheduling priorities that
  30 the queues for a given class are mapped into might not start at zero and might
  31 not be contiguous, depending on the configuration.
  32 .sp
  33 .LP
  34 Processes in the fixed priority class are scheduled according to the parameters
  35 in a fixed-priority dispatcher parameter table (\fBfx_dptbl\fR). The
  36 \fBfx_dptbl\fR table consists of an array (\fBconfig_fx_dptbl[]\fR) of
  37 parameter structures (\fBstruct fxdpent_t\fR), one for each of the \fIn\fR
  38 priority levels used by fixed priority processes in user mode. The structures
  39 are accessed by way of a pointer, (\fBfx_dptbl\fR), to the array. The
  40 properties of a given priority level \fIi\fR are specified by the \fIi\fRth
  41 parameter structure in this array (\fBfx_dptbl[\fIi\fR]\fR).
  42 .sp
  43 .LP
  44 A parameter structure consists of the following members. These are also
  45 described in the \fB/usr/include/sys/fx.h\fR header.
  46 .sp
  47 .ne 2
  48 .na
  49 \fB\fBfx_globpri\fR\fR
  50 .ad
  51 .RS 14n
  52 The global scheduling priority associated with this priority level. The mapping
  53 between fixed-priority priority levels and global scheduling priorities is
  54 determined at boot time by the system configuration. \fBfx_globpri\fR can not
  55 be changed with \fBdispadmin\fR(8).
  56 .RE
  57
  58 .sp
  59 .ne 2
  60 .na
  61 \fB\fBfx_quantum\fR\fR
  62 .ad
  63 .RS 14n
  64 The length of the time quantum allocated to processes at this level in ticks
  65 (\fBhz\fR). The time quantum value is only a default or starting value for
  66 processes at a particular level, as the time quantum of a fixed priority
  67 process can be changed by the user with the \fBpriocntl\fR(1) command or the
  68 \fBpriocntl\fR(2) system call.
  69 .sp
  70 In the high resolution clock mode (\fBhires_tick\fR set to \fB1\fR), the value
  71 of \fBhz\fR is set to \fB1000\fR. Increase quantums to maintain the same
  72 absolute time quantums.
  73 .sp
  74 An administrator can affect the behavior of the fixed priority portion of the
  75 scheduler by reconfiguring the \fBfx_dptbl\fR. There are two methods available
  76 for doing this: reconfigure with a loadable module at boot-time or by using
  77 \fBdispadmin\fR(8) at run-time.
  78 .RE
  79
  80 .SS "fx_dptbl Loadable Module"
  81 .sp
  82 .LP
  83 The \fBfx_dptbl\fR can be reconfigured with a loadable module that contains a
  84 new fixed priority dispatch table. The module containing the dispatch table is
  85 separate from the \fBFX\fR loadable module, which contains the rest of the
  86 fixed priority software. This is the only method that can be used to change the
  87 number of fixed priority priority levels or the set of global scheduling
  88 priorities used by the fixed priority class. The relevant procedure and source
  89 code is described in Replacing the fx_dptbl Loadable Module below.
  90 .SS "dispadmin Configuration File"
  91 .sp
  92 .LP
  93 The \fBfx_quantum\fR values in the \fBfx_dptbl\fR can be examined and modified
  94 on a running system using the \fBdispadmin\fR(8) command. Invoking
  95 \fBdispadmin\fR for the fixed-priority class allows the administrator to
  96 retrieve the current \fBfx_dptbl\fR configuration from the kernel's in-core
  97 table or overwrite the in-core table with values from a configuration file. The
  98 configuration file used for input to \fBdispadmin\fR must conform to the
  99 specific format described as follows:
 100 .RS +4
 101 .TP
 102 .ie t \(bu
 103 .el o
 104 Blank lines are ignored and any part of a line to the right of a # symbol is
 105 treated as a comment.
 106 .RE
 107 .RS +4
 108 .TP
 109 .ie t \(bu
 110 .el o
 111 The first non-blank, non-comment line must indicate the resolution to be used
 112 for interpreting the time quantum values. The resolution is specified as:
 113 .sp
 114 .in +2
 115 .nf
 116 RES=\fIres\fR
 117 .fi
 118 .in -2
 119 .sp
 120
 121 where \fIres\fR is a positive integer between 1 and 1,000,000,000 inclusive and
 122 the resolution used is the reciprocal of \fIres\fR in seconds (for example,
 123 \fBRES=1000\fR specifies millisecond resolution). Although you can specify very
 124 fine (nanosecond) resolution, the time quantum lengths are rounded up to the
 125 next integral multiple of the system clock's resolution.
 126 .RE
 127 .RS +4
 128 .TP
 129 .ie t \(bu
 130 .el o
 131 The remaining lines in the file are used to specify the \fBfx_quantum\fR values
 132 for each of the fixed-priority priority levels. The first line specifies the
 133 quantum for fixed-priority level 0, the second line specifies the quantum for
 134 fixed-priority level 1, and so forth. There must be exactly one line for each
 135 configured fixed priority priority level. Each \fBfx_quantum\fR entry must be a
 136 positive integer specifying the desired time quantum in the resolution given by
 137 \fIres\fR.
 138 .RE
 139 .sp
 140 .LP
 141 See Examples for an example of an excerpt of a \fBdispadmin\fR configuration
 142 file.
 143 .SS "Replacing the fx_dptbl Loadable Module"
 144 .sp
 145 .LP
 146 To change the size of the fixed priority dispatch table, you must build the
 147 loadable module that contains the dispatch table information. Save the existing
 148 module before using the following procedure.
 149 .RS +4
 150 .TP
 151 1.
 152 Place the dispatch table code shown below in a file called \fBfx_dptbl.c\fR.
 153 See EXAMPLES, below, for an example of this file.
 154 .RE
 155 .RS +4
 156 .TP
 157 2.
 158 Compile the code using the given compilation and link lines supplied:
 159 .sp
 160 .in +2
 161 .nf
 162 cc -c -0 -D_KERNEL fx_dptbl.c
 163 ld -r -o FX_DPTBL fx_dptbl.o
 164 .fi
 165 .in -2
 166 .sp
 167
 168 .RE
 169 .RS +4
 170 .TP
 171 3.
 172 Copy the current dispatch table in \fB/usr/kernel/sched\fR to
 173 \fBFX_DPTBL.bak\fR.
 174 .RE
 175 .RS +4
 176 .TP
 177 4.
 178 Replace the current \fBFX_DPTBL\fR in \fB/usr/kernel/sched\fR.
 179 .RE
 180 .RS +4
 181 .TP
 182 5.
 183 Make changes in the \fB/etc/system\fR file to reflect the changes to the
 184 sizes of the tables. See \fBsystem\fR(4). The variables affected is
 185 \fBfx_maxupri\fR. The syntax for setting this is as follows:
 186 .sp
 187 .in +2
 188 .nf
 189 set  FX:fx_maxupri=(\fIvalue for max fixed-priority user priority\fR)
 190 .fi
 191 .in -2
 192 .sp
 193
 194 .RE
 195 .RS +4
 196 .TP
 197 6.
 198 Reboot the system to use the new dispatch table.
 199 .RE
 200 .sp
 201 .LP
 202 Exercise great care in using the preceding method to replace the dispatch
 203 table. A mistake can result in panics, thus making the system unusable.
 204 .SH EXAMPLES
 205 .LP
 206 \fBExample 1 \fRConfiguration File Excerpt
 207 .sp
 208 .LP
 209 The following excerpt from a \fBdispadmin\fR configuration file illustrates the
 210 correct format. Note that, for each line specifying a set of parameters, there
 211 is a comment indicating the corresponding priority level. These level numbers
 212 indicate priority within the fixed priority class; the mapping between these
 213 fixed-priority priorities and the corresponding global scheduling priorities is
 214 determined by the configuration specified in the \fBFX_DPTBL\fR loadable
 215 module. The level numbers are strictly for the convenience of the administrator
 216 reading the file and, as with any comment, they are ignored by \fBdispadmin\fR.
 217 The \fBdispadmin\fR command assumes that the lines in the file are ordered by
 218 consecutive, increasing priority level (from 0 to the maximum configured
 219 fixed-priority priority). For the sake of someone reading the file, the level
 220 numbers in the comments should agree with this ordering. If for some reason
 221 they do not, \fBdispadmin\fR is unaffected.
 222
 223 .sp
 224 .in +2
 225 .nf
 226 # Fixed Priority Dispatcher Configuration File RES=1000
 227
 228 RES=1000
 229 #   TIME QUANTUM              PRIORITY
 230 # (fx_quantum)                LEVEL
 231 200                           #   0
 232 200                           #   1
 233 200                           #   2
 234 200                           #   3
 235 200                           #   4
 236 200                           #   5
 237 200                           #   6
 238 200                           #   7
 239  .                            .   .
 240  .                            .   .
 241  .                            .   .
 242 20                            #   58
 243 20                            #   59
 244 20                            #   60
 245 .fi
 246 .in -2
 247 .sp
 248
 249 .LP
 250 \fBExample 2 \fR\fBfx_dptbl.c\fR File Used for Building the New \fBfx_dptbl\fR
 251 .sp
 252 .LP
 253 The following is an example of a \fBfx_dptbl.c\fR file used for building the
 254 new \fBfx_dptbl\fR.
 255
 256 .sp
 257 .in +2
 258 .nf
 259 /* BEGIN fx_dptbl.c */
 260
 261 #include <sys/proc.h>
 262 #include <sys/priocntl.h>
 263 #include <sys/class.h>
 264 #include <sys/disp.h>
 265 #include <sys/fx.h>
 266 #include <sys/fxpriocntl.h>
 267
 268
 269 /*
 270  * This is the loadable module wrapper.
 271  */
 272
 273 #include <sys/modctl.h>
 274
 275 extern struct mod_ops mod_miscops;
 276
 277 /*
 278  * Module linkage information for the kernel.
 279  */
 280
 281 static struct modlmisc modlmisc = {
 282    &mod_miscops, "Fixed priority dispatch table"
 283 };
 284
 285 static struct modlinkage modlinkage = {
 286    MODREV_1, &modlmisc, 0
 287 };
 288
 289 _init()
 290 {
 291    return (mod_install(&modlinkage));
 292 }
 293
 294 _info(modinfop)
 295    struct modinfo *modinfop;
 296 {
 297    return (mod_info(&modlinkage, modinfop));
 298 }
 299
 300 #define FXGPUP0 0   /* Global priority for FX user priority 0 */
 301 fxdpent_t config_fx_dptbl[] = {
 302
 303 /*  glbpri      qntm */
 304
 305    FXGPUP0+0,   20,
 306    FXGPUP0+1,   20,
 307    FXGPUP0+2,   20,
 308    FXGPUP0+3,   20,
 309    FXGPUP0+4,   20,
 310    FXGPUP0+5,   20,
 311    FXGPUP0+6,   20,
 312    FXGPUP0+7,   20,
 313    FXGPUP0+8,   20,
 314    FXGPUP0+9,   20,
 315    FXGPUP0+10,  16,
 316    FXGPUP0+11,  16,
 317    FXGPUP0+12,  16,
 318    FXGPUP0+13,  16,
 319    FXGPUP0+14,  16,
 320    FXGPUP0+15,  16,
 321    FXGPUP0+16,  16,
 322    FXGPUP0+17,  16,
 323    FXGPUP0+18,  16,
 324    FXGPUP0+19,  16,
 325    FXGPUP0+20,  12,
 326    FXGPUP0+21,  12,
 327    FXGPUP0+22,  12,
 328    FXGPUP0+23,  12,
 329    FXGPUP0+24,  12,
 330    FXGPUP0+25,  12,
 331    FXGPUP0+26,  12,
 332    FXGPUP0+27,  12,
 333    FXGPUP0+28,  12,
 334    FXGPUP0+29,  12,
 335    FXGPUP0+30,   8,
 336    FXGPUP0+31,   8,
 337    FXGPUP0+32,   8,
 338    FXGPUP0+33,   8,
 339    FXGPUP0+34,   8,
 340    FXGPUP0+35,   8,
 341    FXGPUP0+36,   8,
 342    FXGPUP0+37,   8,
 343    FXGPUP0+38,   8,
 344    FXGPUP0+39,   8,
 345    FXGPUP0+40,   4,
 346    FXGPUP0+41,   4,
 347    FXGPUP0+42,   4,
 348    FXGPUP0+43,   4,
 349    FXGPUP0+44,   4,
 350    FXGPUP0+45,   4,
 351    FXGPUP0+46,   4,
 352    FXGPUP0+47,   4,
 353    FXGPUP0+48,   4,
 354    FXGPUP0+49,   4,
 355    FXGPUP0+50,   4,
 356    FXGPUP0+51,   4,
 357    FXGPUP0+52,   4,
 358    FXGPUP0+53,   4,
 359    FXGPUP0+54,   4,
 360    FXGPUP0+55,   4,
 361    FXGPUP0+56,   4,
 362    FXGPUP0+57,   4,
 363    FXGPUP0+58,   4,
 364    FXGPUP0+59,   2,
 365    FXGPUP0+60    2,
 366 };
 367
 368
 369
 370 pri_t config_fx_maxumdpri =
 371                 sizeof (config_fx_dptbl) / sizeof (fxdpent_t) - 1;
 372
 373 /*
 374  * Return the address of config_fx_dptbl
 375  */
 376 fxdpent_t *
 377 fx_getdptbl()
 378 {
 379    return (config_fx_dptbl);
 380 }
 381
 382 /*
 383  * Return the address of fx_maxumdpri
 384  */
 385 pri_t
 386 fx_getmaxumdpri()
 387 {
 388 /*
 389  * the config_fx_dptbl table.
 390  */
 391    return (config_fx_maxumdpri);
 392 }
 393 .fi
 394 .in -2
 395 .sp
 396
 397 .SH SEE ALSO
 398 .sp
 399 .LP
 400 \fBpriocntl\fR(1), \fBdispadmin\fR(8), \fBpriocntl\fR(2), \fBsystem\fR(4)
 401 .sp
 402 .LP
 403 \fISystem Administration Guide, Volume 1, System Interface Guide\fR
 404 .SH NOTES
 405 .sp
 406 .LP
 407 In order to improve performance under heavy system load, both the \fBnfsd\fR
 408 daemon and the \fBlockd\fR daemon utilize the maximum priority in the \fBFX\fR
 409 class. Unusual \fBfx_dptbl\fR configurations may have significant negative
 410 impact on the performance of the \fBnfsd\fR and \fBlockd\fR daemons.