docs: block: convert to ReST

	blkdevparts=	Manual partition parsing of block device(s) for

			embedded devices based on command line input.

			See Documentation/block/cmdline-partition.txt

			See Documentation/block/cmdline-partition.rst

	boot_delay=	Milliseconds to delay each printk during boot.

			Values larger than 10 seconds (10000) are changed to

	elevator=	[IOSCHED]

			Format: { "mq-deadline" | "kyber" | "bfq" }

			See Documentation/block/deadline-iosched.txt,

			Documentation/block/kyber-iosched.txt and

			Documentation/block/bfq-iosched.txt for details.

			See Documentation/block/deadline-iosched.rst,

			Documentation/block/kyber-iosched.rst and

			Documentation/block/bfq-iosched.rst for details.

	elfcorehdr=[size[KMG]@]offset[KMG] [IA64,PPC,SH,X86,S390]

			Specifies physical address of start of kernel core

==========================

BFQ (Budget Fair Queueing)

==========================

BFQ is a proportional-share I/O scheduler, with some extra

low-latency capabilities. In addition to cgroups support (blkio or io

controllers), BFQ's main features are:

- BFQ guarantees a high system and application responsiveness, and a

  low latency for time-sensitive applications, such as audio or video

  players;

BFQ works for multi-queue devices too.

The table of contents follow. Impatients can just jump to Section 3.

.. The table of contents follow. Impatients can just jump to Section 3.

CONTENTS

.. CONTENTS

   1. When may BFQ be useful?

    1-1 Personal systems

--------------------

Low latency for interactive applications

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Regardless of the actual background workload, BFQ guarantees that, for

interactive tasks, the storage device is virtually as responsive as if

it was idle. For example, even if one or more of the following

background workloads are being executed:

- one or more large files are being read, written or copied,

- a tree of source files is being compiled,

- one or more virtual machines are performing I/O,

- a software update is in progress,

- indexing daemons are scanning filesystems and updating their

  databases,

starting an application or loading a file from within an application

takes about the same time as if the storage device was idle. As a

comparison, with CFQ, NOOP or DEADLINE, and in the same conditions,

until the background workload terminates (also on SSDs).

Low latency for soft real-time applications

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Also soft real-time applications, such as audio and video

players/streamers, enjoy a low latency and a low drop rate, regardless

of the background I/O workload. As a consequence, these applications

do not suffer from almost any glitch due to the background workload.

Higher speed for code-development tasks

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If some additional workload happens to be executed in parallel, then

BFQ executes the I/O-related components of typical code-development

NOOP or DEADLINE.

High throughput

^^^^^^^^^^^^^^^

On hard disks, BFQ achieves up to 30% higher throughput than CFQ, and

up to 150% higher throughput than DEADLINE and NOOP, with all the

instead, about the same throughput as the other schedulers.

Strong fairness, bandwidth and delay guarantees

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

BFQ distributes the device throughput, and not just the device time,

among I/O-bound applications in proportion their weights, with any

properties as above. In particular, regardless of whether additional,

possibly heavy workloads are being served, BFQ guarantees:

. audio and video-streaming with zero or very low jitter and drop

* audio and video-streaming with zero or very low jitter and drop

  rate;

. fast retrieval of WEB pages and embedded objects;

* fast retrieval of WEB pages and embedded objects;

. real-time recording of data in live-dumping applications (e.g.,

* real-time recording of data in live-dumping applications (e.g.,

  packet logging);

. responsiveness in local and remote access to a server.

* responsiveness in local and remote access to a server.

2. How does BFQ work?

plus a lot of code, are borrowed from CFQ.

- Each process doing I/O on a device is associated with a weight and a

  (bfq_)queue.

  `(bfq_)queue`.

- BFQ grants exclusive access to the device, for a while, to one queue

  (process) at a time, and implements this service model by

CONFIG_BFQ_CGROUP_DEBUG is set. If it is set, then bfq creates all

the stat files documented in

Documentation/cgroup-v1/blkio-controller.rst. If, instead,

CONFIG_BFQ_CGROUP_DEBUG is not set, then bfq creates only the files

CONFIG_BFQ_CGROUP_DEBUG is not set, then bfq creates only the files::

  blkio.bfq.io_service_bytes

  blkio.bfq.io_service_bytes_recursive

  blkio.bfq.io_serviced

applications. Unset this tunable if you need/want to control weights.

[1] P. Valente, A. Avanzini, "Evolution of the BFQ Storage I/O

[1]

    P. Valente, A. Avanzini, "Evolution of the BFQ Storage I/O

    Scheduler", Proceedings of the First Workshop on Mobile System

    Technologies (MST-2015), May 2015.

    http://algogroup.unimore.it/people/paolo/disk_sched/mst-2015.pdf

[2] P. Valente and M. Andreolini, "Improving Application

[2]

    P. Valente and M. Andreolini, "Improving Application

    Responsiveness with the BFQ Disk I/O Scheduler", Proceedings of

    the 5th Annual International Systems and Storage Conference

    (SYSTOR '12), June 2012.

    Slightly extended version:

    http://algogroup.unimore.it/people/paolo/disk_sched/bfq-v1-suite-

							results.pdf

[3] https://github.com/Algodev-github/S

    http://algogroup.unimore.it/people/paolo/disk_sched/bfq-v1-suite-results.pdf

[3]

   https://github.com/Algodev-github/S

Immutable biovecs and biovec iterators:

=======================================

======================================

Immutable biovecs and biovec iterators

======================================

Kent Overstreet <kmo@daterainc.com>

Usage of helpers:

=================

* The following helpers whose names have the suffix of "_all" can only be used

* The following helpers whose names have the suffix of `_all` can only be used

  on non-BIO_CLONED bio. They are usually used by filesystem code. Drivers

  shouldn't use them because the bio may have been split before it reached the

  driver.

::

	bio_for_each_segment_all()

	bio_first_bvec_all()

	bio_first_page_all()

	bio_last_bvec_all()

* The following helpers iterate over single-page segment. The passed 'struct

bio_vec' will contain a single-page IO vector during the iteration

  bio_vec' will contain a single-page IO vector during the iteration::

	bio_for_each_segment()

	bio_for_each_segment_all()

* The following helpers iterate over multi-page bvec. The passed 'struct

bio_vec' will contain a multi-page IO vector during the iteration

  bio_vec' will contain a multi-page IO vector during the iteration::

	bio_for_each_bvec()

	rq_for_each_bvec()

===============================

Generic Block Device Capability

===============================================================================

===============================

This file documents the sysfs file block/<disk>/capability

capability is a hex word indicating which capabilities a specific disk

supports.  For more information on bits not listed here, see

include/linux/genhd.h

Capability				Value

-------------------------------------------------------------------------------

GENHD_FL_MEDIA_CHANGE_NOTIFY		4

GENHD_FL_MEDIA_CHANGE_NOTIFY

----------------------------

Value: 4

When this bit is set, the disk supports Asynchronous Notification

of media change events.  These events will be broadcast to user

space via kernel uevent.