.\"
.\" $FreeBSD: src/share/man/man4/polling.4,v 1.1.2.4 2003/04/14 08:58:02 maxim Exp $
.\" $DragonFly: src/share/man/man4/polling.4,v 1.6 2005/10/13 11:05:10 swildner Exp $
.\"
.Dd October 13, 2005
.Dt POLLING 4
.Os
.Sh NAME
.Nm polling
.Nd device polling support
.Sh SYNOPSIS
.Cd "options DEVICE_POLLING"
.Sh DESCRIPTION
Typically, devices generate interrupts when they need attention
from the CPU.  Device polling
.Dq ( "polling" ,
for brevity,) refers to a technique for handling devices that does not
rely on interrupts.  Rather, it lets the CPU poll devices periodically
to service their needs.
This might seem inefficient and counterintuitive, but when done
properly,
.Nm
gives more control to the operating system on
when and how to handle devices, with a number of advantages in terms
of system responsivity and performance.
.Pp
In particular,
.Nm
reduces the overhead for context
switches which is incurred when servicing interrupts, and
gives more control on the scheduling of the CPU between various
tasks (user processes, software interrupts, device handling)
which ultimately reduces the chances of livelock in the system.
.Sh 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 execution of an interrupt handler
which performs whatever processing is needed by the device.
The duration of the interrupt handler is potentially unbounded
unless the device driver has been programmed with real-time
concerns in mind (which is generally not the case for
.Dx
drivers).
Furthermore, under heavy traffic, the system might be
persistently processing interrupts without being able to
complete other work, either in the kernel or in userland.
.Pp
.Nm 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.
.Pp
.Nm Polling
is enabled with a
.Xr sysctl 8
variable
.Va kern.polling.enable
whereas the polling frequency is controlled by the
.Xr sysctl 8
variable
.Va kern.polling.pollhz
whose range is 1 to 30000 (2000 is the default value).
The percentage of CPU cycles reserved to userland processes is
controlled by the
.Xr sysctl 8
variable
.Va kern.polling.user_frac
whose range is 0 to 100 (50 is the default value).
.Pp
When
.Nm
is enabled, and provided that there is work to do,
up to
.Va kern.polling.user_frac
percent of the CPU cycles is reserved to userland tasks, the
remaining fraction being available for device processing.
.Pp
Enabling
.Nm
also changes the way network software interrupts
are scheduled, so there is never the risk of livelock because
packets are not processed to completion.
.Pp
There are other variables which control or monitor the behaviour
of devices operating in polling mode, but they are unlikely to
require modifications, and are documented in the source file
.Pa sys/kern/kern_poll.c .
.Sh SUPPORTED DEVICES
.Nm Polling
requires explicit modifications to the device drivers.
As of this writing, the
.Xr dc 4 ,
.Xr em 4 ,
.Xr fwe 4 ,
.Xr fxp 4 ,
.Xr nge 4 ,
.Xr nv 4 ,
.Xr re 4 ,
.Xr rl 4 ,
.Xr sis 4 ,
.Xr vr 4 ,
and
.Xr wi 4
devices are supported, with other in the works.
The modifications are rather straightforward, consisting in
the extraction of the inner part of the interrupt service routine
and writing a callback function,
.Fn *_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.
.Pp
In order to reduce the latency in processing packets,
it is advisable to set the
.Xr sysctl 8
variable
.Va kern.polling.pollhz
to at least 1000.
.Sh HISTORY
Device polling was introduced in February 2002 by
.An Luigi Rizzo Aq luigi@iet.unipi.it .