Commit 39443104 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab
Browse files

docs: blockdev: convert to ReST 



Rename the blockdev documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.

The drbd sub-directory contains some graphs and data flows.
Add those too to the documentation.

At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+samsung@kernel.org>
parent e0ae1544

Documentation/admin-guide/kernel-parameters.txt

+9 −9
Original line number Diff line number Diff line
@@ -1249,7 +1249,7 @@ 
			See also Documentation/fault-injection/.



	floppy=		[HW]

			See Documentation/blockdev/floppy.txt.

			See Documentation/blockdev/floppy.rst.



	force_pal_cache_flush

			[IA-64] Avoid check_sal_cache_flush which may hang on
@@ -2234,7 +2234,7 @@ 
	memblock=debug	[KNL] Enable memblock debug messages.



	load_ramdisk=	[RAM] List of ramdisks to load from floppy

			See Documentation/blockdev/ramdisk.txt.

			See Documentation/blockdev/ramdisk.rst.



	lockd.nlm_grace_period=P  [NFS] Assign grace period.

			Format: <integer>
@@ -3268,7 +3268,7 @@ 


	pcd.		[PARIDE]

			See header of drivers/block/paride/pcd.c.

			See also Documentation/blockdev/paride.txt.

			See also Documentation/blockdev/paride.rst.



	pci=option[,option...]	[PCI] various PCI subsystem options.
@@ -3512,7 +3512,7 @@ 
			needed on a platform with proper driver support.



	pd.		[PARIDE]

			See Documentation/blockdev/paride.txt.

			See Documentation/blockdev/paride.rst.



	pdcchassis=	[PARISC,HW] Disable/Enable PDC Chassis Status codes at

			boot time.
@@ -3527,10 +3527,10 @@ 
			and performance comparison.



	pf.		[PARIDE]

			See Documentation/blockdev/paride.txt.

			See Documentation/blockdev/paride.rst.



	pg.		[PARIDE]

			See Documentation/blockdev/paride.txt.

			See Documentation/blockdev/paride.rst.



	pirq=		[SMP,APIC] Manual mp-table setup

			See Documentation/x86/i386/IO-APIC.rst.
@@ -3642,7 +3642,7 @@ 


	prompt_ramdisk=	[RAM] List of RAM disks to prompt for floppy disk

			before loading.

			See Documentation/blockdev/ramdisk.txt.

			See Documentation/blockdev/ramdisk.rst.



	psi=		[KNL] Enable or disable pressure stall information

			tracking.
@@ -3664,7 +3664,7 @@ 
	pstore.backend=	Specify the name of the pstore backend to use



	pt.		[PARIDE]

			See Documentation/blockdev/paride.txt.

			See Documentation/blockdev/paride.rst.



	pti=		[X86_64] Control Page Table Isolation of user and

			kernel address spaces.  Disabling this feature
@@ -3693,7 +3693,7 @@ 
			See Documentation/admin-guide/md.rst.



	ramdisk_size=	[RAM] Sizes of RAM disks in kilobytes

			See Documentation/blockdev/ramdisk.txt.

			See Documentation/blockdev/ramdisk.rst.



	random.trust_cpu={on,off}

			[KNL] Enable or disable trusting the use of the

Documentation/blockdev/drbd/data-structure-v9.txt→Documentation/blockdev/drbd/data-structure-v9.rst

+5 −1
Original line number Diff line number Diff line 
================================

kernel data structure for DRBD-9

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



This describes the in kernel data structure for DRBD-9. Starting with

Linux v3.14 we are reorganizing DRBD to use this data structure.
@@ -10,7 +14,7 @@ device is represented by a block device locally. 


The DRBD objects are interconnected to form a matrix as depicted below; a

drbd_peer_device object sits at each intersection between a drbd_device and a

drbd_connection:

drbd_connection::



  /--------------+---------------+.....+---------------\

  |   resource   |    device     |     |    device     |

Documentation/blockdev/drbd/figures.rst

0 → 100644
+28 −0
Original line number Diff line number Diff line 
.. The here included files are intended to help understand the implementation



Data flows that Relate some functions, and write packets

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



.. kernel-figure:: DRBD-8.3-data-packets.svg

    :alt:   DRBD-8.3-data-packets.svg

    :align: center



.. kernel-figure:: DRBD-data-packets.svg

    :alt:   DRBD-data-packets.svg

    :align: center





Sub graphs of DRBD's state transitions

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



.. kernel-figure:: conn-states-8.dot

    :alt:   conn-states-8.dot

    :align: center



.. kernel-figure:: disk-states-8.dot

    :alt:   disk-states-8.dot

    :align: center



.. kernel-figure:: node-states-8.dot

    :alt:   node-states-8.dot

    :align: center

Documentation/blockdev/drbd/README.txt→Documentation/blockdev/drbd/index.rst

+9 −6
Original line number Diff line number Diff line 
==========================================

Distributed Replicated Block Device - DRBD

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



Description

===========



  DRBD is a shared-nothing, synchronously replicated block device. It

  is designed to serve as a building block for high availability
@@ -7,10 +12,8 @@ Description 


  Please visit http://www.drbd.org to find out more.



The here included files are intended to help understand the implementation



DRBD-8.3-data-packets.svg, DRBD-data-packets.svg  

  relates some functions, and write packets.

