share/man/man4/polling.4

   1 .\" Copyright (c) 2002 Luigi Rizzo
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd December 14, 2004
  28 .Dt POLLING 4
  29 .Os
  30 .Sh NAME
  31 .Nm polling
  32 .Nd device polling support
  33 .Sh SYNOPSIS
  34 .Cd "options DEVICE_POLLING"
  35 .Cd "options HZ=1000"
  36 .Sh DESCRIPTION
  37 Device polling
  38 .Nm (
  39 for brevity) refers to a technique that
  40 lets the operating system periodically poll devices, instead of
  41 relying on the devices to generate interrupts when they need attention.
  42 This might seem inefficient and counterintuitive, but when done
  43 properly,
  44 .Nm
  45 gives more control to the operating system on
  46 when and how to handle devices, with a number of advantages in terms
  47 of system responsiveness and performance.
  48 .Pp
  49 In particular,
  50 .Nm
  51 reduces the overhead for context
  52 switches which is incurred when servicing interrupts, and
  53 gives more control on the scheduling of the CPU between various
  54 tasks (user processes, software interrupts, device handling)
  55 which ultimately reduces the chances of livelock in the system.
  56 .Ss Principles of Operation
  57 In the normal, interrupt-based mode, devices generate an interrupt
  58 whenever they need attention.
  59 This in turn causes a
  60 context switch and the execution of an interrupt handler
  61 which performs whatever processing is needed by the device.
  62 The duration of the interrupt handler is potentially unbounded
  63 unless the device driver has been programmed with real-time
  64 concerns in mind (which is generally not the case for
  65 .Fx
  66 drivers).
  67 Furthermore, under heavy traffic load, the system might be
  68 persistently processing interrupts without being able to
  69 complete other work, either in the kernel or in userland.
  70 .Pp
  71 Device polling disables interrupts by polling devices at appropriate
  72 times, i.e., on clock interrupts, system calls and within the idle loop.
  73 This way, the context switch overhead is removed.
  74 Furthermore,
  75 the operating system can control accurately how much work to spend
  76 in handling device events, and thus prevent livelock by reserving
  77 some amount of CPU to other tasks.
  78 .Pp
  79 Enabling
  80 .Nm
  81 also changes the way software network interrupts
  82 are scheduled, so there is never the risk of livelock because
  83 packets are not processed to completion.
  84 .Ss MIB Variables
  85 The operation of
  86 .Nm
  87 is controlled by the following
  88 .Xr sysctl 8
  89 MIB variables:
  90 .Pp
  91 .Bl -tag -width indent -compact
  92 .It Va kern.polling.enable
  93 If set to non-zero,
  94 .Nm
  95 is enabled.
  96 Default is disabled.
  97 .Pp
  98 .It Va kern.polling.user_frac
  99 When
 100 .Nm
 101 is enabled, and provided that there is some work to do,
 102 up to this percent of the CPU cycles is reserved to userland tasks,
 103 the remaining fraction being available for
 104 .Nm
 105 processing.
 106 Default is 50.
 107 .Pp
 108 .It Va kern.polling.burst
 109 Maximum number of packets grabbed from each network interface in
 110 each timer tick.
 111 This number is dynamically adjusted by the kernel,
 112 according to the programmed
 113 .Va user_frac , burst_max ,
 114 CPU speed, and system load.
 115 .Pp
 116 .It Va kern.polling.each_burst
 117 The burst above is split into smaller chunks of this number of
 118 packets, going round-robin among all interfaces registered for
 119 .Nm .
 120 This prevents the case that a large burst from a single interface
 121 can saturate the IP interrupt queue
 122 .Pq Va net.inet.ip.intr_queue_maxlen .
 123 Default is 5.
 124 .Pp
 125 .It Va kern.polling.burst_max
 126 Upper bound for
 127 .Va kern.polling.burst .
 128 Note that when
 129 .Nm
 130 is enabled, each interface can receive at most
 131 .Pq Va HZ No * Va burst_max
 132 packets per second unless there are spare CPU cycles available for
 133 .Nm
 134 in the idle loop.
 135 This number should be tuned to match the expected load
 136 (which can be quite high with GigE cards).
 137 Default is 150 which is adequate for 100Mbit network and HZ=1000.
 138 .Pp
 139 .It Va kern.polling.idle_poll
 140 Controls if
 141 .Nm
 142 is enabled in the idle loop.
 143 There are no reasons (other than power saving or bugs in the scheduler's
 144 handling of idle priority kernel threads) to disable this.
 145 Note that -CURRENT apparently has some problems in this respect now,
 146 so default is disabled.
 147 .Pp
 148 .It Va kern.polling.poll_in_trap
 149 Controls if
 150 .Nm
 151 is enabled during hardware traps.
 152 Enabling this can be useful to improve the network responsiveness
 153 of boxes with 100% CPU usage.
 154 Default is disabled.
 155 .Pp
 156 .It Va kern.polling.reg_frac
 157 Controls how often (every
 158 .Va reg_frac No / Va HZ
 159 seconds) the status registers of the device are checked for error
 160 conditions and the like.
 161 Increasing this value reduces the load on the bus, but also delays
 162 the error detection.
 163 Default is 20.
 164 .Pp
 165 .It Va kern.polling.handlers
 166 How many active devices have registered for
 167 .Nm .
 168 .Pp
 169 .It Va kern.polling.short_ticks
 170 .It Va kern.polling.lost_polls
 171 .It Va kern.polling.pending_polls
 172 .It Va kern.polling.residual_burst
 173 .It Va kern.polling.phase
 174 .It Va kern.polling.suspect
 175 .It Va kern.polling.stalled
 176 Debugging variables.
 177 .El
 178 .Sh SUPPORTED DEVICES
 179 Device polling requires explicit modifications to the device drivers.
 180 As of this writing, the
 181 .Xr dc 4 ,
 182 .Xr em 4 ,
 183 .Xr fwe 4 ,
 184 .Xr fwip 4 ,
 185 .Xr fxp 4 ,
 186 .Xr ixgb 4 ,
 187 .Xr nge 4 ,
 188 .Xr re 4 ,
 189 .Xr rl 4 ,
 190 .Xr sf 4 ,
 191 .Xr sis 4 ,
 192 .Xr ste 4 ,
 193 .Xr vge 4 ,
 194 and
 195 .Xr vr 4
 196 devices are supported, with others in the works.
 197 The modifications are rather straightforward, consisting in
 198 the extraction of the inner part of the interrupt service routine
 199 and writing a callback function,
 200 .Fn *_poll ,
 201 which is invoked
 202 to probe the device for events and process them.
 203 (See the
 204 conditionally compiled sections of the devices mentioned above
 205 for more details.)
 206 .Pp
 207 As in the worst case the devices are only polled on
 208 clock interrupts, in order to reduce the latency in processing
 209 packets, it is advisable to increase the frequency of the clock
 210 to at least 1000 HZ.
 211 .Sh HISTORY
 212 Device polling first appeared in
 213 .Fx 4.6
 214 and
 215 .Fx 5.0 .
 216 .Sh AUTHORS
 217 Device polling was written by
 218 .An Luigi Rizzo Aq luigi@iet.unipi.it .