diff options
Diffstat (limited to 'static/freebsd/man4/polling.4 3.html')
| -rw-r--r-- | static/freebsd/man4/polling.4 3.html | 184 |
1 files changed, 184 insertions, 0 deletions
diff --git a/static/freebsd/man4/polling.4 3.html b/static/freebsd/man4/polling.4 3.html new file mode 100644 index 00000000..1dc51bd1 --- /dev/null +++ b/static/freebsd/man4/polling.4 3.html @@ -0,0 +1,184 @@ +<table class="head"> + <tr> + <td class="head-ltitle">POLLING(4)</td> + <td class="head-vol">Device Drivers Manual</td> + <td class="head-rtitle">POLLING(4)</td> + </tr> +</table> +<div class="manual-text"> +<section class="Sh"> +<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> +<p class="Pp"><code class="Nm">polling</code> — <span class="Nd">device + polling support</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><code class="Cd">options DEVICE_POLLING</code></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">Device polling ( <code class="Nm">polling</code> for brevity) + refers to a technique that lets the operating system periodically poll + devices, instead of relying on the devices to generate interrupts when they + need attention. This might seem inefficient and counterintuitive, but when + done properly, <code class="Nm">polling</code> 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.</p> +<p class="Pp">In particular, <code class="Nm">polling</code> 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.</p> +<section class="Ss"> +<h2 class="Ss" id="Principles_of_Operation"><a class="permalink" href="#Principles_of_Operation">Principles + of Operation</a></h2> +<p class="Pp">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 + <span class="Ux">FreeBSD</span> drivers). Furthermore, under heavy traffic + load, the system might be persistently processing interrupts without being + able to complete other work, either in the kernel or in userland.</p> +<p class="Pp">Device polling disables interrupts by polling devices at + appropriate times, i.e., on clock interrupts 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.</p> +<p class="Pp">Enabling <code class="Nm">polling</code> also changes the way + software network interrupts are scheduled, so there is never the risk of + livelock because packets are not processed to completion.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="Enabling_polling"><a class="permalink" href="#Enabling_polling">Enabling + polling</a></h2> +<p class="Pp">Currently only network interface drivers support the + <code class="Nm">polling</code> feature. It is turned on and off with help + of <a class="Xr">ifconfig(8)</a> command.</p> +<p class="Pp">The historic <var class="Va">kern.polling.enable</var>, which + enabled polling for all interfaces, can be replaced with the following + code:</p> +<div class="Bd Pp Li"> +<pre>for i in `ifconfig -l` ; + do ifconfig $i polling; # use -polling to disable +done</pre> +</div> +</section> +<section class="Ss"> +<h2 class="Ss" id="MIB_Variables"><a class="permalink" href="#MIB_Variables">MIB + Variables</a></h2> +<p class="Pp">The operation of <code class="Nm">polling</code> is controlled by + the following <a class="Xr">sysctl(8)</a> MIB variables:</p> +<p class="Pp"></p> +<dl class="Bl-tag Bl-compact"> + <dt id="kern.polling.user_frac"><var class="Va">kern.polling.user_frac</var></dt> + <dd>When <code class="Nm">polling</code> 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 + <code class="Nm">polling</code> processing. Default is 50. + <p class="Pp"></p> + </dd> + <dt id="kern.polling.burst"><var class="Va">kern.polling.burst</var></dt> + <dd>Maximum number of packets grabbed from each network interface in each + timer tick. This number is dynamically adjusted by the kernel, according + to the programmed <var class="Va">user_frac</var>, + <var class="Va">burst_max</var>, CPU speed, and system load. + <p class="Pp"></p> + </dd> + <dt id="kern.polling.each_burst"><var class="Va">kern.polling.each_burst</var></dt> + <dd>The burst above is split into smaller chunks of this number of packets, + going round-robin among all interfaces registered for + <code class="Nm">polling</code>. This prevents the case that a large burst + from a single interface can saturate the IP interrupt queue + (<var class="Va">net.inet.ip.intr_queue_maxlen</var>). Default is 5. + <p class="Pp"></p> + </dd> + <dt id="kern.polling.burst_max"><var class="Va">kern.polling.burst_max</var></dt> + <dd>Upper bound for <var class="Va">kern.polling.burst</var>. Note that when + <code class="Nm">polling</code> is enabled, each interface can receive at + most (<var class="Va">HZ</var> <span class="No">*</span> + <var class="Va">burst_max</var>) packets per second unless there are spare + CPU cycles available for <code class="Nm">polling</code> in the idle loop. + This number should be tuned to match the expected load (which can be quite + high with GigE cards). Default is 150 which is adequate for 100Mbit + network and HZ=1000. + <p class="Pp"></p> + </dd> + <dt id="kern.polling.idle_poll"><var class="Va">kern.polling.idle_poll</var></dt> + <dd>Controls if <code class="Nm">polling</code> is enabled in the idle loop. + There are no reasons (other than power saving or bugs in the scheduler's + handling of idle priority kernel threads) to disable this. + <p class="Pp"></p> + </dd> + <dt id="kern.polling.reg_frac"><var class="Va">kern.polling.reg_frac</var></dt> + <dd>Controls how often (every <var class="Va">reg_frac</var> + <span class="No">/</span> <var class="Va">HZ</var> seconds) the status + registers 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. + <p class="Pp"></p> + </dd> + <dt id="kern.polling.handlers"><var class="Va">kern.polling.handlers</var></dt> + <dd>How many active devices have registered for + <code class="Nm">polling</code>. + <p class="Pp"></p> + </dd> + <dt id="kern.polling.short_ticks"><var class="Va">kern.polling.short_ticks</var></dt> + <dd style="width: auto;"> </dd> + <dt id="kern.polling.lost_polls"><var class="Va">kern.polling.lost_polls</var></dt> + <dd style="width: auto;"> </dd> + <dt id="kern.polling.pending_polls"><var class="Va">kern.polling.pending_polls</var></dt> + <dd style="width: auto;"> </dd> + <dt id="kern.polling.residual_burst"><var class="Va">kern.polling.residual_burst</var></dt> + <dd style="width: auto;"> </dd> + <dt id="kern.polling.phase"><var class="Va">kern.polling.phase</var></dt> + <dd style="width: auto;"> </dd> + <dt id="kern.polling.suspect"><var class="Va">kern.polling.suspect</var></dt> + <dd style="width: auto;"> </dd> + <dt id="kern.polling.stalled"><var class="Va">kern.polling.stalled</var></dt> + <dd>Debugging variables.</dd> +</dl> +</section> +</section> +<section class="Sh"> +<h1 class="Sh" id="SUPPORTED_DEVICES"><a class="permalink" href="#SUPPORTED_DEVICES">SUPPORTED + DEVICES</a></h1> +<p class="Pp">Device polling requires explicit modifications to the device + drivers. As of this writing, the <a class="Xr">bge(4)</a>, + <a class="Xr">dc(4)</a>, <a class="Xr">em(4)</a>, <a class="Xr">fwe(4)</a>, + <a class="Xr">fwip(4)</a>, <a class="Xr">fxp(4)</a>, + <a class="Xr">igb(4)</a>, <a class="Xr">nfe(4)</a>, + <a class="Xr">nge(4)</a>, <a class="Xr">re(4)</a>, <a class="Xr">rl(4)</a>, + <a class="Xr">sis(4)</a>, <a class="Xr">ste(4)</a>, + <a class="Xr">stge(4)</a>, <a class="Xr">vge(4)</a>, + <a class="Xr">vr(4)</a>, and <a class="Xr">xl(4)</a> 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 writing a callback function, + <a class="permalink" href="#*_poll"><code class="Fn" id="*_poll">*_poll</code></a>(), + 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.)</p> +<p class="Pp">As in the worst case the devices are only polled on clock + interrupts, in order to reduce the latency in processing packets, it is not + advisable to decrease the frequency of the clock below 1000 Hz.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">Device polling first appeared in <span class="Ux">FreeBSD + 4.6</span> and <span class="Ux">FreeBSD 5.0</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">Device polling was written by <span class="An">Luigi Rizzo</span> + <<a class="Mt" href="mailto:luigi@iet.unipi.it">luigi@iet.unipi.it</a>>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">December 26, 2020</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |