.\"
.\" Copyright (c) 2011
.\"	The DragonFly Project.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in
.\"    the documentation and/or other materials provided with the
.\"    distribution.
.\" 3. Neither the name of The DragonFly Project nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific, prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd August 19, 2011
.Dt BFQ 8
.Os
.Sh NAME
.Nm BFQ
.Nd Budget Fair Queueing disk scheduling policy
.Sh SYNOPSIS
To compile this driver into the kernel,
place the following lines in your
kernel configuration file:
.Bd -ragged -offset indent
.Cd "options dsched_bfq"
.Ed
.Pp
Alternatively, to load the driver as a
module at boot time, place the following line in
.Xr loader.conf 5 :
.Bd -literal -offset indent
dsched_bfq_load="YES"
.Ed
.Sh DESCRIPTION
The
.Nm
disk scheduler is invented by Paolo Valente.
The current version of
.Nm
in
.Dx
is implemented according to his technique report.
Also, some additional features are added into the current version;
they are inspired by the Linux version, but are totally written from scratch.
.Pp
Like the CFQ (Complete Fair Queue) disk scheduler under Linux,
.Nm
is a fair queueing scheduler that aims to improve the interactivity and
lower the latency of the system.
Maximizing throughput, however, is not the major design goal of it.
So it is better to switch to
.Nm
if the computer is for desktop usage, in which interactivity eclipses
throughput in general.
.Ss Switching To BFQ
You may use
.Xr sysctl 8
to switch to
.Nm
(where
.Dq ad0
is the name of your hard drive):
.Bd -literal -offset indent
sysctl dsched.policy.ad0=bfq
.Ed
.Pp
A loader tunable of the same name is available for setting it permanently.
.Ss Tuning BFQ
Currently
.Nm
has two tunable parameters: the global AS switch and the maximum budget.
They can be tuned by the
.Xr sysctl 8
command, for example:
.Bd -literal -offset indent
#enable the global AS feature:
sysctl dsched.bfq.ad0.as_switch=1

#set the max budget to 512KB:
sysctl dsched.bfq.ad0.max_budget=524288

#enable automatic max budget adapting:
sysctl dsched.bfq.ad0.auto_max_budget=0
.Ed
.Bl -tag -width indent
.It The AS feature
It is reported that turning AS on may affect the interactivity and increase
max latency greatly.
It is probably due to the over-serialized implementation of BFQ.
However, the blogbench shows that turning AS
on will also increase the throughput greatly.
.Pp
Suggestion: turn on the AS feature, for it effects little on average
latency.
.It The max budget
One thread could be assigned a budget no more than the max budget.
Generally,
a higher budget means higher throughput because of less operations on
WF2Q+ augtree, while a lower budget force the scheduler cost more on
those operations.
.Pp
However, the real world experiments show that a too high budget affects
interactivity heavily.
A too low budget will also cause higher latency, and
if the budget is less than 64KB (65536), which is smaller than the size of
some bios, the scheduler will retrograde to a round-robin scheduler, which
is not a good form for a disk scheduler.
.Pp
Suggestions: Do not use automatic max budget, it is usually too high.
A budget of 1/10 of the automatic max budget may be proper.
In general, 512K(default), 256K, 192K can be good.
It is better to determine the
best max budget by binary selecting by the result of some benchmarks.
.El
.Sh SEE ALSO
.Xr dsched 4 ,
.Xr kldload 8 ,
.Xr sysctl 8
.Pp
.Pa http://leaf.dragonflybsd.org/~brillsp/bfq_doc/bfq.html
.Sh HISTORY
The
.Nm
scheduler first appeared in
.Dx 2.11 .
.Sh AUTHORS
The
.Nm
scheduling policy was written by
.An Brills Peng.
.Sh BUGS
When switching to another dsched policy from BFQ, the system may deadlock.
.Pp
Currently, the overall performance is not very good and it is not tested on
large number of machines.
It is not recommended to use this version in a productivity environment.