Commit 37fe4038 authored Jun 10, 2021 by Kir Kolyshkin Committed by Jens Axboe Jun 16, 2021

docs/cgroup-v1/blkio: stop abusing itemized list



Fix many formatting issues by stop (ab)using itemized lists for
everything (mostly replaced by definition lists).

Acked-by: Tejun Heo <tj@kernel.org>
Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>
Signed-off-by: Jens Axboe <axboe@kernel.dk>

parent fda0b5ba

Documentation/admin-guide/cgroup-v1/blkio-controller.rst

+67 −63

Original line number	Original line	Diff line number	Diff line
	@@ -17,29 +17,30 @@ level logical devices like device mapper.

	HOWTO		HOWTO
	=====		=====

	Throttling/Upper Limit policy		Throttling/Upper Limit policy
	-----------------------------		-----------------------------
	- Enable Block IO controller::		Enable Block IO controller::

	CONFIG_BLK_CGROUP=y		CONFIG_BLK_CGROUP=y

	- Enable throttling in block layer::		Enable throttling in block layer::

	CONFIG_BLK_DEV_THROTTLING=y		CONFIG_BLK_DEV_THROTTLING=y

	- Mount blkio controller (see cgroups.txt, Why are cgroups needed?)::		Mount blkio controller (see cgroups.txt, Why are cgroups needed?)::

	mount -t cgroup -o blkio none /sys/fs/cgroup/blkio		mount -t cgroup -o blkio none /sys/fs/cgroup/blkio

	- Specify a bandwidth rate on particular device for root group. The format		Specify a bandwidth rate on particular device for root group. The format
	for policy is "<major>:<minor> <bytes_per_second>"::		for policy is "<major>:<minor> <bytes_per_second>"::

	echo "8:16 1048576" > /sys/fs/cgroup/blkio/blkio.throttle.read_bps_device		echo "8:16 1048576" > /sys/fs/cgroup/blkio/blkio.throttle.read_bps_device

	Above will put a limit of 1MB/second on reads happening for root group		This will put a limit of 1MB/second on reads happening for root group
	on device having major/minor number 8:16.		on device having major/minor number 8:16.

	- Run dd to read a file and see if rate is throttled to 1MB/s or not::		Run dd to read a file and see if rate is throttled to 1MB/s or not::

	# dd iflag=direct if=/mnt/common/zerofile of=/dev/null bs=4K count=1024		# dd iflag=direct if=/mnt/common/zerofile of=/dev/null bs=4K count=1024
	1024+0 records in		1024+0 records in
	@@ -79,28 +80,31 @@ following::

	Various user visible config options		Various user visible config options
	===================================		===================================

	CONFIG_BLK_CGROUP		CONFIG_BLK_CGROUP
	- Block IO controller.		Block IO controller.

	CONFIG_BFQ_CGROUP_DEBUG		CONFIG_BFQ_CGROUP_DEBUG
	- Debug help. Right now some additional stats file show up in cgroup		Debug help. Right now some additional stats file show up in cgroup
	if this option is enabled.		if this option is enabled.

	CONFIG_BLK_DEV_THROTTLING		CONFIG_BLK_DEV_THROTTLING
	- Enable block device throttling support in block layer.		Enable block device throttling support in block layer.

	Details of cgroup files		Details of cgroup files
	=======================		=======================

	Proportional weight policy files		Proportional weight policy files
	--------------------------------		--------------------------------
	- blkio.weight
	- Specifies per cgroup weight. This is default weight of the group		blkio.weight
			Specifies per cgroup weight. This is default weight of the group
	on all the devices until and unless overridden by per device rule.		on all the devices until and unless overridden by per device rule.
	(See blkio.weight_device).		(See blkio.weight_device).
	Currently allowed range of weights is from 10 to 1000.		Currently allowed range of weights is from 10 to 1000.

	- blkio.weight_device		blkio.weight_device
	- One can specify per cgroup per device rules using this interface.		One can specify per cgroup per device rules using this interface.
	These rules override the default value of group weight as specified		These rules override the default value of group weight as specified
	by blkio.weight.		by blkio.weight.

	@@ -130,34 +134,34 @@ Proportional weight policy files
	dev weight		dev weight
	8:16 300		8:16 300

	- blkio.time		blkio.time
	- disk time allocated to cgroup per device in milliseconds. First		Disk time allocated to cgroup per device in milliseconds. First
	two fields specify the major and minor number of the device and		two fields specify the major and minor number of the device and
	third field specifies the disk time allocated to group in		third field specifies the disk time allocated to group in
	milliseconds.		milliseconds.

	- blkio.sectors		blkio.sectors
	- number of sectors transferred to/from disk by the group. First		Number of sectors transferred to/from disk by the group. First
	two fields specify the major and minor number of the device and		two fields specify the major and minor number of the device and
	third field specifies the number of sectors transferred by the		third field specifies the number of sectors transferred by the
	group to/from the device.		group to/from the device.

	- blkio.io_service_bytes		blkio.io_service_bytes
	- Number of bytes transferred to/from the disk by the group. These		Number of bytes transferred to/from the disk by the group. These
	are further divided by the type of operation - read or write, sync		are further divided by the type of operation - read or write, sync
	or async. First two fields specify the major and minor number of the		or async. First two fields specify the major and minor number of the
	device, third field specifies the operation type and the fourth field		device, third field specifies the operation type and the fourth field
	specifies the number of bytes.		specifies the number of bytes.

	- blkio.io_serviced		blkio.io_serviced
	- Number of IOs (bio) issued to the disk by the group. These		Number of IOs (bio) issued to the disk by the group. These
	are further divided by the type of operation - read or write, sync		are further divided by the type of operation - read or write, sync
	or async. First two fields specify the major and minor number of the		or async. First two fields specify the major and minor number of the
	device, third field specifies the operation type and the fourth field		device, third field specifies the operation type and the fourth field
	specifies the number of IOs.		specifies the number of IOs.

	- blkio.io_service_time		blkio.io_service_time
	- Total amount of time between request dispatch and request completion		Total amount of time between request dispatch and request completion
	for the IOs done by this cgroup. This is in nanoseconds to make it		for the IOs done by this cgroup. This is in nanoseconds to make it
	meaningful for flash devices too. For devices with queue depth of 1,		meaningful for flash devices too. For devices with queue depth of 1,
	this time represents the actual service time. When queue_depth > 1,		this time represents the actual service time. When queue_depth > 1,
	@@ -170,8 +174,8 @@ Proportional weight policy files
	specifies the operation type and the fourth field specifies the		specifies the operation type and the fourth field specifies the
	io_service_time in ns.		io_service_time in ns.

	- blkio.io_wait_time		blkio.io_wait_time
	- Total amount of time the IOs for this cgroup spent waiting in the		Total amount of time the IOs for this cgroup spent waiting in the
	scheduler queues for service. This can be greater than the total time		scheduler queues for service. This can be greater than the total time
	elapsed since it is cumulative io_wait_time for all IOs. It is not a		elapsed since it is cumulative io_wait_time for all IOs. It is not a
	measure of total time the cgroup spent waiting but rather a measure of		measure of total time the cgroup spent waiting but rather a measure of
	@@ -185,24 +189,24 @@ Proportional weight policy files
	minor number of the device, third field specifies the operation type		minor number of the device, third field specifies the operation type
	and the fourth field specifies the io_wait_time in ns.		and the fourth field specifies the io_wait_time in ns.

	- blkio.io_merged		blkio.io_merged
	- Total number of bios/requests merged into requests belonging to this		Total number of bios/requests merged into requests belonging to this
	cgroup. This is further divided by the type of operation - read or		cgroup. This is further divided by the type of operation - read or
	write, sync or async.		write, sync or async.

	- blkio.io_queued		blkio.io_queued
	- Total number of requests queued up at any given instant for this		Total number of requests queued up at any given instant for this
	cgroup. This is further divided by the type of operation - read or		cgroup. This is further divided by the type of operation - read or
	write, sync or async.		write, sync or async.

	- blkio.avg_queue_size		blkio.avg_queue_size
	- Debugging aid only enabled if CONFIG_BFQ_CGROUP_DEBUG=y.		Debugging aid only enabled if CONFIG_BFQ_CGROUP_DEBUG=y.
	The average queue size for this cgroup over the entire time of this		The average queue size for this cgroup over the entire time of this
	cgroup's existence. Queue size samples are taken each time one of the		cgroup's existence. Queue size samples are taken each time one of the
	queues of this cgroup gets a timeslice.		queues of this cgroup gets a timeslice.

	- blkio.group_wait_time		blkio.group_wait_time
	- Debugging aid only enabled if CONFIG_BFQ_CGROUP_DEBUG=y.		Debugging aid only enabled if CONFIG_BFQ_CGROUP_DEBUG=y.
	This is the amount of time the cgroup had to wait since it became busy		This is the amount of time the cgroup had to wait since it became busy
	(i.e., went from 0 to 1 request queued) to get a timeslice for one of		(i.e., went from 0 to 1 request queued) to get a timeslice for one of
	its queues. This is different from the io_wait_time which is the		its queues. This is different from the io_wait_time which is the
	@@ -212,8 +216,8 @@ Proportional weight policy files
	will only report the group_wait_time accumulated till the last time it		will only report the group_wait_time accumulated till the last time it
	got a timeslice and will not include the current delta.		got a timeslice and will not include the current delta.

	- blkio.empty_time		blkio.empty_time
	- Debugging aid only enabled if CONFIG_BFQ_CGROUP_DEBUG=y.		Debugging aid only enabled if CONFIG_BFQ_CGROUP_DEBUG=y.
	This is the amount of time a cgroup spends without any pending		This is the amount of time a cgroup spends without any pending
	requests when not being served, i.e., it does not include any time		requests when not being served, i.e., it does not include any time
	spent idling for one of the queues of the cgroup. This is in		spent idling for one of the queues of the cgroup. This is in
	@@ -221,8 +225,8 @@ Proportional weight policy files
	the stat will only report the empty_time accumulated till the last		the stat will only report the empty_time accumulated till the last
	time it had a pending request and will not include the current delta.		time it had a pending request and will not include the current delta.

	- blkio.idle_time		blkio.idle_time
	- Debugging aid only enabled if CONFIG_BFQ_CGROUP_DEBUG=y.		Debugging aid only enabled if CONFIG_BFQ_CGROUP_DEBUG=y.
	This is the amount of time spent by the IO scheduler idling for a		This is the amount of time spent by the IO scheduler idling for a
	given cgroup in anticipation of a better request than the existing ones		given cgroup in anticipation of a better request than the existing ones
	from other queues/cgroups. This is in nanoseconds. If this is read		from other queues/cgroups. This is in nanoseconds. If this is read
	@@ -230,43 +234,43 @@ Proportional weight policy files
	idle_time accumulated till the last idle period and will not include		idle_time accumulated till the last idle period and will not include
	the current delta.		the current delta.

	- blkio.dequeue		blkio.dequeue
	- Debugging aid only enabled if CONFIG_BFQ_CGROUP_DEBUG=y. This		Debugging aid only enabled if CONFIG_BFQ_CGROUP_DEBUG=y. This
	gives the statistics about how many a times a group was dequeued		gives the statistics about how many a times a group was dequeued
	from service tree of the device. First two fields specify the major		from service tree of the device. First two fields specify the major
	and minor number of the device and third field specifies the number		and minor number of the device and third field specifies the number
	of times a group was dequeued from a particular device.		of times a group was dequeued from a particular device.

	- blkio.*_recursive		blkio.*_recursive
	- Recursive version of various stats. These files show the		Recursive version of various stats. These files show the
	same information as their non-recursive counterparts but		same information as their non-recursive counterparts but
	include stats from all the descendant cgroups.		include stats from all the descendant cgroups.

	Throttling/Upper limit policy files		Throttling/Upper limit policy files
	-----------------------------------		-----------------------------------
	- blkio.throttle.read_bps_device		blkio.throttle.read_bps_device
	- Specifies upper limit on READ rate from the device. IO rate is		Specifies upper limit on READ rate from the device. IO rate is
	specified in bytes per second. Rules are per device. Following is		specified in bytes per second. Rules are per device. Following is
	the format::		the format::

	echo "<major>:<minor> <rate_bytes_per_second>" > /cgrp/blkio.throttle.read_bps_device		echo "<major>:<minor> <rate_bytes_per_second>" > /cgrp/blkio.throttle.read_bps_device

	- blkio.throttle.write_bps_device		blkio.throttle.write_bps_device
	- Specifies upper limit on WRITE rate to the device. IO rate is		Specifies upper limit on WRITE rate to the device. IO rate is
	specified in bytes per second. Rules are per device. Following is		specified in bytes per second. Rules are per device. Following is
	the format::		the format::

	echo "<major>:<minor> <rate_bytes_per_second>" > /cgrp/blkio.throttle.write_bps_device		echo "<major>:<minor> <rate_bytes_per_second>" > /cgrp/blkio.throttle.write_bps_device

	- blkio.throttle.read_iops_device		blkio.throttle.read_iops_device
	- Specifies upper limit on READ rate from the device. IO rate is		Specifies upper limit on READ rate from the device. IO rate is
	specified in IO per second. Rules are per device. Following is		specified in IO per second. Rules are per device. Following is
	the format::		the format::

	echo "<major>:<minor> <rate_io_per_second>" > /cgrp/blkio.throttle.read_iops_device		echo "<major>:<minor> <rate_io_per_second>" > /cgrp/blkio.throttle.read_iops_device

	- blkio.throttle.write_iops_device		blkio.throttle.write_iops_device
	- Specifies upper limit on WRITE rate to the device. IO rate is		Specifies upper limit on WRITE rate to the device. IO rate is
	specified in io per second. Rules are per device. Following is		specified in io per second. Rules are per device. Following is
	the format::		the format::

	@@ -275,15 +279,15 @@ Throttling/Upper limit policy files
	Note: If both BW and IOPS rules are specified for a device, then IO is		Note: If both BW and IOPS rules are specified for a device, then IO is
	subjected to both the constraints.		subjected to both the constraints.

	- blkio.throttle.io_serviced		blkio.throttle.io_serviced
	- Number of IOs (bio) issued to the disk by the group. These		Number of IOs (bio) issued to the disk by the group. These
	are further divided by the type of operation - read or write, sync		are further divided by the type of operation - read or write, sync
	or async. First two fields specify the major and minor number of the		or async. First two fields specify the major and minor number of the
	device, third field specifies the operation type and the fourth field		device, third field specifies the operation type and the fourth field
	specifies the number of IOs.		specifies the number of IOs.

	- blkio.throttle.io_service_bytes		blkio.throttle.io_service_bytes
	- Number of bytes transferred to/from the disk by the group. These		Number of bytes transferred to/from the disk by the group. These
	are further divided by the type of operation - read or write, sync		are further divided by the type of operation - read or write, sync
	or async. First two fields specify the major and minor number of the		or async. First two fields specify the major and minor number of the
	device, third field specifies the operation type and the fourth field		device, third field specifies the operation type and the fourth field
	@@ -291,6 +295,6 @@ Note: If both BW and IOPS rules are specified for a device, then IO is

	Common files among various policies		Common files among various policies
	-----------------------------------		-----------------------------------
	- blkio.reset_stats		blkio.reset_stats
	- Writing an int to this file will result in resetting all the stats		Writing an int to this file will result in resetting all the stats
	for that cgroup.		for that cgroup.