.. toctree::

   :maxdepth: 1



conn-states-8.dot, disk-states-8.dot, node-states-8.dot

  The sub graphs of DRBD's state transitions
 
   data-structure-v9

   figures

Documentation/blockdev/floppy.txt→Documentation/blockdev/floppy.rst

+49 −39
Original line number Diff line number Diff line 
This file describes the floppy driver.

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

Floppy Driver

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



FAQ list:

=========
@@ -15,16 +17,16 @@ lilo. This option can be typed at the boot prompt, or entered in the 
lilo configuration file.



Example: If your kernel is called linux-2.6.9, type the following line

at the lilo boot prompt (if you have a thinkpad):

at the lilo boot prompt (if you have a thinkpad)::



 linux-2.6.9 floppy=thinkpad



You may also enter the following line in /etc/lilo.conf, in the description

of linux-2.6.9:

of linux-2.6.9::



 append = "floppy=thinkpad"



 Several floppy related options may be given, example:

Several floppy related options may be given, example::



 linux-2.6.9 floppy=daring floppy=two_fdc

 append = "floppy=daring floppy=two_fdc"
@@ -38,14 +40,16 @@ restore the default behavior. 
Module configuration options

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



 If you use the floppy driver as a module, use the following syntax:

If you use the floppy driver as a module, use the following syntax::



	modprobe floppy floppy="<options>"



Example:

Example::



	modprobe floppy floppy="omnibook messages"



If you need certain options enabled every time you load the floppy driver,

you can put:

you can put::



	options floppy floppy="omnibook messages"
@@ -70,8 +74,7 @@ in a configuration file in /etc/modprobe.d/. 
	Tells the floppy driver that you have only one floppy controller.

	(default)



 floppy=two_fdc

 floppy=<address>,two_fdc

 floppy=two_fdc / floppy=<address>,two_fdc

	Tells the floppy driver that you have two floppy controllers.

	The second floppy controller is assumed to be at <address>.

	This option is not needed if the second controller is at address
@@ -84,8 +87,7 @@ in a configuration file in /etc/modprobe.d/. 
 floppy=0,thinkpad

	Tells the floppy driver that you don't have a Thinkpad.



 floppy=omnibook

 floppy=nodma

 floppy=omnibook / floppy=nodma

	Tells the floppy driver not to use Dma for data transfers.

	This is needed on HP Omnibooks, which don't have a workable

	DMA channel for the floppy driver. This option is also useful
@@ -144,14 +146,16 @@ in a configuration file in /etc/modprobe.d/. 
	described in the physical CMOS), or if your BIOS uses

	non-standard CMOS types. The CMOS types are:



		0 - Use the value of the physical CMOS

		1 - 5 1/4 DD

		2 - 5 1/4 HD

		3 - 3 1/2 DD

		4 - 3 1/2 HD

		5 - 3 1/2 ED

		6 - 3 1/2 ED

	       16 - unknown or not installed

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

		0  Use the value of the physical CMOS

		1  5 1/4 DD

		2  5 1/4 HD

		3  3 1/2 DD

		4  3 1/2 HD

		5  3 1/2 ED

		6  3 1/2 ED

	       16  unknown or not installed

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



	(Note: there are two valid types for ED drives. This is because 5 was

	initially chosen to represent floppy *tapes*, and 6 for ED drives.
@@ -162,8 +166,7 @@ in a configuration file in /etc/modprobe.d/. 
	Print a warning message when an unexpected interrupt is received.

	(default)



 floppy=no_unexpected_interrupts

 floppy=L40SX

 floppy=no_unexpected_interrupts / floppy=L40SX

	Don't print a message when an unexpected interrupt is received. This

	is needed on IBM L40SX laptops in certain video modes. (There seems

	to be an interaction between video and floppy. The unexpected
@@ -199,10 +202,11 @@ in a configuration file in /etc/modprobe.d/. 
	Sets the floppy DMA channel to <nr> instead of 2.



 floppy=slow

	Use PS/2 stepping rate:

	 " PS/2 floppies have much slower step rates than regular floppies.

	Use PS/2 stepping rate::



	   PS/2 floppies have much slower step rates than regular floppies.

	   It's been recommended that take about 1/4 of the default speed

	   in some more extreme cases."

	   in some more extreme cases.





Supporting utilities and additional documentation:
@@ -215,11 +219,15 @@ access high capacity disks (up to 1992K on a high density 3 1/2 disk!). 
It also contains additional documentation about the floppy driver.



The latest version can be found at fdutils homepage:



 http://fdutils.linux.lu



The fdutils releases can be found at:



 http://fdutils.linux.lu/download.html



 http://www.tux.org/pub/knaff/fdutils/



 ftp://metalab.unc.edu/pub/Linux/utils/disk-management/



Reporting problems about the floppy driver
@@ -239,7 +247,9 @@ sure to mention also the type of the filesystem in the subject line. 
Changelog

=========



10-30-2004 :	Cleanup, updating, add reference to module configuration.

10-30-2004 :

		Cleanup, updating, add reference to module configuration.

		James Nelson <james4765@gmail.com>



6-3-2000 :	Original Document
 
6-3-2000 :

		Original Document

CRA Git | Maintained and supported by SUSTech CRA and CCSE