home | help
POLLING(4)		     Kernel Interfaces Manual		      POLLING(4)

NAME
     polling -- device polling support

SYNOPSIS
     options DEVICE_POLLING
     options HZ=1000

DESCRIPTION
     Device  polling  (polling	for brevity) refers to a technique that lets the
     operating system periodically poll devices, instead of relying on	the  de-
     vices to generate interrupts when they need attention.  This might seem in-
     efficient	and counterintuitive, but when done properly, polling gives more
     control to the operating system on when and how to handle devices,  with  a
     number of advantages in terms of system responsiveness and performance.

     In  particular,  polling reduces the overhead for context switches which is
     incurred when servicing interrupts, and gives more control on the	schedul-
     ing  of the CPU between various tasks (user processes, software interrupts,
     device handling) which ultimately reduces the chances of  livelock  in  the
     system.

   Principles of Operation
     In the normal, interrupt-based mode, devices generate an interrupt whenever
     they  need  attention.  This in turn causes a context switch and the execu-
     tion of an interrupt handler which performs whatever processing  is  needed
     by  the  device.	The duration of the interrupt handler is potentially un-
     bounded unless the device driver has been programmed  with  real-time  con-
     cerns  in mind (which is generally not the case for FreeBSD drivers).  Fur-
     thermore, under heavy traffic load, the system might be  persistently  pro-
     cessing interrupts without being able to complete other work, either in the
     kernel or in userland.

     Device polling disables interrupts by polling devices at appropriate times,
     i.e.,  on	clock  interrupts,  system calls and within the idle loop.  This
     way, the context switch overhead is removed.   Furthermore,  the  operating
     system  can  control  accurately  how much work to spend in handling device
     events, and thus prevent livelock by reserving some amount of CPU to  other
     tasks.

     Enabling  polling	also  changes  the  way  software network interrupts are
     scheduled, so there is never the risk of livelock because packets	are  not
     processed to completion.

   MIB Variables
     The operation of polling is controlled by the following sysctl(8) MIB vari-
     ables:

     kern.polling.enable
	     If set to non-zero, polling is enabled.  Default is disabled.

     kern.polling.user_frac
	     When  polling  is	enabled, and provided that there is some work to
	     do, up to this percent of the CPU cycles is  reserved  to	userland
	     tasks,  the remaining fraction being available for polling process-
	     ing.  Default is 50.

     kern.polling.burst
	     Maximum number of packets grabbed from each  network  interface  in
	     each  timer  tick.  This number is dynamically adjusted by the ker-
	     nel, according to the programmed user_frac, burst_max,  CPU  speed,
	     and system load.

     kern.polling.each_burst
	     The  burst  above	is  split  into smaller chunks of this number of
	     packets, going round-robin  among	all  interfaces  registered  for
	     polling.	This  prevents the case that a large burst from a single
	     interface	  can	 saturate     the     IP     interrupt	   queue
	     (net.inet.ip.intr_queue_maxlen).  Default is 5.

     kern.polling.burst_max
	     Upper  bound for kern.polling.burst.  Note that when polling is en-
	     abled, each interface can receive at most (HZ * burst_max)  packets
	     per  second unless there are spare CPU cycles available for polling
	     in the idle loop.	This number should be tuned  to  match	the  ex-
	     pected  load (which can be quite high with GigE cards).  Default is
	     150 which is adequate for 100Mbit network and HZ=1000.

     kern.polling.idle_poll
	     Controls if polling is enabled in the idle loop.  There are no rea-
	     sons (other than power saving or bugs in the  scheduler's	handling
	     of  idle priority kernel threads) to disable this.  Note that -CUR-
	     RENT apparently has some problems in this respect now,  so  default
	     is disabled.

     kern.polling.poll_in_trap
	     Controls  if  polling  is	enabled during hardware traps.	Enabling
	     this can be useful to improve the network responsiveness  of  boxes
	     with 100% CPU usage.  Default is disabled.

     kern.polling.reg_frac
	     Controls  how often (every reg_frac / HZ seconds) the status regis-
	     ters of the device are checked for error conditions and  the  like.
	     Increasing  this value reduces the load on the bus, but also delays
	     the error detection.  Default is 20.

     kern.polling.handlers
	     How many active devices have registered for polling.

     kern.polling.short_ticks
     kern.polling.lost_polls
     kern.polling.pending_polls
     kern.polling.residual_burst
     kern.polling.phase
     kern.polling.suspect
     kern.polling.stalled
	     Debugging variables.

SUPPORTED DEVICES
     Device polling requires explicit modifications to the device  drivers.   As
     of  this writing, the dc(4), em(4), fwe(4), fxp(4), ixgb(4), nge(4), re(4),
     rl(4), sis(4), ste(4), vge(4), and vr(4) devices are supported, with others
     in the works.  The modifications are rather straightforward, consisting  in
     the extraction of the inner part of the interrupt service routine and writ-
     ing a callback function, *_poll(), which is invoked to probe the device for
     events  and  process them.  (See the conditionally compiled sections of the
     devices mentioned above for more details.)

     As in the worst case the devices are only polled on  clock  interrupts,  in
     order  to	reduce the latency in processing packets, it is advisable to in-
     crease the frequency of the clock to at least 1000 HZ.

HISTORY
     Device polling first appeared in FreeBSD 4.6 and FreeBSD 5.0.

AUTHORS
     Device polling was written by Luigi Rizzo <luigi@iet.unipi.it>.

FreeBSD 5.3			  April 5, 2004 		      POLLING(4)

home | help