share/man/man4/polling.4

   1 .\"
   2 .\" $FreeBSD: src/share/man/man4/polling.4,v 1.1.2.4 2003/04/14 08:58:02 maxim Exp $
   3 .\" $DragonFly: src/share/man/man4/polling.4,v 1.9 2007/06/08 07:39:20 swildner Exp $
   4 .\"
   5 .Dd October 13, 2005
   6 .Dt POLLING 4
   7 .Os
   8 .Sh NAME
   9 .Nm polling
  10 .Nd device polling support
  11 .Sh SYNOPSIS
  12 .Cd "options DEVICE_POLLING"
  13 .Sh DESCRIPTION
  14 Typically, devices generate interrupts when they need attention
  15 from the CPU.  Device polling
  16 .Dq ( "polling" ,
  17 for brevity,) refers to a technique for handling devices that does not
  18 rely on interrupts.  Rather, it lets the CPU poll devices periodically
  19 to service their needs.
  20 This might seem inefficient and counterintuitive, but when done
  21 properly,
  22 .Nm
  23 gives more control to the operating system on
  24 when and how to handle devices, with a number of advantages in terms
  25 of system responsivity and performance.
  26 .Pp
  27 In particular,
  28 .Nm
  29 reduces the overhead for context
  30 switches which is incurred when servicing interrupts, and
  31 gives more control on the scheduling of the CPU between various
  32 tasks (user processes, software interrupts, device handling)
  33 which ultimately reduces the chances of livelock in the system.
  34 .Sh PRINCIPLES OF OPERATION
  35 In the normal, interrupt-based mode, devices generate an interrupt
  36 whenever they need attention.
  37 This in turn causes a
  38 context switch and the execution of an interrupt handler
  39 which performs whatever processing is needed by the device.
  40 The duration of the interrupt handler is potentially unbounded
  41 unless the device driver has been programmed with real-time
  42 concerns in mind (which is generally not the case for
  43 .Dx
  44 drivers).
  45 Furthermore, under heavy traffic, the system might be
  46 persistently processing interrupts without being able to
  47 complete other work, either in the kernel or in userland.
  48 .Pp
  49 .Nm Polling
  50 disables interrupts by polling devices at appropriate
  51 times, i.e., on clock interrupts, system calls and within the idle loop.
  52 This way, the context switch overhead is removed.
  53 Furthermore,
  54 the operating system can control accurately how much work to spend
  55 in handling device events, and thus prevent livelock by reserving
  56 some amount of CPU to other tasks.
  57 .Pp
  58 .Nm Polling
  59 is enabled with a
  60 .Xr sysctl 8
  61 variable
  62 .Va kern.polling.enable
  63 whereas the polling frequency is controlled by the
  64 .Xr sysctl 8
  65 variable
  66 .Va kern.polling.pollhz
  67 whose range is 1 to 30000 (2000 is the default value).
  68 The percentage of CPU cycles reserved to userland processes is
  69 controlled by the
  70 .Xr sysctl 8
  71 variable
  72 .Va kern.polling.user_frac
  73 whose range is 0 to 100 (50 is the default value).
  74 .Pp
  75 When
  76 .Nm
  77 is enabled, and provided that there is work to do,
  78 up to
  79 .Va kern.polling.user_frac
  80 percent of the CPU cycles is reserved to userland tasks, the
  81 remaining fraction being available for device processing.
  82 .Pp
  83 Enabling
  84 .Nm
  85 also changes the way network software interrupts
  86 are scheduled, so there is never the risk of livelock because
  87 packets are not processed to completion.
  88 .Pp
  89 There are other variables which control or monitor the behaviour
  90 of devices operating in polling mode, but they are unlikely to
  91 require modifications, and are documented in the source file
  92 .Pa sys/kern/kern_poll.c .
  93 .Sh SUPPORTED DEVICES
  94 .Nm Polling
  95 requires explicit modifications to the device drivers.
  96 As of this writing, the
  97 .Xr bce 4 ,
  98 .Xr bge 4 ,
  99 .Xr dc 4 ,
 100 .Xr em 4 ,
 101 .Xr fwe 4 ,
 102 .Xr fxp 4 ,
 103 .Xr nfe 4 ,
 104 .Xr nge 4 ,
 105 .Xr nv 4 ,
 106 .Xr re 4 ,
 107 .Xr rl 4 ,
 108 .Xr sis 4 ,
 109 .Xr stge 4 ,
 110 .Xr vge 4 ,
 111 .Xr vr 4 ,
 112 .Xr wi 4
 113 and
 114 .Xr xl 4
 115 devices are supported, with other in the works.
 116 The modifications are rather straightforward, consisting in
 117 the extraction of the inner part of the interrupt service routine
 118 and writing a callback function,
 119 .Fn *_poll ,
 120 which is invoked
 121 to probe the device for events and process them.
 122 See the
 123 conditionally compiled sections of the devices mentioned above
 124 for more details.
 125 .Pp
 126 In order to reduce the latency in processing packets,
 127 it is advisable to set the
 128 .Xr sysctl 8
 129 variable
 130 .Va kern.polling.pollhz
 131 to at least 1000.
 132 .Sh HISTORY
 133 Device polling was introduced in February 2002 by
 134 .An Luigi Rizzo Aq luigi@iet.unipi.it .