* Re: [PATCH v1 20/22] docs: extcon: move it to acpi dir and convert it to ReST
From: Rafael J. Wysocki @ 2019-06-19 10:02 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab,
Linux Kernel Mailing List, Jonathan Corbet, MyungJoo Ham,
Chanwoo Choi, Len Brown, ACPI Devel Maling List
In-Reply-To: <4701210.Ilfu9VLqBR@kreacher>
On Wed, Jun 19, 2019 at 11:59 AM Rafael J. Wysocki <rjw@rjwysocki.net> wrote:
>
> On Tuesday, June 18, 2019 11:05:44 PM CEST Mauro Carvalho Chehab wrote:
> > The intel-int3496.txt file is a documentation for an ACPI driver.
> >
> > There's no reason to keep it on a separate directory.
> >
> > So, instead of keeping it on some random location, move it
> > to a sub-directory inside the ACPI documentation dir.
> >
> > For now, keep it with .txt extension, in order to avoid
> > Sphinx build noise. A later patch should change it to .rst
> > and movin it to be together with other acpi docs.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
>
> Acked-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
Which said, the changelog appears to be outdated, because the format
of the doc *does* change.
> > ---
> > .../acpi/extcon-intel-int3496.rst} | 14 ++++++++++----
> > Documentation/firmware-guide/acpi/index.rst | 1 +
> > MAINTAINERS | 6 +++---
> > 3 files changed, 14 insertions(+), 7 deletions(-)
> > rename Documentation/{extcon/intel-int3496.txt => firmware-guide/acpi/extcon-intel-int3496.rst} (66%)
> >
> > diff --git a/Documentation/extcon/intel-int3496.txt b/Documentation/firmware-guide/acpi/extcon-intel-int3496.rst
^ permalink raw reply
* Re: [PATCH v1 20/22] docs: extcon: move it to acpi dir and convert it to ReST
From: Rafael J. Wysocki @ 2019-06-19 9:59 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, MyungJoo Ham, Chanwoo Choi, Len Brown,
linux-acpi
In-Reply-To: <b6d199c3e7c8c868acbb313a1a516ea8aed042ee.1560891322.git.mchehab+samsung@kernel.org>
On Tuesday, June 18, 2019 11:05:44 PM CEST Mauro Carvalho Chehab wrote:
> The intel-int3496.txt file is a documentation for an ACPI driver.
>
> There's no reason to keep it on a separate directory.
>
> So, instead of keeping it on some random location, move it
> to a sub-directory inside the ACPI documentation dir.
>
> For now, keep it with .txt extension, in order to avoid
> Sphinx build noise. A later patch should change it to .rst
> and movin it to be together with other acpi docs.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
Or please let me know if you want me to pick up this one.
> ---
> .../acpi/extcon-intel-int3496.rst} | 14 ++++++++++----
> Documentation/firmware-guide/acpi/index.rst | 1 +
> MAINTAINERS | 6 +++---
> 3 files changed, 14 insertions(+), 7 deletions(-)
> rename Documentation/{extcon/intel-int3496.txt => firmware-guide/acpi/extcon-intel-int3496.rst} (66%)
>
> diff --git a/Documentation/extcon/intel-int3496.txt b/Documentation/firmware-guide/acpi/extcon-intel-int3496.rst
> similarity index 66%
> rename from Documentation/extcon/intel-int3496.txt
> rename to Documentation/firmware-guide/acpi/extcon-intel-int3496.rst
> index 8155dbc7fad3..5137ca834b54 100644
> --- a/Documentation/extcon/intel-int3496.txt
> +++ b/Documentation/firmware-guide/acpi/extcon-intel-int3496.rst
> @@ -1,5 +1,6 @@
> +=====================================================
> Intel INT3496 ACPI device extcon driver documentation
> ------------------------------------------------------
> +=====================================================
>
> The Intel INT3496 ACPI device extcon driver is a driver for ACPI
> devices with an acpi-id of INT3496, such as found for example on
> @@ -13,15 +14,20 @@ between an USB host and an USB peripheral controller.
> The ACPI devices exposes this functionality by returning an array with up
> to 3 gpio descriptors from its ACPI _CRS (Current Resource Settings) call:
>
> -Index 0: The input gpio for the id-pin, this is always present and valid
> -Index 1: The output gpio for enabling Vbus output from the device to the otg
> +======= =====================================================================
> +Index 0 The input gpio for the id-pin, this is always present and valid
> +Index 1 The output gpio for enabling Vbus output from the device to the otg
> port, write 1 to enable the Vbus output (this gpio descriptor may
> be absent or invalid)
> -Index 2: The output gpio for muxing of the data pins between the USB host and
> +Index 2 The output gpio for muxing of the data pins between the USB host and
> the USB peripheral controller, write 1 to mux to the peripheral
> controller
> +======= =====================================================================
>
> There is a mapping between indices and GPIO connection IDs as follows
> +
> + ======= =======
> id index 0
> vbus index 1
> mux index 2
> + ======= =======
> diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
> index ae609eec4679..90c90d42d9ad 100644
> --- a/Documentation/firmware-guide/acpi/index.rst
> +++ b/Documentation/firmware-guide/acpi/index.rst
> @@ -24,3 +24,4 @@ ACPI Support
> acpi-lid
> lpit
> video_extension
> + extcon-intel-int3496
> diff --git a/MAINTAINERS b/MAINTAINERS
> index e07cbd44d48a..b7c81bd0f8e8 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -321,7 +321,7 @@ F: drivers/pnp/pnpacpi/
> F: include/linux/acpi.h
> F: include/linux/fwnode.h
> F: include/acpi/
> -F: Documentation/acpi/
> +F: Documentation/firmware-guide/acpi/
> F: Documentation/ABI/testing/sysfs-bus-acpi
> F: Documentation/ABI/testing/configfs-acpi
> F: drivers/pci/*acpi*
> @@ -4881,7 +4881,7 @@ S: Maintained
> F: Documentation/
> F: scripts/kernel-doc
> X: Documentation/ABI/
> -X: Documentation/acpi/
> +X: Documentation/firmware-guide/acpi/
> X: Documentation/devicetree/
> X: Documentation/i2c/
> X: Documentation/media/
> @@ -6057,7 +6057,7 @@ S: Maintained
> F: drivers/extcon/
> F: include/linux/extcon/
> F: include/linux/extcon.h
> -F: Documentation/extcon/
> +F: Documentation/firmware-guide/acpi/extcon-intel-int3496.rst
> F: Documentation/devicetree/bindings/extcon/
>
> EXYNOS DP DRIVER
>
^ permalink raw reply
* Re: [PATCH v1 02/22] docs: ioctl-number.txt: convert it to ReST format
From: Federico Vaga @ 2019-06-19 7:32 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Harry Wei, Alex Shi, Doug Ledford,
Jason Gunthorpe, linux-rdma
In-Reply-To: <e8f1c925c5d118717eb38455e8f9dacf340cc35e.1560891322.git.mchehab+samsung@kernel.org>
On Tuesday, June 18, 2019 11:05:26 PM CEST Mauro Carvalho Chehab wrote:
> The conversion itself is simple: add a markup for the
> title of this file and add markups for both tables.
>
> Yet, the big table here with IOCTL numbers is badly formatted:
> on several lines, the "Include File" column has some values that
> are bigger than the reserved space there.
>
> Also, on several places, a comment was misplaced at the "Include
> File" space.
>
> So, most of the work here is to actually ensure that each field
> will be properly fixed.
>
> Also worth to mention that some URLs have the asterisk character
> on it. Well, Sphinx has an issue with asterisks in the middle
> of an string. As this is URL, use the alternate format: %2A.
>
> As a side effect of this patch, it is now a lot easier to see that
> some reserved ioctl numbers are missing the include files
> where it is supposed to be used.
>
> PS.: While this is part of a subdir, I opted to convert this
> single file alone, as this file has a potential of conflicts,
> as most subsystem maintainers touch it.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
> .../{ioctl-number.txt => ioctl-number.rst} | 588 +++++++++---------
> Documentation/process/submit-checklist.rst | 2 +-
> .../it_IT/process/submit-checklist.rst | 2 +-
> .../zh_CN/process/submit-checklist.rst | 2 +-
> include/uapi/rdma/rdma_user_ioctl_cmds.h | 2 +-
Acked-by: Federico Vaga <federico.vaga@vaga.pv.it>
--
Federico Vaga
http://www.federicovaga.it/
^ permalink raw reply
* Re: [PATCH v1 14/22] docs: usb: rename files to .rst and add them to drivers-api
From: Greg Kroah-Hartman @ 2019-06-19 6:47 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Oliver Neukum, Alan Stern, Johan Hovold,
Valentina Manea, Shuah Khan, Felipe Balbi, linux-usb
In-Reply-To: <c05aecb424e4f835e3f7872ecb5818e1d2f3267c.1560891322.git.mchehab+samsung@kernel.org>
On Tue, Jun 18, 2019 at 06:05:38PM -0300, Mauro Carvalho Chehab wrote:
> While there are a mix of things here, most of the stuff
> were written from Kernel developer's PoV. So, add them to
> the driver-api book.
>
> A follow up for this patch would be to move documents from
> there that are specific to sysadmins, adding them to the
> admin-guide.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Ah, I guess I can take this through my tree, will do that later today.
thanks,
greg k-h
^ permalink raw reply
* Re: [PATCH v1 14/22] docs: usb: rename files to .rst and add them to drivers-api
From: Greg Kroah-Hartman @ 2019-06-19 6:46 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Oliver Neukum, Alan Stern, Johan Hovold,
Valentina Manea, Shuah Khan, Felipe Balbi, linux-usb
In-Reply-To: <c05aecb424e4f835e3f7872ecb5818e1d2f3267c.1560891322.git.mchehab+samsung@kernel.org>
On Tue, Jun 18, 2019 at 06:05:38PM -0300, Mauro Carvalho Chehab wrote:
> While there are a mix of things here, most of the stuff
> were written from Kernel developer's PoV. So, add them to
> the driver-api book.
>
> A follow up for this patch would be to move documents from
> there that are specific to sysadmins, adding them to the
> admin-guide.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
^ permalink raw reply
* Re: [PATCH v1 14/22] docs: usb: rename files to .rst and add them to drivers-api
From: Felipe Balbi @ 2019-06-19 6:23 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Greg Kroah-Hartman, Oliver Neukum, Alan Stern,
Johan Hovold, Valentina Manea, Shuah Khan, linux-usb
In-Reply-To: <c05aecb424e4f835e3f7872ecb5818e1d2f3267c.1560891322.git.mchehab+samsung@kernel.org>
[-- Attachment #1: Type: text/plain, Size: 490 bytes --]
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> writes:
> While there are a mix of things here, most of the stuff
> were written from Kernel developer's PoV. So, add them to
> the driver-api book.
>
> A follow up for this patch would be to move documents from
> there that are specific to sysadmins, adding them to the
> admin-guide.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Felipe Balbi <felipe.balbi@linux.intel.com>
--
balbi
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]
^ permalink raw reply
* [PATCH] docs: fb: Add TER16x32 to the available font names
From: Takashi Iwai @ 2019-06-19 5:39 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Bartlomiej Zolnierkiewicz, Randy Dunlap, Greg Kroah-Hartman,
linux-doc, linux-fbdev, linux-kernel
The new font is available since recently.
Signed-off-by: Takashi Iwai <tiwai@suse.de>
---
Documentation/fb/fbcon.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/fb/fbcon.rst b/Documentation/fb/fbcon.rst
index cfb9f7c38f18..1da65b9000de 100644
--- a/Documentation/fb/fbcon.rst
+++ b/Documentation/fb/fbcon.rst
@@ -82,7 +82,7 @@ C. Boot options
Select the initial font to use. The value 'name' can be any of the
compiled-in fonts: 10x18, 6x10, 7x14, Acorn8x8, MINI4x6,
- PEARL8x8, ProFont6x11, SUN12x22, SUN8x16, VGA8x16, VGA8x8.
+ PEARL8x8, ProFont6x11, SUN12x22, SUN8x16, TER16x32, VGA8x16, VGA8x8.
Note, not all drivers can handle font with widths not divisible by 8,
such as vga16fb.
--
2.16.4
^ permalink raw reply related
* Re: [PATCH v4 23/28] docs: target: convert docs to ReST and rename to *.rst
From: Martin K. Petersen @ 2019-06-19 3:38 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Martin K. Petersen, linux-scsi, target-devel
In-Reply-To: <9c58d2f3478126736e69b688a7dbf0da26ba2285.1560361364.git.mchehab+samsung@kernel.org>
Mauro,
> Convert the TCM docs to ReST format and add them to the
> bookset.
Looks good to me.
Acked-by: Martin K. Petersen <martin.petersen@oracle.com>
--
Martin K. Petersen Oracle Linux Engineering
^ permalink raw reply
* Re: [PATCH v2 02/29] docs: lcd-panel-cgram.txt: convert docs to ReST and rename to *.rst
From: Mauro Carvalho Chehab @ 2019-06-18 23:14 UTC (permalink / raw)
To: Miguel Ojeda
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <CANiq72kibf49R+QtUjqcttGiNr4kxBqc0TxSe+HdrQUahTxgng@mail.gmail.com>
Em Tue, 18 Jun 2019 23:14:01 +0200
Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> escreveu:
> On Tue, Jun 18, 2019 at 10:56 PM Mauro Carvalho Chehab
> <mchehab+samsung@kernel.org> wrote:
> >
> > This small text file describes the usage of parallel port LCD
> > displays from userspace PoV. So, a good candidate for the
> > admin guide.
> >
> > While this is not part of the admin-guide book, mark it as
> > :orphan:, in order to avoid build warnings.
>
> If we are going to move everything else to `.rst` too, even things
> outside the guide, then ack.
Yeah, the plan is to move all text files inside Documentation/ to .rst[1].
[1] There are some exceptions: for ABI and features, the current plan
is to have a script that parses their strict formats and produce
a ReST output.
Btw, Still pending to be sent, I have already a patch removing the
:orphan: from this file and adding it to the admin guide:
https://git.linuxtv.org/mchehab/experimental.git/commit/?h=convert_rst_renames_v5.1&id=eae5b48cab115c83be8dd59ee99b9e45f8142134
And the corresponding output, after the patches I currently have:
https://www.infradead.org/~mchehab/rst_conversion/admin-guide/lcd-panel-cgram.html
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH v2 02/29] docs: lcd-panel-cgram.txt: convert docs to ReST and rename to *.rst
From: Miguel Ojeda @ 2019-06-18 21:14 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <3da3e0379da562d703e6896ded6a7839d1272494.1560890800.git.mchehab+samsung@kernel.org>
On Tue, Jun 18, 2019 at 10:56 PM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> This small text file describes the usage of parallel port LCD
> displays from userspace PoV. So, a good candidate for the
> admin guide.
>
> While this is not part of the admin-guide book, mark it as
> :orphan:, in order to avoid build warnings.
If we are going to move everything else to `.rst` too, even things
outside the guide, then ack.
Cheers,
Miguel
^ permalink raw reply
* [PATCH v1 16/22] docs: driver-api: add xilinx driver API documentation
From: Mauro Carvalho Chehab @ 2019-06-18 21:05 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Michal Simek, linux-arm-kernel
In-Reply-To: <cover.1560891322.git.mchehab+samsung@kernel.org>
The current file there (emmi) provides a description of
the driver uAPI and kAPI.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/driver-api/index.rst | 1 +
Documentation/{ => driver-api}/xilinx/eemi.rst | 0
Documentation/{ => driver-api}/xilinx/index.rst | 1 -
3 files changed, 1 insertion(+), 1 deletion(-)
rename Documentation/{ => driver-api}/xilinx/eemi.rst (100%)
rename Documentation/{ => driver-api}/xilinx/index.rst (94%)
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index 492b96003af2..6935d973ff5b 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -124,6 +124,7 @@ available subsections can be seen below.
unaligned-memory-access
vfio
vfio-mediated-device
+ xilinx/index
xillybus
xz
zorro
diff --git a/Documentation/xilinx/eemi.rst b/Documentation/driver-api/xilinx/eemi.rst
similarity index 100%
rename from Documentation/xilinx/eemi.rst
rename to Documentation/driver-api/xilinx/eemi.rst
diff --git a/Documentation/xilinx/index.rst b/Documentation/driver-api/xilinx/index.rst
similarity index 94%
rename from Documentation/xilinx/index.rst
rename to Documentation/driver-api/xilinx/index.rst
index 01cc1a0714df..13f7589ed442 100644
--- a/Documentation/xilinx/index.rst
+++ b/Documentation/driver-api/xilinx/index.rst
@@ -1,4 +1,3 @@
-:orphan:
===========
Xilinx FPGA
--
2.21.0
^ permalink raw reply related
* [PATCH v1 17/22] docs: add arch doc directories to the index
From: Mauro Carvalho Chehab @ 2019-06-18 21:05 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Catalin Marinas, Will Deacon, Palmer Dabbelt,
Albert Ou, Heiko Carstens, Vasily Gorbik, Christian Borntraeger,
linux-arm-kernel, linux-riscv, linux-s390
In-Reply-To: <cover.1560891322.git.mchehab+samsung@kernel.org>
Now that several arch documents were converted to ReST,
add their indexes to Documentation/index.rst and remove the
:orphan: from them.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/arm/index.rst | 2 --
Documentation/arm64/index.rst | 2 --
Documentation/ia64/index.rst | 2 --
Documentation/index.rst | 10 ++++++++++
Documentation/m68k/index.rst | 2 --
Documentation/riscv/index.rst | 2 --
Documentation/s390/index.rst | 2 --
Documentation/sparc/index.rst | 2 --
Documentation/xtensa/index.rst | 2 --
9 files changed, 10 insertions(+), 16 deletions(-)
diff --git a/Documentation/arm/index.rst b/Documentation/arm/index.rst
index bd316d1a1802..9c2f781f4685 100644
--- a/Documentation/arm/index.rst
+++ b/Documentation/arm/index.rst
@@ -1,5 +1,3 @@
-:orphan:
-
================
ARM Architecture
================
diff --git a/Documentation/arm64/index.rst b/Documentation/arm64/index.rst
index 018b7836ecb7..96b696ba4e6c 100644
--- a/Documentation/arm64/index.rst
+++ b/Documentation/arm64/index.rst
@@ -1,5 +1,3 @@
-:orphan:
-
==================
ARM64 Architecture
==================
diff --git a/Documentation/ia64/index.rst b/Documentation/ia64/index.rst
index a3e3052ad6e2..ef99475f672b 100644
--- a/Documentation/ia64/index.rst
+++ b/Documentation/ia64/index.rst
@@ -1,5 +1,3 @@
-:orphan:
-
==================
IA-64 Architecture
==================
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 2f9bf37b8989..82cd9528dff0 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -116,7 +116,17 @@ implementation.
:maxdepth: 2
sh/index
+ arm/index
+ arm64/index
+ ia64/index
+ m68k/index
+ powerpc/index
+ riscv/index
+ s390/index
+ sh/index
+ sparc/index
x86/index
+ xtensa/index
Filesystem Documentation
------------------------
diff --git a/Documentation/m68k/index.rst b/Documentation/m68k/index.rst
index f3273ec075c3..aa121cfcbbd9 100644
--- a/Documentation/m68k/index.rst
+++ b/Documentation/m68k/index.rst
@@ -1,5 +1,3 @@
-:orphan:
-
=================
m68k Architecture
=================
diff --git a/Documentation/riscv/index.rst b/Documentation/riscv/index.rst
index c4b906d9b5a7..e3ca0922a8c2 100644
--- a/Documentation/riscv/index.rst
+++ b/Documentation/riscv/index.rst
@@ -1,5 +1,3 @@
-:orphan:
-
===================
RISC-V architecture
===================
diff --git a/Documentation/s390/index.rst b/Documentation/s390/index.rst
index 1a914da2a07b..4602312909d3 100644
--- a/Documentation/s390/index.rst
+++ b/Documentation/s390/index.rst
@@ -1,5 +1,3 @@
-:orphan:
-
=================
s390 Architecture
=================
diff --git a/Documentation/sparc/index.rst b/Documentation/sparc/index.rst
index 91f7d6643dd5..71cff621f243 100644
--- a/Documentation/sparc/index.rst
+++ b/Documentation/sparc/index.rst
@@ -1,5 +1,3 @@
-:orphan:
-
==================
Sparc Architecture
==================
diff --git a/Documentation/xtensa/index.rst b/Documentation/xtensa/index.rst
index 5a24e365e35f..239c5f0a5c67 100644
--- a/Documentation/xtensa/index.rst
+++ b/Documentation/xtensa/index.rst
@@ -1,5 +1,3 @@
-:orphan:
-
===================
Xtensa Architecture
===================
--
2.21.0
^ permalink raw reply related
* [PATCH v1 07/22] docs: perf: convert to ReST
From: Mauro Carvalho Chehab @ 2019-06-18 21:05 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Shaokun Zhang, Khuong Dinh, Andy Gross,
David Brown, Will Deacon, Mark Rutland, linux-arm-msm,
linux-arm-kernel
In-Reply-To: <cover.1560891322.git.mchehab+samsung@kernel.org>
Rename the perf documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.
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: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../perf/{arm-ccn.txt => arm-ccn.rst} | 18 +++++-----
.../perf/{arm_dsu_pmu.txt => arm_dsu_pmu.rst} | 5 +--
.../perf/{hisi-pmu.txt => hisi-pmu.rst} | 35 +++++++++++--------
Documentation/perf/index.rst | 16 +++++++++
.../perf/{qcom_l2_pmu.txt => qcom_l2_pmu.rst} | 3 +-
.../perf/{qcom_l3_pmu.txt => qcom_l3_pmu.rst} | 3 +-
.../{thunderx2-pmu.txt => thunderx2-pmu.rst} | 25 ++++++-------
.../perf/{xgene-pmu.txt => xgene-pmu.rst} | 3 +-
MAINTAINERS | 4 +--
drivers/perf/qcom_l3_pmu.c | 2 +-
10 files changed, 72 insertions(+), 42 deletions(-)
rename Documentation/perf/{arm-ccn.txt => arm-ccn.rst} (86%)
rename Documentation/perf/{arm_dsu_pmu.txt => arm_dsu_pmu.rst} (92%)
rename Documentation/perf/{hisi-pmu.txt => hisi-pmu.rst} (73%)
create mode 100644 Documentation/perf/index.rst
rename Documentation/perf/{qcom_l2_pmu.txt => qcom_l2_pmu.rst} (94%)
rename Documentation/perf/{qcom_l3_pmu.txt => qcom_l3_pmu.rst} (93%)
rename Documentation/perf/{thunderx2-pmu.txt => thunderx2-pmu.rst} (73%)
rename Documentation/perf/{xgene-pmu.txt => xgene-pmu.rst} (96%)
diff --git a/Documentation/perf/arm-ccn.txt b/Documentation/perf/arm-ccn.rst
similarity index 86%
rename from Documentation/perf/arm-ccn.txt
rename to Documentation/perf/arm-ccn.rst
index 15cdb7bc57c3..832b0c64023a 100644
--- a/Documentation/perf/arm-ccn.txt
+++ b/Documentation/perf/arm-ccn.rst
@@ -1,3 +1,4 @@
+==========================
ARM Cache Coherent Network
==========================
@@ -29,6 +30,7 @@ Crosspoint watchpoint-based events (special "event" value 0xfe)
require "xp" and "vc" as as above plus "port" (device port index),
"dir" (transmit/receive direction), comparator values ("cmp_l"
and "cmp_h") and "mask", being index of the comparator mask.
+
Masks are defined separately from the event description
(due to limited number of the config values) in the "cmp_mask"
directory, with first 8 configurable by user and additional
@@ -44,16 +46,16 @@ request the events on this processor (if not, the perf_event->cpu value
will be overwritten anyway). In case of this processor being offlined,
the events are migrated to another one and the attribute is updated.
-Example of perf tool use:
+Example of perf tool use::
-/ # perf list | grep ccn
- ccn/cycles/ [Kernel PMU event]
-<...>
- ccn/xp_valid_flit,xp=?,port=?,vc=?,dir=?/ [Kernel PMU event]
-<...>
+ / # perf list | grep ccn
+ ccn/cycles/ [Kernel PMU event]
+ <...>
+ ccn/xp_valid_flit,xp=?,port=?,vc=?,dir=?/ [Kernel PMU event]
+ <...>
-/ # perf stat -a -e ccn/cycles/,ccn/xp_valid_flit,xp=1,port=0,vc=1,dir=1/ \
- sleep 1
+ / # perf stat -a -e ccn/cycles/,ccn/xp_valid_flit,xp=1,port=0,vc=1,dir=1/ \
+ sleep 1
The driver does not support sampling, therefore "perf record" will
not work. Per-task (without "-a") perf sessions are not supported.
diff --git a/Documentation/perf/arm_dsu_pmu.txt b/Documentation/perf/arm_dsu_pmu.rst
similarity index 92%
rename from Documentation/perf/arm_dsu_pmu.txt
rename to Documentation/perf/arm_dsu_pmu.rst
index d611e15f5add..7fd34db75d13 100644
--- a/Documentation/perf/arm_dsu_pmu.txt
+++ b/Documentation/perf/arm_dsu_pmu.rst
@@ -1,3 +1,4 @@
+==================================
ARM DynamIQ Shared Unit (DSU) PMU
==================================
@@ -13,7 +14,7 @@ PMU doesn't support process specific events and cannot be used in sampling mode.
The DSU provides a bitmap for a subset of implemented events via hardware
registers. There is no way for the driver to determine if the other events
are available or not. Hence the driver exposes only those events advertised
-by the DSU, in "events" directory under :
+by the DSU, in "events" directory under::
/sys/bus/event_sources/devices/arm_dsu_<N>/
@@ -23,6 +24,6 @@ and use the raw event code for the unlisted events.
The driver also exposes the CPUs connected to the DSU instance in "associated_cpus".
-e.g usage :
+e.g usage::
perf stat -a -e arm_dsu_0/cycles/
diff --git a/Documentation/perf/hisi-pmu.txt b/Documentation/perf/hisi-pmu.rst
similarity index 73%
rename from Documentation/perf/hisi-pmu.txt
rename to Documentation/perf/hisi-pmu.rst
index 267a028b2741..404a5c3d9d00 100644
--- a/Documentation/perf/hisi-pmu.txt
+++ b/Documentation/perf/hisi-pmu.rst
@@ -1,5 +1,7 @@
+======================================================
HiSilicon SoC uncore Performance Monitoring Unit (PMU)
======================================================
+
The HiSilicon SoC chip includes various independent system device PMUs
such as L3 cache (L3C), Hydra Home Agent (HHA) and DDRC. These PMUs are
independent and have hardware logic to gather statistics and performance
@@ -11,11 +13,13 @@ called Super CPU cluster (SCCL) and is made up of 6 CCLs. Each SCCL has
two HHAs (0 - 1) and four DDRCs (0 - 3), respectively.
HiSilicon SoC uncore PMU driver
----------------------------------------
+-------------------------------
+
Each device PMU has separate registers for event counting, control and
interrupt, and the PMU driver shall register perf PMU drivers like L3C,
HHA and DDRC etc. The available events and configuration options shall
-be described in the sysfs, see :
+be described in the sysfs, see:
+
/sys/devices/hisi_sccl{X}_<l3c{Y}/hha{Y}/ddrc{Y}>/, or
/sys/bus/event_source/devices/hisi_sccl{X}_<l3c{Y}/hha{Y}/ddrc{Y}>.
The "perf list" command shall list the available events from sysfs.
@@ -24,27 +28,30 @@ Each L3C, HHA and DDRC is registered as a separate PMU with perf. The PMU
name will appear in event listing as hisi_sccl<sccl-id>_module<index-id>.
where "sccl-id" is the identifier of the SCCL and "index-id" is the index of
module.
+
e.g. hisi_sccl3_l3c0/rd_hit_cpipe is READ_HIT_CPIPE event of L3C index #0 in
SCCL ID #3.
+
e.g. hisi_sccl1_hha0/rx_operations is RX_OPERATIONS event of HHA index #0 in
SCCL ID #1.
The driver also provides a "cpumask" sysfs attribute, which shows the CPU core
ID used to count the uncore PMU event.
-Example usage of perf:
-$# perf list
-hisi_sccl3_l3c0/rd_hit_cpipe/ [kernel PMU event]
-------------------------------------------
-hisi_sccl3_l3c0/wr_hit_cpipe/ [kernel PMU event]
-------------------------------------------
-hisi_sccl1_l3c0/rd_hit_cpipe/ [kernel PMU event]
-------------------------------------------
-hisi_sccl1_l3c0/wr_hit_cpipe/ [kernel PMU event]
-------------------------------------------
+Example usage of perf::
-$# perf stat -a -e hisi_sccl3_l3c0/rd_hit_cpipe/ sleep 5
-$# perf stat -a -e hisi_sccl3_l3c0/config=0x02/ sleep 5
+ $# perf list
+ hisi_sccl3_l3c0/rd_hit_cpipe/ [kernel PMU event]
+ ------------------------------------------
+ hisi_sccl3_l3c0/wr_hit_cpipe/ [kernel PMU event]
+ ------------------------------------------
+ hisi_sccl1_l3c0/rd_hit_cpipe/ [kernel PMU event]
+ ------------------------------------------
+ hisi_sccl1_l3c0/wr_hit_cpipe/ [kernel PMU event]
+ ------------------------------------------
+
+ $# perf stat -a -e hisi_sccl3_l3c0/rd_hit_cpipe/ sleep 5
+ $# perf stat -a -e hisi_sccl3_l3c0/config=0x02/ sleep 5
The current driver does not support sampling. So "perf record" is unsupported.
Also attach to a task is unsupported as the events are all uncore.
diff --git a/Documentation/perf/index.rst b/Documentation/perf/index.rst
new file mode 100644
index 000000000000..4bf848e27f26
--- /dev/null
+++ b/Documentation/perf/index.rst
@@ -0,0 +1,16 @@
+:orphan:
+
+===========================
+Performance monitor support
+===========================
+
+.. toctree::
+ :maxdepth: 1
+
+ hisi-pmu
+ qcom_l2_pmu
+ qcom_l3_pmu
+ arm-ccn
+ xgene-pmu
+ arm_dsu_pmu
+ thunderx2-pmu
diff --git a/Documentation/perf/qcom_l2_pmu.txt b/Documentation/perf/qcom_l2_pmu.rst
similarity index 94%
rename from Documentation/perf/qcom_l2_pmu.txt
rename to Documentation/perf/qcom_l2_pmu.rst
index b25b97659ab9..c130178a4a55 100644
--- a/Documentation/perf/qcom_l2_pmu.txt
+++ b/Documentation/perf/qcom_l2_pmu.rst
@@ -1,3 +1,4 @@
+=====================================================================
Qualcomm Technologies Level-2 Cache Performance Monitoring Unit (PMU)
=====================================================================
@@ -28,7 +29,7 @@ The driver provides a "cpumask" sysfs attribute which contains a mask
consisting of one CPU per cluster which will be used to handle all the PMU
events on that cluster.
-Examples for use with perf:
+Examples for use with perf::
perf stat -e l2cache_0/config=0x001/,l2cache_0/config=0x042/ -a sleep 1
diff --git a/Documentation/perf/qcom_l3_pmu.txt b/Documentation/perf/qcom_l3_pmu.rst
similarity index 93%
rename from Documentation/perf/qcom_l3_pmu.txt
rename to Documentation/perf/qcom_l3_pmu.rst
index 96b3a9444a0d..a3d014a46bfd 100644
--- a/Documentation/perf/qcom_l3_pmu.txt
+++ b/Documentation/perf/qcom_l3_pmu.rst
@@ -1,3 +1,4 @@
+===========================================================================
Qualcomm Datacenter Technologies L3 Cache Performance Monitoring Unit (PMU)
===========================================================================
@@ -17,7 +18,7 @@ The hardware implements 32bit event counters and has a flat 8bit event space
exposed via the "event" format attribute. In addition to the 32bit physical
counters the driver supports virtual 64bit hardware counters by using hardware
counter chaining. This feature is exposed via the "lc" (long counter) format
-flag. E.g.:
+flag. E.g.::
perf stat -e l3cache_0_0/read-miss,lc/
diff --git a/Documentation/perf/thunderx2-pmu.txt b/Documentation/perf/thunderx2-pmu.rst
similarity index 73%
rename from Documentation/perf/thunderx2-pmu.txt
rename to Documentation/perf/thunderx2-pmu.rst
index dffc57143736..08e33675853a 100644
--- a/Documentation/perf/thunderx2-pmu.txt
+++ b/Documentation/perf/thunderx2-pmu.rst
@@ -1,3 +1,4 @@
+=============================================================
Cavium ThunderX2 SoC Performance Monitoring Unit (PMU UNCORE)
=============================================================
@@ -24,18 +25,18 @@ and configuration options under sysfs, see
The driver does not support sampling, therefore "perf record" will not
work. Per-task perf sessions are also not supported.
-Examples:
+Examples::
-# perf stat -a -e uncore_dmc_0/cnt_cycles/ sleep 1
+ # perf stat -a -e uncore_dmc_0/cnt_cycles/ sleep 1
-# perf stat -a -e \
-uncore_dmc_0/cnt_cycles/,\
-uncore_dmc_0/data_transfers/,\
-uncore_dmc_0/read_txns/,\
-uncore_dmc_0/write_txns/ sleep 1
+ # perf stat -a -e \
+ uncore_dmc_0/cnt_cycles/,\
+ uncore_dmc_0/data_transfers/,\
+ uncore_dmc_0/read_txns/,\
+ uncore_dmc_0/write_txns/ sleep 1
-# perf stat -a -e \
-uncore_l3c_0/read_request/,\
-uncore_l3c_0/read_hit/,\
-uncore_l3c_0/inv_request/,\
-uncore_l3c_0/inv_hit/ sleep 1
+ # perf stat -a -e \
+ uncore_l3c_0/read_request/,\
+ uncore_l3c_0/read_hit/,\
+ uncore_l3c_0/inv_request/,\
+ uncore_l3c_0/inv_hit/ sleep 1
diff --git a/Documentation/perf/xgene-pmu.txt b/Documentation/perf/xgene-pmu.rst
similarity index 96%
rename from Documentation/perf/xgene-pmu.txt
rename to Documentation/perf/xgene-pmu.rst
index d7cff4454e5b..644f8ed89152 100644
--- a/Documentation/perf/xgene-pmu.txt
+++ b/Documentation/perf/xgene-pmu.rst
@@ -1,3 +1,4 @@
+================================================
APM X-Gene SoC Performance Monitoring Unit (PMU)
================================================
@@ -33,7 +34,7 @@ each PMU, please refer to APM X-Gene User Manual.
Each perf driver also provides a "cpumask" sysfs attribute, which contains a
single CPU ID of the processor which will be used to handle all the PMU events.
-Example for perf tool use:
+Example for perf tool use::
/ # perf list | grep -e l3c -e iob -e mcb -e mc
l3c0/ackq-full/ [Kernel PMU event]
diff --git a/MAINTAINERS b/MAINTAINERS
index 163327d6a856..2f8e1543caff 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1139,7 +1139,7 @@ APPLIED MICRO (APM) X-GENE SOC PMU
M: Khuong Dinh <khuong@os.amperecomputing.com>
S: Supported
F: drivers/perf/xgene_pmu.c
-F: Documentation/perf/xgene-pmu.txt
+F: Documentation/perf/xgene-pmu.rst
F: Documentation/devicetree/bindings/perf/apm-xgene-pmu.txt
APTINA CAMERA SENSOR PLL
@@ -7180,7 +7180,7 @@ M: Shaokun Zhang <zhangshaokun@hisilicon.com>
W: http://www.hisilicon.com
S: Supported
F: drivers/perf/hisilicon
-F: Documentation/perf/hisi-pmu.txt
+F: Documentation/perf/hisi-pmu.rst
HISILICON ROCE DRIVER
M: Lijun Ou <oulijun@huawei.com>
diff --git a/drivers/perf/qcom_l3_pmu.c b/drivers/perf/qcom_l3_pmu.c
index 15b8c10c2b2b..90f88ce5192b 100644
--- a/drivers/perf/qcom_l3_pmu.c
+++ b/drivers/perf/qcom_l3_pmu.c
@@ -8,7 +8,7 @@
* the slices. User space needs to aggregate to individual counts to provide
* a global picture.
*
- * See Documentation/perf/qcom_l3_pmu.txt for more details.
+ * See Documentation/perf/qcom_l3_pmu.rst for more details.
*
* Copyright (c) 2015-2017, The Linux Foundation. All rights reserved.
*/
--
2.21.0
^ permalink raw reply related
* [PATCH v1 15/22] docs: driver-api: add a chapter for memory-related API
From: Mauro Carvalho Chehab @ 2019-06-18 21:05 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Bjorn Helgaas, Alan Stern, Andrea Parri,
Will Deacon, Peter Zijlstra, Boqun Feng, Nicholas Piggin,
David Howells, Jade Alglave, Luc Maranget, Paul E. McKenney,
Akira Yokosawa, Daniel Lustig, Tony Luck, Fenghua Yu,
James E.J. Bottomley, Helge Deller, Thomas Gleixner, Ingo Molnar,
Borislav Petkov, H. Peter Anvin, x86, Christoph Hellwig,
Marek Szyprowski, Robin Murphy, linux-pci, linux-arch, linux-ia64,
linux-parisc, iommu
In-Reply-To: <cover.1560891322.git.mchehab+samsung@kernel.org>
There are some DMA files under the main dir. Move them to the
new chapter and add an index file for them.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/PCI/pci.rst | 6 +++---
Documentation/block/biodoc.rst | 2 +-
.../driver-api/bus-virt-phys-mapping.rst | 2 +-
Documentation/driver-api/index.rst | 2 ++
.../mm/dma-api-howto.rst} | 2 --
.../{DMA-API.rst => driver-api/mm/dma-api.rst} | 8 +++-----
.../mm/dma-attributes.rst} | 2 --
.../mm/dma-isa-lpc.rst} | 4 +---
Documentation/driver-api/mm/index.rst | 11 +++++++++++
Documentation/driver-api/usb/dma.rst | 6 +++---
Documentation/memory-barriers.txt | 6 +++---
.../translations/ko_KR/memory-barriers.txt | 6 +++---
arch/ia64/hp/common/sba_iommu.c | 12 ++++++------
arch/ia64/sn/pci/pci_dma.c | 4 ++--
arch/parisc/kernel/pci-dma.c | 2 +-
arch/x86/include/asm/dma-mapping.h | 4 ++--
arch/x86/kernel/amd_gart_64.c | 2 +-
drivers/parisc/sba_iommu.c | 16 ++++++++--------
include/linux/dma-mapping.h | 2 +-
include/media/videobuf-dma-sg.h | 2 +-
kernel/dma/debug.c | 2 +-
21 files changed, 54 insertions(+), 49 deletions(-)
rename Documentation/{DMA-API-HOWTO.rst => driver-api/mm/dma-api-howto.rst} (99%)
rename Documentation/{DMA-API.rst => driver-api/mm/dma-api.rst} (99%)
rename Documentation/{DMA-attributes.rst => driver-api/mm/dma-attributes.rst} (99%)
rename Documentation/{DMA-ISA-LPC.rst => driver-api/mm/dma-isa-lpc.rst} (98%)
create mode 100644 Documentation/driver-api/mm/index.rst
diff --git a/Documentation/PCI/pci.rst b/Documentation/PCI/pci.rst
index 0f52d172c9ac..8665209eda40 100644
--- a/Documentation/PCI/pci.rst
+++ b/Documentation/PCI/pci.rst
@@ -265,7 +265,7 @@ Set the DMA mask size
---------------------
.. note::
If anything below doesn't make sense, please refer to
- Documentation/DMA-API.rst. This section is just a reminder that
+ Documentation/driver-api/mm/dma-api.rst. This section is just a reminder that
drivers need to indicate DMA capabilities of the device and is not
an authoritative source for DMA interfaces.
@@ -291,7 +291,7 @@ Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are
Setup shared control data
-------------------------
Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared)
-memory. See Documentation/DMA-API.rst for a full description of
+memory. See Documentation/driver-api/mm/dma-api.rst for a full description of
the DMA APIs. This section is just a reminder that it needs to be done
before enabling DMA on the device.
@@ -421,7 +421,7 @@ owners if there is one.
Then clean up "consistent" buffers which contain the control data.
-See Documentation/DMA-API.rst for details on unmapping interfaces.
+See Documentation/driver-api/mm/dma-api.rst for details on unmapping interfaces.
Unregister from other subsystems
diff --git a/Documentation/block/biodoc.rst b/Documentation/block/biodoc.rst
index 59bd93bec8fc..2206c88e7dee 100644
--- a/Documentation/block/biodoc.rst
+++ b/Documentation/block/biodoc.rst
@@ -195,7 +195,7 @@ a virtual address mapping (unlike the earlier scheme of virtual address
do not have a corresponding kernel virtual address space mapping) and
low-memory pages.
-Note: Please refer to Documentation/DMA-API-HOWTO.rst for a discussion
+Note: Please refer to Documentation/driver-api/mm/dma-api-howto.rst for a discussion
on PCI high mem DMA aspects and mapping of scatter gather lists, and support
for 64 bit PCI.
diff --git a/Documentation/driver-api/bus-virt-phys-mapping.rst b/Documentation/driver-api/bus-virt-phys-mapping.rst
index 80972916e88c..18b6fdf618d2 100644
--- a/Documentation/driver-api/bus-virt-phys-mapping.rst
+++ b/Documentation/driver-api/bus-virt-phys-mapping.rst
@@ -8,7 +8,7 @@ How to access I/O mapped memory from within device drivers
The virt_to_bus() and bus_to_virt() functions have been
superseded by the functionality provided by the PCI DMA interface
- (see Documentation/DMA-API-HOWTO.rst). They continue
+ (see Documentation/driver-api/mm/dma-api-howto.rst). They continue
to be documented below for historical purposes, but new code
must not use them. --davidm 00/12/12
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index bb2621b17212..492b96003af2 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -16,6 +16,7 @@ available subsections can be seen below.
basics
infrastructure
+ mm/index
pm/index
clk
device-io
@@ -59,6 +60,7 @@ available subsections can be seen below.
fpga/index
acpi/index
generic-counter
+ mm/index
atomic_bitops
bt8xxgpio
diff --git a/Documentation/DMA-API-HOWTO.rst b/Documentation/driver-api/mm/dma-api-howto.rst
similarity index 99%
rename from Documentation/DMA-API-HOWTO.rst
rename to Documentation/driver-api/mm/dma-api-howto.rst
index db9f8fcebe1f..358d495456d1 100644
--- a/Documentation/DMA-API-HOWTO.rst
+++ b/Documentation/driver-api/mm/dma-api-howto.rst
@@ -1,5 +1,3 @@
-:orphan:
-
=========================
Dynamic DMA mapping Guide
=========================
diff --git a/Documentation/DMA-API.rst b/Documentation/driver-api/mm/dma-api.rst
similarity index 99%
rename from Documentation/DMA-API.rst
rename to Documentation/driver-api/mm/dma-api.rst
index 2f26857f97ff..c2c4d0b456b1 100644
--- a/Documentation/DMA-API.rst
+++ b/Documentation/driver-api/mm/dma-api.rst
@@ -1,5 +1,3 @@
-:orphan:
-
============================================
Dynamic DMA mapping using the generic device
============================================
@@ -7,7 +5,7 @@ Dynamic DMA mapping using the generic device
:Author: James E.J. Bottomley <James.Bottomley@HansenPartnership.com>
This document describes the DMA API. For a more gentle introduction
-of the API (and actual examples), see Documentation/DMA-API-HOWTO.rst.
+of the API (and actual examples), see Documentation/driver-api/mm/dma-api-howto.rst.
This API is split into two pieces. Part I describes the basic API.
Part II describes extensions for supporting non-consistent memory
@@ -465,7 +463,7 @@ without the _attrs suffixes, except that they pass an optional
dma_attrs.
The interpretation of DMA attributes is architecture-specific, and
-each attribute should be documented in Documentation/DMA-attributes.rst.
+each attribute should be documented in Documentation/driver-api/mm/dma-attributes.rst.
If dma_attrs are 0, the semantics of each of these functions
is identical to those of the corresponding function
@@ -478,7 +476,7 @@ for DMA::
#include <linux/dma-mapping.h>
/* DMA_ATTR_FOO should be defined in linux/dma-mapping.h and
- * documented in Documentation/DMA-attributes.rst */
+ * documented in Documentation/driver-api/mm/dma-attributes.rst */
...
unsigned long attr;
diff --git a/Documentation/DMA-attributes.rst b/Documentation/driver-api/mm/dma-attributes.rst
similarity index 99%
rename from Documentation/DMA-attributes.rst
rename to Documentation/driver-api/mm/dma-attributes.rst
index 471c5c38f9d9..8f8d97f65d73 100644
--- a/Documentation/DMA-attributes.rst
+++ b/Documentation/driver-api/mm/dma-attributes.rst
@@ -1,5 +1,3 @@
-:orphan:
-
==============
DMA attributes
==============
diff --git a/Documentation/DMA-ISA-LPC.rst b/Documentation/driver-api/mm/dma-isa-lpc.rst
similarity index 98%
rename from Documentation/DMA-ISA-LPC.rst
rename to Documentation/driver-api/mm/dma-isa-lpc.rst
index 205a379c2d62..6ae393d391cf 100644
--- a/Documentation/DMA-ISA-LPC.rst
+++ b/Documentation/driver-api/mm/dma-isa-lpc.rst
@@ -1,5 +1,3 @@
-:orphan:
-
============================
DMA with ISA and LPC devices
============================
@@ -19,7 +17,7 @@ To do ISA style DMA you need to include two headers::
#include <asm/dma.h>
The first is the generic DMA API used to convert virtual addresses to
-bus addresses (see Documentation/DMA-API.rst for details).
+bus addresses (see Documentation/driver-api/mm/dma-api.rst for details).
The second contains the routines specific to ISA DMA transfers. Since
this is not present on all platforms make sure you construct your
diff --git a/Documentation/driver-api/mm/index.rst b/Documentation/driver-api/mm/index.rst
new file mode 100644
index 000000000000..e34c7ee4a4b9
--- /dev/null
+++ b/Documentation/driver-api/mm/index.rst
@@ -0,0 +1,11 @@
+==========================
+Memory Related Kernel APIs
+==========================
+
+.. toctree::
+ :maxdepth: 1
+
+ dma-api
+ dma-api-howto
+ dma-attributes
+ dma-isa-lpc
diff --git a/Documentation/driver-api/usb/dma.rst b/Documentation/driver-api/usb/dma.rst
index 12955a77c7fe..8ef36aa2278d 100644
--- a/Documentation/driver-api/usb/dma.rst
+++ b/Documentation/driver-api/usb/dma.rst
@@ -10,7 +10,7 @@ API overview
The big picture is that USB drivers can continue to ignore most DMA issues,
though they still must provide DMA-ready buffers (see
-``Documentation/DMA-API-HOWTO.rst``). That's how they've worked through
+``Documentation/driver-api/mm/dma-api-howto.rst``). That's how they've worked through
the 2.4 (and earlier) kernels, or they can now be DMA-aware.
DMA-aware usb drivers:
@@ -60,7 +60,7 @@ and effects like cache-trashing can impose subtle penalties.
force a consistent memory access ordering by using memory barriers. It's
not using a streaming DMA mapping, so it's good for small transfers on
systems where the I/O would otherwise thrash an IOMMU mapping. (See
- ``Documentation/DMA-API-HOWTO.rst`` for definitions of "coherent" and
+ ``Documentation/driver-api/mm/dma-api-howto.rst`` for definitions of "coherent" and
"streaming" DMA mappings.)
Asking for 1/Nth of a page (as well as asking for N pages) is reasonably
@@ -91,7 +91,7 @@ Working with existing buffers
Existing buffers aren't usable for DMA without first being mapped into the
DMA address space of the device. However, most buffers passed to your
driver can safely be used with such DMA mapping. (See the first section
-of Documentation/DMA-API-HOWTO.rst, titled "What memory is DMA-able?")
+of Documentation/driver-api/mm/dma-api-howto.rst, titled "What memory is DMA-able?")
- When you're using scatterlists, you can map everything at once. On some
systems, this kicks in an IOMMU and turns the scatterlists into single
diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt
index 4a44f00478db..087b0d864a94 100644
--- a/Documentation/memory-barriers.txt
+++ b/Documentation/memory-barriers.txt
@@ -549,8 +549,8 @@ There are certain things that the Linux kernel memory barriers do not guarantee:
[*] For information on bus mastering DMA and coherency please read:
Documentation/PCI/pci.rst
- Documentation/DMA-API-HOWTO.rst
- Documentation/DMA-API.rst
+ Documentation/driver-api/mm/dma-api-howto.rst
+ Documentation/driver-api/mm/dma-api.rst
DATA DEPENDENCY BARRIERS (HISTORICAL)
@@ -1933,7 +1933,7 @@ There are some more advanced barrier functions:
here.
See the subsection "Kernel I/O barrier effects" for more information on
- relaxed I/O accessors and the Documentation/DMA-API.rst file for more
+ relaxed I/O accessors and the Documentation/driver-api/mm/dma-api.rst file for more
information on consistent memory.
diff --git a/Documentation/translations/ko_KR/memory-barriers.txt b/Documentation/translations/ko_KR/memory-barriers.txt
index 03c06a7800c3..7b86ac9f15d2 100644
--- a/Documentation/translations/ko_KR/memory-barriers.txt
+++ b/Documentation/translations/ko_KR/memory-barriers.txt
@@ -570,8 +570,8 @@ ACQUIRE 는 해당 오퍼레이션의 로드 부분에만 적용되고 RELEASE
[*] 버스 마스터링 DMA 와 일관성에 대해서는 다음을 참고하시기 바랍니다:
Documentation/PCI/pci.rst
- Documentation/DMA-API-HOWTO.rst
- Documentation/DMA-API.rst
+ Documentation/driver-api/mm/dma-api-howto.rst
+ Documentation/driver-api/mm/dma-api.rst
데이터 의존성 배리어 (역사적)
@@ -1904,7 +1904,7 @@ Mandatory 배리어들은 SMP 시스템에서도 UP 시스템에서도 SMP 효
writel_relaxed() 와 같은 완화된 I/O 접근자들에 대한 자세한 내용을 위해서는
"커널 I/O 배리어의 효과" 섹션을, consistent memory 에 대한 자세한 내용을
- 위해선 Documentation/DMA-API.rst 문서를 참고하세요.
+ 위해선 Documentation/driver-api/mm/dma-api.rst 문서를 참고하세요.
MMIO 쓰기 배리어
diff --git a/arch/ia64/hp/common/sba_iommu.c b/arch/ia64/hp/common/sba_iommu.c
index 8f97d42316e8..0b0b5084e6c8 100644
--- a/arch/ia64/hp/common/sba_iommu.c
+++ b/arch/ia64/hp/common/sba_iommu.c
@@ -912,7 +912,7 @@ sba_mark_invalid(struct ioc *ioc, dma_addr_t iova, size_t byte_cnt)
* @dir: dma direction
* @attrs: optional dma attributes
*
- * See Documentation/DMA-API-HOWTO.rst
+ * See Documentation/driver-api/mm/dma-api-howto.rst
*/
static dma_addr_t sba_map_page(struct device *dev, struct page *page,
unsigned long poff, size_t size,
@@ -1033,7 +1033,7 @@ sba_mark_clean(struct ioc *ioc, dma_addr_t iova, size_t size)
* @dir: R/W or both.
* @attrs: optional dma attributes
*
- * See Documentation/DMA-API-HOWTO.rst
+ * See Documentation/driver-api/mm/dma-api-howto.rst
*/
static void sba_unmap_page(struct device *dev, dma_addr_t iova, size_t size,
enum dma_data_direction dir, unsigned long attrs)
@@ -1110,7 +1110,7 @@ static void sba_unmap_page(struct device *dev, dma_addr_t iova, size_t size,
* @size: number of bytes mapped in driver buffer.
* @dma_handle: IOVA of new buffer.
*
- * See Documentation/DMA-API-HOWTO.rst
+ * See Documentation/driver-api/mm/dma-api-howto.rst
*/
static void *
sba_alloc_coherent(struct device *dev, size_t size, dma_addr_t *dma_handle,
@@ -1167,7 +1167,7 @@ sba_alloc_coherent(struct device *dev, size_t size, dma_addr_t *dma_handle,
* @vaddr: virtual address IOVA of "consistent" buffer.
* @dma_handler: IO virtual address of "consistent" buffer.
*
- * See Documentation/DMA-API-HOWTO.rst
+ * See Documentation/driver-api/mm/dma-api-howto.rst
*/
static void sba_free_coherent(struct device *dev, size_t size, void *vaddr,
dma_addr_t dma_handle, unsigned long attrs)
@@ -1430,7 +1430,7 @@ static void sba_unmap_sg_attrs(struct device *dev, struct scatterlist *sglist,
* @dir: R/W or both.
* @attrs: optional dma attributes
*
- * See Documentation/DMA-API-HOWTO.rst
+ * See Documentation/driver-api/mm/dma-api-howto.rst
*/
static int sba_map_sg_attrs(struct device *dev, struct scatterlist *sglist,
int nents, enum dma_data_direction dir,
@@ -1529,7 +1529,7 @@ static int sba_map_sg_attrs(struct device *dev, struct scatterlist *sglist,
* @dir: R/W or both.
* @attrs: optional dma attributes
*
- * See Documentation/DMA-API-HOWTO.rst
+ * See Documentation/driver-api/mm/dma-api-howto.rst
*/
static void sba_unmap_sg_attrs(struct device *dev, struct scatterlist *sglist,
int nents, enum dma_data_direction dir,
diff --git a/arch/ia64/sn/pci/pci_dma.c b/arch/ia64/sn/pci/pci_dma.c
index f475fccea152..a06ae52117f0 100644
--- a/arch/ia64/sn/pci/pci_dma.c
+++ b/arch/ia64/sn/pci/pci_dma.c
@@ -5,7 +5,7 @@
*
* Copyright (C) 2000,2002-2005 Silicon Graphics, Inc. All rights reserved.
*
- * Routines for PCI DMA mapping. See Documentation/DMA-API.rst for
+ * Routines for PCI DMA mapping. See Documentation/driver-api/mm/dma-api.rst for
* a description of how these routines should be used.
*/
@@ -72,7 +72,7 @@ EXPORT_SYMBOL(sn_dma_set_mask);
* that @dma_handle will have the %PCIIO_DMA_CMD flag set.
*
* This interface is usually used for "command" streams (e.g. the command
- * queue for a SCSI controller). See Documentation/DMA-API.rst for
+ * queue for a SCSI controller). See Documentation/driver-api/mm/dma-api.rst for
* more information.
*/
static void *sn_dma_alloc_coherent(struct device *dev, size_t size,
diff --git a/arch/parisc/kernel/pci-dma.c b/arch/parisc/kernel/pci-dma.c
index 2bb63062f6c3..08e7ff08fa94 100644
--- a/arch/parisc/kernel/pci-dma.c
+++ b/arch/parisc/kernel/pci-dma.c
@@ -3,7 +3,7 @@
** PARISC 1.1 Dynamic DMA mapping support.
** This implementation is for PA-RISC platforms that do not support
** I/O TLBs (aka DMA address translation hardware).
-** See Documentation/DMA-API-HOWTO.rst for interface definitions.
+** See Documentation/driver-api/mm/dma-api-howto.rst for interface definitions.
**
** (c) Copyright 1999,2000 Hewlett-Packard Company
** (c) Copyright 2000 Grant Grundler
diff --git a/arch/x86/include/asm/dma-mapping.h b/arch/x86/include/asm/dma-mapping.h
index dfa443fe17c2..ff9ff85529fc 100644
--- a/arch/x86/include/asm/dma-mapping.h
+++ b/arch/x86/include/asm/dma-mapping.h
@@ -3,8 +3,8 @@
#define _ASM_X86_DMA_MAPPING_H
/*
- * IOMMU interface. See Documentation/DMA-API-HOWTO.rst and
- * Documentation/DMA-API.rst for documentation.
+ * IOMMU interface. See Documentation/driver-api/mm/dma-api-howto.rst and
+ * Documentation/driver-api/mm/dma-api.rst for documentation.
*/
#include <linux/scatterlist.h>
diff --git a/arch/x86/kernel/amd_gart_64.c b/arch/x86/kernel/amd_gart_64.c
index 03108de30105..397c2cdd19d8 100644
--- a/arch/x86/kernel/amd_gart_64.c
+++ b/arch/x86/kernel/amd_gart_64.c
@@ -6,7 +6,7 @@
* This allows to use PCI devices that only support 32bit addresses on systems
* with more than 4GB.
*
- * See Documentation/DMA-API-HOWTO.rst for the interface specification.
+ * See Documentation/driver-api/mm/dma-api-howto.rst for the interface specification.
*
* Copyright 2002 Andi Kleen, SuSE Labs.
*/
diff --git a/drivers/parisc/sba_iommu.c b/drivers/parisc/sba_iommu.c
index 267ceb5f7838..349b4a2f21a1 100644
--- a/drivers/parisc/sba_iommu.c
+++ b/drivers/parisc/sba_iommu.c
@@ -666,7 +666,7 @@ sba_mark_invalid(struct ioc *ioc, dma_addr_t iova, size_t byte_cnt)
* @dev: instance of PCI owned by the driver that's asking
* @mask: number of address bits this PCI device can handle
*
- * See Documentation/DMA-API-HOWTO.rst
+ * See Documentation/driver-api/mm/dma-api-howto.rst
*/
static int sba_dma_supported( struct device *dev, u64 mask)
{
@@ -678,7 +678,7 @@ static int sba_dma_supported( struct device *dev, u64 mask)
return(0);
}
- /* Documentation/DMA-API-HOWTO.rst tells drivers to try 64-bit
+ /* Documentation/driver-api/mm/dma-api-howto.rst tells drivers to try 64-bit
* first, then fall back to 32-bit if that fails.
* We are just "encouraging" 32-bit DMA masks here since we can
* never allow IOMMU bypass unless we add special support for ZX1.
@@ -706,7 +706,7 @@ static int sba_dma_supported( struct device *dev, u64 mask)
* @size: number of bytes to map in driver buffer.
* @direction: R/W or both.
*
- * See Documentation/DMA-API-HOWTO.rst
+ * See Documentation/driver-api/mm/dma-api-howto.rst
*/
static dma_addr_t
sba_map_single(struct device *dev, void *addr, size_t size,
@@ -796,7 +796,7 @@ sba_map_page(struct device *dev, struct page *page, unsigned long offset,
* @size: number of bytes mapped in driver buffer.
* @direction: R/W or both.
*
- * See Documentation/DMA-API-HOWTO.rst
+ * See Documentation/driver-api/mm/dma-api-howto.rst
*/
static void
sba_unmap_page(struct device *dev, dma_addr_t iova, size_t size,
@@ -875,7 +875,7 @@ sba_unmap_page(struct device *dev, dma_addr_t iova, size_t size,
* @size: number of bytes mapped in driver buffer.
* @dma_handle: IOVA of new buffer.
*
- * See Documentation/DMA-API-HOWTO.rst
+ * See Documentation/driver-api/mm/dma-api-howto.rst
*/
static void *sba_alloc(struct device *hwdev, size_t size, dma_addr_t *dma_handle,
gfp_t gfp, unsigned long attrs)
@@ -906,7 +906,7 @@ static void *sba_alloc(struct device *hwdev, size_t size, dma_addr_t *dma_handle
* @vaddr: virtual address IOVA of "consistent" buffer.
* @dma_handler: IO virtual address of "consistent" buffer.
*
- * See Documentation/DMA-API-HOWTO.rst
+ * See Documentation/driver-api/mm/dma-api-howto.rst
*/
static void
sba_free(struct device *hwdev, size_t size, void *vaddr,
@@ -941,7 +941,7 @@ int dump_run_sg = 0;
* @nents: number of entries in list
* @direction: R/W or both.
*
- * See Documentation/DMA-API-HOWTO.rst
+ * See Documentation/driver-api/mm/dma-api-howto.rst
*/
static int
sba_map_sg(struct device *dev, struct scatterlist *sglist, int nents,
@@ -1025,7 +1025,7 @@ sba_map_sg(struct device *dev, struct scatterlist *sglist, int nents,
* @nents: number of entries in list
* @direction: R/W or both.
*
- * See Documentation/DMA-API-HOWTO.rst
+ * See Documentation/driver-api/mm/dma-api-howto.rst
*/
static void
sba_unmap_sg(struct device *dev, struct scatterlist *sglist, int nents,
diff --git a/include/linux/dma-mapping.h b/include/linux/dma-mapping.h
index 7ff3fcd73cec..eb234c3f466b 100644
--- a/include/linux/dma-mapping.h
+++ b/include/linux/dma-mapping.h
@@ -14,7 +14,7 @@
/**
* List of possible attributes associated with a DMA mapping. The semantics
- * of each attribute should be defined in Documentation/DMA-attributes.rst.
+ * of each attribute should be defined in Documentation/driver-api/mm/dma-attributes.rst.
*
* DMA_ATTR_WRITE_BARRIER: DMA to a memory region with this attribute
* forces all pending DMA writes to complete.
diff --git a/include/media/videobuf-dma-sg.h b/include/media/videobuf-dma-sg.h
index 50a549e5b477..60f2df32bf39 100644
--- a/include/media/videobuf-dma-sg.h
+++ b/include/media/videobuf-dma-sg.h
@@ -34,7 +34,7 @@
* does memory allocation too using vmalloc_32().
*
* videobuf_dma_*()
- * see Documentation/DMA-API-HOWTO.rst, these functions to
+ * see Documentation/driver-api/mm/dma-api-howto.rst, these functions to
* basically the same. The map function does also build a
* scatterlist for the buffer (and unmap frees it ...)
*
diff --git a/kernel/dma/debug.c b/kernel/dma/debug.c
index 616919c774a5..1d3f9b8de6df 100644
--- a/kernel/dma/debug.c
+++ b/kernel/dma/debug.c
@@ -1069,7 +1069,7 @@ static void check_unmap(struct dma_debug_entry *ref)
/*
* Drivers should use dma_mapping_error() to check the returned
* addresses of dma_map_single() and dma_map_page().
- * If not, print this warning message. See Documentation/DMA-API.rst.
+ * If not, print this warning message. See Documentation/driver-api/mm/dma-api.rst.
*/
if (entry->map_err_type == MAP_ERR_NOT_CHECKED) {
err_printk(ref->dev, entry,
--
2.21.0
^ permalink raw reply related
* [PATCH v1 00/22] Convert files to ReST - part 3
From: Mauro Carvalho Chehab @ 2019-06-18 21:05 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Palmer Dabbelt, Albert Ou, Alexei Starovoitov,
Daniel Borkmann, Martin KaFai Lau, Song Liu, Yonghong Song,
linux-riscv, netdev, bpf
This is the third part of a series I wrote sometime ago where I manually
convert lots of files to be properly parsed by Sphinx as ReST files.
As it touches on lot of stuff, this series is based on today's linux-next,
at tag next-20190617.
The first version of this series had 57 patches. The first part with 28 patches
were already merged. The second part has 29 patches. This series with 22
patches finishes the conversion part of my series. That's because I opted to
do ~1 patch per converted directory.
That sounds too much to be send on a single round. So, I'm opting to split
it on 3 parts for the conversion.
After having those three patch series merged, I should submit a final patch
series adding orphaned books to existing ones (with ~50 patches), to be
applied on a convenient moment (probably late on a merge window).
Those patches should probably be good to be merged either by subsystem
maintainers or via the docs tree.
I opted to mark new files not included yet to the main index.rst (directly or
indirectly) with the :orphan: tag, in order to avoid adding warnings to the
build system. This should be removed after we find a "home" for all
the converted files within the new document tree arrangement, after I
submit the third part.
Both this series and the other parts of this work are on my devel git tree,
at:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=convert_rst_renames_v5.1
The final output in html (after all patches I currently have, including
the upcoming series) can be seen at:
https://www.infradead.org/~mchehab/rst_conversion/
It contains all pending work from my side related to the conversion, plus
the patches I finished a first version today with contains the renaming
patches and de-orphan changes.
Mauro Carvalho Chehab (22):
docs: Documentation/*.txt: rename all ReST files to *.rst
docs: ioctl-number.txt: convert it to ReST format
docs: ioctl: convert to ReST
docs: thermal: convert to ReST
docs: rapidio: convert to ReST
docs: blockdev: convert to ReST
docs: perf: convert to ReST
docs: sysctl: convert to ReST
docs: block: convert to ReST
docs: security: move some books to it and update
docs: admin-guide: add .rst files from the main dir
docs: driver-api: add .rst files from the main dir
docs: x86: move two x86-specific files to x86 arch dir
docs: usb: rename files to .rst and add them to drivers-api
docs: driver-api: add a chapter for memory-related API
docs: driver-api: add xilinx driver API documentation
docs: add arch doc directories to the index
docs: admin-guide: move sysctl directory to it
docs: driver-api: add remaining converted dirs to it
docs: extcon: move it to acpi dir and convert it to ReST
docs: admin-guide: add laptops documentation
admin-guide: add kdump documentation into it
CREDITS | 2 +-
Documentation/ABI/removed/sysfs-class-rfkill | 2 +-
Documentation/ABI/stable/sysfs-class-rfkill | 2 +-
Documentation/ABI/stable/sysfs-devices-node | 2 +-
Documentation/ABI/testing/procfs-diskstats | 2 +-
Documentation/ABI/testing/sysfs-block | 2 +-
Documentation/ABI/testing/sysfs-block-device | 2 +-
.../ABI/testing/sysfs-class-switchtec | 2 +-
.../ABI/testing/sysfs-devices-system-cpu | 4 +-
.../ABI/testing/sysfs-platform-asus-laptop | 2 +-
Documentation/PCI/pci.rst | 8 +-
Documentation/{ => admin-guide}/aoe/aoe.rst | 4 +-
.../{ => admin-guide}/aoe/autoload.sh | 1 -
.../{ => admin-guide}/aoe/examples.rst | 0
Documentation/{ => admin-guide}/aoe/index.rst | 2 -
Documentation/{ => admin-guide}/aoe/status.sh | 0
Documentation/{ => admin-guide}/aoe/todo.rst | 0
.../{ => admin-guide}/aoe/udev-install.sh | 4 +-
Documentation/{ => admin-guide}/aoe/udev.txt | 8 +-
.../{btmrvl.txt => admin-guide/btmrvl.rst} | 0
Documentation/admin-guide/bug-hunting.rst | 4 +-
.../cgroup-v1/blkio-controller.rst | 0
.../{ => admin-guide}/cgroup-v1/cgroups.rst | 4 +-
.../{ => admin-guide}/cgroup-v1/cpuacct.rst | 0
.../{ => admin-guide}/cgroup-v1/cpusets.rst | 2 +-
.../{ => admin-guide}/cgroup-v1/devices.rst | 0
.../cgroup-v1/freezer-subsystem.rst | 0
.../{ => admin-guide}/cgroup-v1/hugetlb.rst | 0
.../{ => admin-guide}/cgroup-v1/index.rst | 2 -
.../cgroup-v1/memcg_test.rst | 4 +-
.../{ => admin-guide}/cgroup-v1/memory.rst | 0
.../{ => admin-guide}/cgroup-v1/net_cls.rst | 0
.../{ => admin-guide}/cgroup-v1/net_prio.rst | 0
.../{ => admin-guide}/cgroup-v1/pids.rst | 0
.../{ => admin-guide}/cgroup-v1/rdma.rst | 0
Documentation/admin-guide/cgroup-v2.rst | 2 +-
.../clearing-warn-once.rst} | 0
.../cpu-load.rst} | 0
.../cputopology.rst} | 0
.../efi-stub.rst} | 0
.../{highuid.txt => admin-guide/highuid.rst} | 2 +-
Documentation/admin-guide/hw-vuln/l1tf.rst | 4 +-
.../hw_random.rst} | 0
Documentation/admin-guide/index.rst | 26 +
.../{iostats.txt => admin-guide/iostats.rst} | 0
.../{ => admin-guide}/kdump/gdbmacros.txt | 0
.../{ => admin-guide}/kdump/index.rst | 1 -
.../{ => admin-guide}/kdump/kdump.rst | 0
.../{ => admin-guide}/kdump/vmcoreinfo.rst | 0
.../admin-guide/kernel-parameters.txt | 46 +-
.../kernel-per-cpu-kthreads.rst} | 4 +-
.../{ => admin-guide}/laptops/asus-laptop.rst | 0
.../laptops/disk-shock-protection.rst | 0
.../{ => admin-guide}/laptops/index.rst | 1 -
.../{ => admin-guide}/laptops/laptop-mode.rst | 0
.../{ => admin-guide}/laptops/lg-laptop.rst | 1 -
.../{ => admin-guide}/laptops/sony-laptop.rst | 0
.../{ => admin-guide}/laptops/sonypi.rst | 0
.../laptops/thinkpad-acpi.rst | 6 +-
.../laptops/toshiba_haps.rst | 0
.../lcd-panel-cgram.rst | 2 -
.../{ldm.txt => admin-guide/ldm.rst} | 3 +-
.../lockup-watchdogs.rst} | 0
.../mm/cma_debugfs.rst} | 2 -
Documentation/admin-guide/mm/index.rst | 2 +-
Documentation/admin-guide/mm/ksm.rst | 2 +-
.../admin-guide/mm/numa_memory_policy.rst | 2 +-
.../numastat.rst} | 3 +-
.../{pnp.txt => admin-guide/pnp.rst} | 11 +-
.../{rtc.txt => admin-guide/rtc.rst} | 6 +-
.../{svga.txt => admin-guide/svga.rst} | 0
.../abi.txt => admin-guide/sysctl/abi.rst} | 71 +-
.../fs.txt => admin-guide/sysctl/fs.rst} | 142 +--
.../README => admin-guide/sysctl/index.rst} | 34 +-
.../sysctl/kernel.rst} | 378 ++++----
.../net.txt => admin-guide/sysctl/net.rst} | 141 ++-
.../sysctl/sunrpc.rst} | 13 +-
.../user.txt => admin-guide/sysctl/user.rst} | 32 +-
.../vm.txt => admin-guide/sysctl/vm.rst} | 264 ++---
.../video-output.rst} | 1 -
Documentation/arm/index.rst | 2 -
Documentation/arm64/index.rst | 2 -
.../{bfq-iosched.txt => bfq-iosched.rst} | 68 +-
.../block/{biodoc.txt => biodoc.rst} | 366 ++++---
.../block/{biovecs.txt => biovecs.rst} | 20 +-
.../block/{capability.txt => capability.rst} | 17 +-
...ne-partition.txt => cmdline-partition.rst} | 13 +-
...{data-integrity.txt => data-integrity.rst} | 60 +-
...dline-iosched.txt => deadline-iosched.rst} | 21 +-
Documentation/block/index.rst | 25 +
.../block/{ioprio.txt => ioprio.rst} | 95 +-
.../{kyber-iosched.txt => kyber-iosched.rst} | 3 +-
.../block/{null_blk.txt => null_blk.rst} | 65 +-
Documentation/block/{pr.txt => pr.rst} | 18 +-
.../{queue-sysfs.txt => queue-sysfs.rst} | 7 +-
.../block/{request.txt => request.rst} | 47 +-
Documentation/block/{stat.txt => stat.rst} | 13 +-
...witching-sched.txt => switching-sched.rst} | 28 +-
...ontrol.txt => writeback_cache_control.rst} | 12 +-
...structure-v9.txt => data-structure-v9.rst} | 6 +-
Documentation/blockdev/drbd/figures.rst | 28 +
.../blockdev/drbd/{README.txt => index.rst} | 15 +-
.../blockdev/{floppy.txt => floppy.rst} | 88 +-
Documentation/blockdev/index.rst | 16 +
Documentation/blockdev/{nbd.txt => nbd.rst} | 2 +-
.../blockdev/{paride.txt => paride.rst} | 194 ++--
.../blockdev/{ramdisk.txt => ramdisk.rst} | 55 +-
Documentation/blockdev/{zram.txt => zram.rst} | 197 ++--
Documentation/core-api/printk-formats.rst | 2 +-
Documentation/device-mapper/statistics.rst | 4 +-
.../devicetree/bindings/phy/phy-bindings.txt | 2 +-
.../atomic_bitops.rst} | 1 -
.../bt8xxgpio.rst} | 1 -
.../bus-virt-phys-mapping.rst} | 52 +-
.../{connector => driver-api}/connector.rst | 2 -
.../{console => driver-api}/console.rst | 2 -
.../{crc32.txt => driver-api/crc32.rst} | 0
.../{dcdbas.txt => driver-api/dcdbas.rst} | 0
.../debugging-modules.rst} | 0
.../debugging-via-ohci1394.rst} | 0
.../{dell_rbu.txt => driver-api/dell_rbu.rst} | 1 -
.../{digsig.txt => driver-api/digsig.rst} | 0
.../{EDID/howto.rst => driver-api/edid.rst} | 2 -
.../{eisa.txt => driver-api/eisa.rst} | 0
.../futex-requeue-pi.rst} | 0
.../gcc-plugins.rst} | 0
.../hwspinlock.rst} | 0
Documentation/driver-api/index.rst | 71 +-
.../io-mapping.rst} | 0
.../io_ordering.rst} | 0
.../{IPMI.txt => driver-api/ipmi.rst} | 0
.../irq-affinity.rst} | 0
.../irq-domain.rst} | 0
Documentation/{IRQ.txt => driver-api/irq.rst} | 0
.../irqflags-tracing.rst} | 1 -
Documentation/{isa.txt => driver-api/isa.rst} | 0
.../{isapnp.txt => driver-api/isapnp.rst} | 0
.../{kobject.txt => driver-api/kobject.rst} | 4 +-
.../{kprobes.txt => driver-api/kprobes.rst} | 1 -
.../{kref.txt => driver-api/kref.rst} | 0
.../pblk.txt => driver-api/lightnvm-pblk.rst} | 0
Documentation/{lzo.txt => driver-api/lzo.rst} | 0
.../{mailbox.txt => driver-api/mailbox.rst} | 0
.../men-chameleon-bus.rst} | 0
.../mm/dma-api-howto.rst} | 0
.../mm/dma-api.rst} | 6 +-
.../mm/dma-attributes.rst} | 0
.../mm/dma-isa-lpc.rst} | 2 +-
Documentation/driver-api/mm/index.rst | 11 +
.../nommu-mmap.rst} | 0
Documentation/{ntb.txt => driver-api/ntb.rst} | 0
Documentation/{nvmem => driver-api}/nvmem.rst | 2 -
.../{padata.txt => driver-api/padata.rst} | 0
.../parport-lowlevel.rst} | 0
.../percpu-rw-semaphore.rst} | 0
.../{pi-futex.txt => driver-api/pi-futex.rst} | 0
Documentation/driver-api/pps.rst | 2 -
.../preempt-locking.rst} | 2 +-
.../{pti => driver-api}/pti_intel_mid.rst | 2 -
Documentation/driver-api/ptp.rst | 2 -
Documentation/{pwm.txt => driver-api/pwm.rst} | 0
.../{rbtree.txt => driver-api/rbtree.rst} | 52 +-
.../remoteproc.rst} | 2 +-
.../{rfkill.txt => driver-api/rfkill.rst} | 0
.../robust-futex-ABI.rst} | 0
.../robust-futexes.rst} | 0
.../{rpmsg.txt => driver-api/rpmsg.rst} | 0
.../{sgi-ioc4.txt => driver-api/sgi-ioc4.rst} | 0
.../{SM501.txt => driver-api/sm501.rst} | 0
.../smsc_ece1099.rst} | 0
.../speculation.rst} | 8 +-
.../static-keys.rst} | 0
.../switchtec.rst} | 2 +-
.../sync_file.rst} | 0
Documentation/{tee.txt => driver-api/tee.rst} | 0
.../this_cpu_ops.rst} | 0
.../unaligned-memory-access.rst} | 0
Documentation/driver-api/usb/dma.rst | 6 +-
.../vfio-mediated-device.rst} | 2 +-
.../{vfio.txt => driver-api/vfio.rst} | 0
.../{ => driver-api}/xilinx/eemi.rst | 0
.../{ => driver-api}/xilinx/index.rst | 1 -
.../{xillybus.txt => driver-api/xillybus.rst} | 0
Documentation/{xz.txt => driver-api/xz.rst} | 0
.../{zorro.txt => driver-api/zorro.rst} | 5 +-
Documentation/driver-model/device.rst | 2 +-
Documentation/fb/fbcon.rst | 4 +-
Documentation/fb/vesafb.rst | 2 +-
Documentation/filesystems/proc.txt | 2 +-
Documentation/filesystems/sysfs.txt | 2 +-
Documentation/filesystems/tmpfs.txt | 2 +-
.../acpi/extcon-intel-int3496.rst} | 14 +-
Documentation/firmware-guide/acpi/index.rst | 1 +
Documentation/gpu/drm-mm.rst | 2 +-
Documentation/ia64/index.rst | 2 -
Documentation/ia64/irq-redir.rst | 2 +-
Documentation/index.rst | 14 +
...g-up-ioctls.txt => botching-up-ioctls.rst} | 1 +
Documentation/ioctl/{cdrom.txt => cdrom.rst} | 908 +++++++++++-------
Documentation/ioctl/{hdio.txt => hdio.rst} | 835 ++++++++++------
Documentation/ioctl/index.rst | 16 +
...{ioctl-decoding.txt => ioctl-decoding.rst} | 13 +-
.../{ioctl-number.txt => ioctl-number.rst} | 588 ++++++------
Documentation/locking/rt-mutex.rst | 2 +-
Documentation/m68k/index.rst | 2 -
Documentation/memory-barriers.txt | 6 +-
Documentation/mic/index.rst | 2 -
Documentation/networking/ip-sysctl.txt | 2 +-
Documentation/networking/scaling.rst | 4 +-
.../perf/{arm-ccn.txt => arm-ccn.rst} | 18 +-
.../perf/{arm_dsu_pmu.txt => arm_dsu_pmu.rst} | 5 +-
.../perf/{hisi-pmu.txt => hisi-pmu.rst} | 35 +-
Documentation/perf/index.rst | 16 +
.../perf/{qcom_l2_pmu.txt => qcom_l2_pmu.rst} | 3 +-
.../perf/{qcom_l3_pmu.txt => qcom_l3_pmu.rst} | 3 +-
.../{thunderx2-pmu.txt => thunderx2-pmu.rst} | 25 +-
.../perf/{xgene-pmu.txt => xgene-pmu.rst} | 3 +-
Documentation/{phy.txt => phy.rst} | 2 +
Documentation/phy/samsung-usb2.rst | 2 -
.../powerpc/firmware-assisted-dump.rst | 2 +-
Documentation/process/submit-checklist.rst | 2 +-
Documentation/rapidio/index.rst | 15 +
.../{mport_cdev.txt => mport_cdev.rst} | 47 +-
.../rapidio/{rapidio.txt => rapidio.rst} | 39 +-
.../rapidio/{rio_cm.txt => rio_cm.rst} | 66 +-
.../rapidio/{sysfs.txt => sysfs.rst} | 4 +
.../rapidio/{tsi721.txt => tsi721.rst} | 45 +-
Documentation/riscv/index.rst | 2 -
Documentation/s390/index.rst | 2 -
Documentation/s390/vfio-ccw.rst | 6 +-
Documentation/scheduler/index.rst | 2 -
Documentation/scheduler/sched-deadline.rst | 2 +-
Documentation/scheduler/sched-design-CFS.rst | 2 +-
Documentation/scheduler/sched-rt-group.rst | 2 +-
Documentation/security/index.rst | 5 +-
.../security/{LSM.rst => lsm-development.rst} | 0
Documentation/{lsm.txt => security/lsm.rst} | 0
Documentation/{SAK.txt => security/sak.rst} | 1 -
.../{siphash.txt => security/siphash.rst} | 0
Documentation/security/tpm/index.rst | 1 +
Documentation/security/tpm/xen-tpmfront.rst | 2 -
Documentation/sparc/index.rst | 2 -
...pu-cooling-api.txt => cpu-cooling-api.rst} | 39 +-
.../{exynos_thermal => exynos_thermal.rst} | 47 +-
...emulation => exynos_thermal_emulation.rst} | 66 +-
Documentation/thermal/index.rst | 18 +
...el_powerclamp.txt => intel_powerclamp.rst} | 177 ++--
.../{nouveau_thermal => nouveau_thermal.rst} | 54 +-
...ower_allocator.txt => power_allocator.rst} | 140 +--
.../thermal/{sysfs-api.txt => sysfs-api.rst} | 490 ++++++----
...hermal => x86_pkg_temperature_thermal.rst} | 28 +-
Documentation/trace/kprobetrace.rst | 2 +-
.../it_IT/process/submit-checklist.rst | 2 +-
.../translations/ko_KR/memory-barriers.txt | 6 +-
Documentation/translations/zh_CN/IRQ.txt | 4 +-
.../translations/zh_CN/filesystems/sysfs.txt | 2 +-
.../translations/zh_CN/io_ordering.txt | 4 +-
.../translations/zh_CN/oops-tracing.txt | 4 +-
.../zh_CN/process/submit-checklist.rst | 2 +-
Documentation/usb/{acm.txt => acm.rst} | 0
.../{authorization.txt => authorization.rst} | 0
.../usb/{chipidea.txt => chipidea.rst} | 0
Documentation/usb/{dwc3.txt => dwc3.rst} | 0
Documentation/usb/{ehci.txt => ehci.rst} | 0
.../usb/{functionfs.txt => functionfs.rst} | 0
...{gadget-testing.txt => gadget-testing.rst} | 4 +-
...adget_configfs.txt => gadget_configfs.rst} | 0
.../usb/{gadget_hid.txt => gadget_hid.rst} | 0
.../{gadget_multi.txt => gadget_multi.rst} | 0
...{gadget_printer.txt => gadget_printer.rst} | 0
.../{gadget_serial.txt => gadget_serial.rst} | 0
Documentation/usb/index.rst | 39 +
.../usb/{iuu_phoenix.txt => iuu_phoenix.rst} | 0
.../{mass-storage.txt => mass-storage.rst} | 0
...{misc_usbsevseg.txt => misc_usbsevseg.rst} | 0
.../usb/{mtouchusb.txt => mtouchusb.rst} | 0
Documentation/usb/{ohci.txt => ohci.rst} | 0
Documentation/usb/{rio.txt => rio.rst} | 0
Documentation/usb/text_files.rst | 29 +
.../usb/{usb-help.txt => usb-help.rst} | 0
.../usb/{usb-serial.txt => usb-serial.rst} | 0
...{usbip_protocol.txt => usbip_protocol.rst} | 0
Documentation/usb/{usbmon.txt => usbmon.rst} | 0
...-overview.txt => wusb-design-overview.rst} | 0
Documentation/vm/numa.rst | 4 +-
Documentation/vm/page_migration.rst | 2 +-
Documentation/vm/unevictable-lru.rst | 4 +-
Documentation/w1/w1.netlink | 2 +-
Documentation/watchdog/hpwdt.rst | 4 +-
Documentation/x86/index.rst | 2 +
.../{Intel-IOMMU.txt => x86/intel-iommu.rst} | 1 +
.../{intel_txt.txt => x86/intel_txt.rst} | 1 +
Documentation/x86/topology.rst | 2 +-
.../x86/x86_64/fake-numa-for-cpusets.rst | 4 +-
Documentation/xtensa/index.rst | 2 -
MAINTAINERS | 106 +-
arch/Kconfig | 4 +-
arch/arm/Kconfig | 4 +-
arch/arm64/Kconfig | 2 +-
arch/ia64/hp/common/sba_iommu.c | 12 +-
arch/ia64/sn/pci/pci_dma.c | 4 +-
arch/parisc/Kconfig | 2 +-
arch/parisc/kernel/pci-dma.c | 2 +-
arch/sh/Kconfig | 4 +-
arch/sparc/Kconfig | 2 +-
arch/unicore32/include/asm/io.h | 2 +-
arch/x86/Kconfig | 8 +-
arch/x86/include/asm/dma-mapping.h | 4 +-
arch/x86/kernel/amd_gart_64.c | 2 +-
block/Kconfig | 4 +-
block/Kconfig.iosched | 2 +-
block/bfq-iosched.c | 2 +-
block/blk-integrity.c | 2 +-
block/ioprio.c | 2 +-
block/mq-deadline.c | 2 +-
block/partitions/Kconfig | 2 +-
block/partitions/cmdline.c | 2 +-
drivers/base/core.c | 2 +-
drivers/block/Kconfig | 8 +-
drivers/block/floppy.c | 2 +-
drivers/block/zram/Kconfig | 6 +-
drivers/char/Kconfig | 6 +-
drivers/char/hw_random/core.c | 2 +-
drivers/char/ipmi/Kconfig | 2 +-
drivers/char/ipmi/ipmi_si_hotmod.c | 2 +-
drivers/char/ipmi/ipmi_si_intf.c | 2 +-
drivers/dma-buf/Kconfig | 2 +-
drivers/gpio/Kconfig | 2 +-
drivers/gpu/drm/Kconfig | 2 +-
drivers/gpu/drm/drm_ioctl.c | 2 +-
drivers/parisc/sba_iommu.c | 16 +-
drivers/pci/switch/Kconfig | 2 +-
drivers/perf/qcom_l3_pmu.c | 2 +-
drivers/platform/x86/Kconfig | 8 +-
drivers/platform/x86/dcdbas.c | 2 +-
drivers/platform/x86/dell_rbu.c | 2 +-
drivers/pnp/isapnp/Kconfig | 2 +-
drivers/rapidio/Kconfig | 2 +-
drivers/tty/Kconfig | 2 +-
drivers/usb/Kconfig | 2 +-
drivers/usb/class/Kconfig | 2 +-
drivers/usb/gadget/Kconfig | 6 +-
drivers/usb/gadget/function/f_mass_storage.c | 2 +-
drivers/usb/gadget/legacy/Kconfig | 6 +-
drivers/usb/host/Kconfig | 2 +-
drivers/usb/misc/Kconfig | 2 +-
drivers/usb/mon/Kconfig | 2 +-
drivers/usb/serial/Kconfig | 10 +-
drivers/usb/serial/belkin_sa.c | 2 +-
drivers/usb/serial/belkin_sa.h | 2 +-
drivers/usb/serial/cypress_m8.c | 2 +-
drivers/usb/serial/empeg.c | 2 +-
drivers/usb/serial/ftdi_sio.c | 2 +-
drivers/usb/serial/ir-usb.c | 2 +-
drivers/usb/serial/keyspan_pda.c | 2 +-
drivers/usb/serial/omninet.c | 2 +-
drivers/usb/serial/oti6858.c | 2 +-
drivers/usb/serial/pl2303.c | 2 +-
drivers/usb/serial/usb-serial.c | 2 +-
drivers/usb/serial/visor.c | 2 +-
drivers/usb/serial/visor.h | 2 +-
drivers/usb/serial/whiteheat.c | 2 +-
drivers/usb/serial/whiteheat.h | 2 +-
drivers/vfio/Kconfig | 2 +-
drivers/vfio/mdev/Kconfig | 2 +-
drivers/w1/Kconfig | 2 +-
fs/proc/Kconfig | 2 +-
include/asm-generic/bitops/atomic.h | 2 +-
include/linux/cgroup-defs.h | 2 +-
include/linux/dma-mapping.h | 2 +-
include/linux/hw_random.h | 2 +-
include/linux/io-mapping.h | 2 +-
include/linux/jump_label.h | 2 +-
include/linux/kobject.h | 2 +-
include/linux/kobject_ns.h | 2 +-
include/linux/rbtree.h | 2 +-
include/linux/rbtree_augmented.h | 2 +-
include/linux/thermal.h | 4 +-
include/media/videobuf-dma-sg.h | 2 +-
include/uapi/linux/bpf.h | 2 +-
include/uapi/rdma/rdma_user_ioctl_cmds.h | 2 +-
init/Kconfig | 6 +-
kernel/cgroup/cpuset.c | 2 +-
kernel/dma/debug.c | 2 +-
kernel/padata.c | 2 +-
kernel/panic.c | 2 +-
lib/Kconfig | 2 +-
lib/Kconfig.debug | 2 +-
lib/crc32.c | 2 +-
lib/kobject.c | 4 +-
lib/lzo/lzo1x_decompress_safe.c | 2 +-
lib/xz/Kconfig | 2 +-
mm/Kconfig | 2 +-
mm/nommu.c | 2 +-
mm/swap.c | 2 +-
samples/Kconfig | 2 +-
samples/kprobes/kprobe_example.c | 2 +-
samples/kprobes/kretprobe_example.c | 2 +-
scripts/gcc-plugins/Kconfig | 2 +-
security/Kconfig | 2 +-
security/device_cgroup.c | 2 +-
tools/include/linux/rbtree.h | 2 +-
tools/include/linux/rbtree_augmented.h | 2 +-
tools/include/uapi/linux/bpf.h | 2 +-
tools/testing/selftests/zram/README | 2 +-
405 files changed, 4491 insertions(+), 2896 deletions(-)
rename Documentation/{ => admin-guide}/aoe/aoe.rst (97%)
rename Documentation/{ => admin-guide}/aoe/autoload.sh (99%)
rename Documentation/{ => admin-guide}/aoe/examples.rst (100%)
rename Documentation/{ => admin-guide}/aoe/index.rst (95%)
rename Documentation/{ => admin-guide}/aoe/status.sh (100%)
rename Documentation/{ => admin-guide}/aoe/todo.rst (100%)
rename Documentation/{ => admin-guide}/aoe/udev-install.sh (92%)
rename Documentation/{ => admin-guide}/aoe/udev.txt (91%)
rename Documentation/{btmrvl.txt => admin-guide/btmrvl.rst} (100%)
rename Documentation/{ => admin-guide}/cgroup-v1/blkio-controller.rst (100%)
rename Documentation/{ => admin-guide}/cgroup-v1/cgroups.rst (99%)
rename Documentation/{ => admin-guide}/cgroup-v1/cpuacct.rst (100%)
rename Documentation/{ => admin-guide}/cgroup-v1/cpusets.rst (99%)
rename Documentation/{ => admin-guide}/cgroup-v1/devices.rst (100%)
rename Documentation/{ => admin-guide}/cgroup-v1/freezer-subsystem.rst (100%)
rename Documentation/{ => admin-guide}/cgroup-v1/hugetlb.rst (100%)
rename Documentation/{ => admin-guide}/cgroup-v1/index.rst (97%)
rename Documentation/{ => admin-guide}/cgroup-v1/memcg_test.rst (98%)
rename Documentation/{ => admin-guide}/cgroup-v1/memory.rst (100%)
rename Documentation/{ => admin-guide}/cgroup-v1/net_cls.rst (100%)
rename Documentation/{ => admin-guide}/cgroup-v1/net_prio.rst (100%)
rename Documentation/{ => admin-guide}/cgroup-v1/pids.rst (100%)
rename Documentation/{ => admin-guide}/cgroup-v1/rdma.rst (100%)
rename Documentation/{clearing-warn-once.txt => admin-guide/clearing-warn-once.rst} (100%)
rename Documentation/{cpu-load.txt => admin-guide/cpu-load.rst} (100%)
rename Documentation/{cputopology.txt => admin-guide/cputopology.rst} (100%)
rename Documentation/{efi-stub.txt => admin-guide/efi-stub.rst} (100%)
rename Documentation/{highuid.txt => admin-guide/highuid.rst} (99%)
rename Documentation/{hw_random.txt => admin-guide/hw_random.rst} (100%)
rename Documentation/{iostats.txt => admin-guide/iostats.rst} (100%)
rename Documentation/{ => admin-guide}/kdump/gdbmacros.txt (100%)
rename Documentation/{ => admin-guide}/kdump/index.rst (97%)
rename Documentation/{ => admin-guide}/kdump/kdump.rst (100%)
rename Documentation/{ => admin-guide}/kdump/vmcoreinfo.rst (100%)
rename Documentation/{kernel-per-CPU-kthreads.txt => admin-guide/kernel-per-cpu-kthreads.rst} (98%)
rename Documentation/{ => admin-guide}/laptops/asus-laptop.rst (100%)
rename Documentation/{ => admin-guide}/laptops/disk-shock-protection.rst (100%)
rename Documentation/{ => admin-guide}/laptops/index.rst (95%)
rename Documentation/{ => admin-guide}/laptops/laptop-mode.rst (100%)
rename Documentation/{ => admin-guide}/laptops/lg-laptop.rst (99%)
rename Documentation/{ => admin-guide}/laptops/sony-laptop.rst (100%)
rename Documentation/{ => admin-guide}/laptops/sonypi.rst (100%)
rename Documentation/{ => admin-guide}/laptops/thinkpad-acpi.rst (99%)
rename Documentation/{ => admin-guide}/laptops/toshiba_haps.rst (100%)
rename Documentation/{auxdisplay => admin-guide}/lcd-panel-cgram.rst (99%)
rename Documentation/{ldm.txt => admin-guide/ldm.rst} (98%)
rename Documentation/{lockup-watchdogs.txt => admin-guide/lockup-watchdogs.rst} (100%)
rename Documentation/{cma/debugfs.rst => admin-guide/mm/cma_debugfs.rst} (98%)
rename Documentation/{numastat.txt => admin-guide/numastat.rst} (93%)
rename Documentation/{pnp.txt => admin-guide/pnp.rst} (98%)
rename Documentation/{rtc.txt => admin-guide/rtc.rst} (99%)
rename Documentation/{svga.txt => admin-guide/svga.rst} (100%)
rename Documentation/{sysctl/abi.txt => admin-guide/sysctl/abi.rst} (30%)
rename Documentation/{sysctl/fs.txt => admin-guide/sysctl/fs.rst} (77%)
rename Documentation/{sysctl/README => admin-guide/sysctl/index.rst} (78%)
rename Documentation/{sysctl/kernel.txt => admin-guide/sysctl/kernel.rst} (79%)
rename Documentation/{sysctl/net.txt => admin-guide/sysctl/net.rst} (85%)
rename Documentation/{sysctl/sunrpc.txt => admin-guide/sysctl/sunrpc.rst} (62%)
rename Documentation/{sysctl/user.txt => admin-guide/sysctl/user.rst} (77%)
rename Documentation/{sysctl/vm.txt => admin-guide/sysctl/vm.rst} (84%)
rename Documentation/{video-output.txt => admin-guide/video-output.rst} (99%)
rename Documentation/block/{bfq-iosched.txt => bfq-iosched.rst} (95%)
rename Documentation/block/{biodoc.txt => biodoc.rst} (83%)
rename Documentation/block/{biovecs.txt => biovecs.rst} (92%)
rename Documentation/block/{capability.txt => capability.rst} (40%)
rename Documentation/block/{cmdline-partition.txt => cmdline-partition.rst} (92%)
rename Documentation/block/{data-integrity.txt => data-integrity.rst} (91%)
rename Documentation/block/{deadline-iosched.txt => deadline-iosched.rst} (89%)
create mode 100644 Documentation/block/index.rst
rename Documentation/block/{ioprio.txt => ioprio.rst} (75%)
rename Documentation/block/{kyber-iosched.txt => kyber-iosched.rst} (86%)
rename Documentation/block/{null_blk.txt => null_blk.rst} (60%)
rename Documentation/block/{pr.txt => pr.rst} (93%)
rename Documentation/block/{queue-sysfs.txt => queue-sysfs.rst} (99%)
rename Documentation/block/{request.txt => request.rst} (59%)
rename Documentation/block/{stat.txt => stat.rst} (89%)
rename Documentation/block/{switching-sched.txt => switching-sched.rst} (67%)
rename Documentation/block/{writeback_cache_control.txt => writeback_cache_control.rst} (94%)
rename Documentation/blockdev/drbd/{data-structure-v9.txt => data-structure-v9.rst} (94%)
create mode 100644 Documentation/blockdev/drbd/figures.rst
rename Documentation/blockdev/drbd/{README.txt => index.rst} (55%)
rename Documentation/blockdev/{floppy.txt => floppy.rst} (81%)
create mode 100644 Documentation/blockdev/index.rst
rename Documentation/blockdev/{nbd.txt => nbd.rst} (96%)
rename Documentation/blockdev/{paride.txt => paride.rst} (81%)
rename Documentation/blockdev/{ramdisk.txt => ramdisk.rst} (84%)
rename Documentation/blockdev/{zram.txt => zram.rst} (76%)
rename Documentation/{atomic_bitops.txt => driver-api/atomic_bitops.rst} (99%)
rename Documentation/{bt8xxgpio.txt => driver-api/bt8xxgpio.rst} (99%)
rename Documentation/{bus-virt-phys-mapping.txt => driver-api/bus-virt-phys-mapping.rst} (93%)
rename Documentation/{connector => driver-api}/connector.rst (99%)
rename Documentation/{console => driver-api}/console.rst (99%)
rename Documentation/{crc32.txt => driver-api/crc32.rst} (100%)
rename Documentation/{dcdbas.txt => driver-api/dcdbas.rst} (100%)
rename Documentation/{debugging-modules.txt => driver-api/debugging-modules.rst} (100%)
rename Documentation/{debugging-via-ohci1394.txt => driver-api/debugging-via-ohci1394.rst} (100%)
rename Documentation/{dell_rbu.txt => driver-api/dell_rbu.rst} (99%)
rename Documentation/{digsig.txt => driver-api/digsig.rst} (100%)
rename Documentation/{EDID/howto.rst => driver-api/edid.rst} (99%)
rename Documentation/{eisa.txt => driver-api/eisa.rst} (100%)
rename Documentation/{futex-requeue-pi.txt => driver-api/futex-requeue-pi.rst} (100%)
rename Documentation/{gcc-plugins.txt => driver-api/gcc-plugins.rst} (100%)
rename Documentation/{hwspinlock.txt => driver-api/hwspinlock.rst} (100%)
rename Documentation/{io-mapping.txt => driver-api/io-mapping.rst} (100%)
rename Documentation/{io_ordering.txt => driver-api/io_ordering.rst} (100%)
rename Documentation/{IPMI.txt => driver-api/ipmi.rst} (100%)
rename Documentation/{IRQ-affinity.txt => driver-api/irq-affinity.rst} (100%)
rename Documentation/{IRQ-domain.txt => driver-api/irq-domain.rst} (100%)
rename Documentation/{IRQ.txt => driver-api/irq.rst} (100%)
rename Documentation/{irqflags-tracing.txt => driver-api/irqflags-tracing.rst} (99%)
rename Documentation/{isa.txt => driver-api/isa.rst} (100%)
rename Documentation/{isapnp.txt => driver-api/isapnp.rst} (100%)
rename Documentation/{kobject.txt => driver-api/kobject.rst} (99%)
rename Documentation/{kprobes.txt => driver-api/kprobes.rst} (99%)
rename Documentation/{kref.txt => driver-api/kref.rst} (100%)
rename Documentation/{lightnvm/pblk.txt => driver-api/lightnvm-pblk.rst} (100%)
rename Documentation/{lzo.txt => driver-api/lzo.rst} (100%)
rename Documentation/{mailbox.txt => driver-api/mailbox.rst} (100%)
rename Documentation/{men-chameleon-bus.txt => driver-api/men-chameleon-bus.rst} (100%)
rename Documentation/{DMA-API-HOWTO.txt => driver-api/mm/dma-api-howto.rst} (100%)
rename Documentation/{DMA-API.txt => driver-api/mm/dma-api.rst} (99%)
rename Documentation/{DMA-attributes.txt => driver-api/mm/dma-attributes.rst} (100%)
rename Documentation/{DMA-ISA-LPC.txt => driver-api/mm/dma-isa-lpc.rst} (98%)
create mode 100644 Documentation/driver-api/mm/index.rst
rename Documentation/{nommu-mmap.txt => driver-api/nommu-mmap.rst} (100%)
rename Documentation/{ntb.txt => driver-api/ntb.rst} (100%)
rename Documentation/{nvmem => driver-api}/nvmem.rst (99%)
rename Documentation/{padata.txt => driver-api/padata.rst} (100%)
rename Documentation/{parport-lowlevel.txt => driver-api/parport-lowlevel.rst} (100%)
rename Documentation/{percpu-rw-semaphore.txt => driver-api/percpu-rw-semaphore.rst} (100%)
rename Documentation/{pi-futex.txt => driver-api/pi-futex.rst} (100%)
rename Documentation/{preempt-locking.txt => driver-api/preempt-locking.rst} (99%)
rename Documentation/{pti => driver-api}/pti_intel_mid.rst (99%)
rename Documentation/{pwm.txt => driver-api/pwm.rst} (100%)
rename Documentation/{rbtree.txt => driver-api/rbtree.rst} (94%)
rename Documentation/{remoteproc.txt => driver-api/remoteproc.rst} (99%)
rename Documentation/{rfkill.txt => driver-api/rfkill.rst} (100%)
rename Documentation/{robust-futex-ABI.txt => driver-api/robust-futex-ABI.rst} (100%)
rename Documentation/{robust-futexes.txt => driver-api/robust-futexes.rst} (100%)
rename Documentation/{rpmsg.txt => driver-api/rpmsg.rst} (100%)
rename Documentation/{sgi-ioc4.txt => driver-api/sgi-ioc4.rst} (100%)
rename Documentation/{SM501.txt => driver-api/sm501.rst} (100%)
rename Documentation/{smsc_ece1099.txt => driver-api/smsc_ece1099.rst} (100%)
rename Documentation/{speculation.txt => driver-api/speculation.rst} (100%)
rename Documentation/{static-keys.txt => driver-api/static-keys.rst} (100%)
rename Documentation/{switchtec.txt => driver-api/switchtec.rst} (97%)
rename Documentation/{sync_file.txt => driver-api/sync_file.rst} (100%)
rename Documentation/{tee.txt => driver-api/tee.rst} (100%)
rename Documentation/{this_cpu_ops.txt => driver-api/this_cpu_ops.rst} (100%)
rename Documentation/{unaligned-memory-access.txt => driver-api/unaligned-memory-access.rst} (100%)
rename Documentation/{vfio-mediated-device.txt => driver-api/vfio-mediated-device.rst} (99%)
rename Documentation/{vfio.txt => driver-api/vfio.rst} (100%)
rename Documentation/{ => driver-api}/xilinx/eemi.rst (100%)
rename Documentation/{ => driver-api}/xilinx/index.rst (94%)
rename Documentation/{xillybus.txt => driver-api/xillybus.rst} (100%)
rename Documentation/{xz.txt => driver-api/xz.rst} (100%)
rename Documentation/{zorro.txt => driver-api/zorro.rst} (99%)
rename Documentation/{extcon/intel-int3496.txt => firmware-guide/acpi/extcon-intel-int3496.rst} (66%)
rename Documentation/ioctl/{botching-up-ioctls.txt => botching-up-ioctls.rst} (99%)
rename Documentation/ioctl/{cdrom.txt => cdrom.rst} (39%)
rename Documentation/ioctl/{hdio.txt => hdio.rst} (54%)
create mode 100644 Documentation/ioctl/index.rst
rename Documentation/ioctl/{ioctl-decoding.txt => ioctl-decoding.rst} (54%)
rename Documentation/ioctl/{ioctl-number.txt => ioctl-number.rst} (11%)
rename Documentation/perf/{arm-ccn.txt => arm-ccn.rst} (86%)
rename Documentation/perf/{arm_dsu_pmu.txt => arm_dsu_pmu.rst} (92%)
rename Documentation/perf/{hisi-pmu.txt => hisi-pmu.rst} (73%)
create mode 100644 Documentation/perf/index.rst
rename Documentation/perf/{qcom_l2_pmu.txt => qcom_l2_pmu.rst} (94%)
rename Documentation/perf/{qcom_l3_pmu.txt => qcom_l3_pmu.rst} (93%)
rename Documentation/perf/{thunderx2-pmu.txt => thunderx2-pmu.rst} (73%)
rename Documentation/perf/{xgene-pmu.txt => xgene-pmu.rst} (96%)
rename Documentation/{phy.txt => phy.rst} (99%)
create mode 100644 Documentation/rapidio/index.rst
rename Documentation/rapidio/{mport_cdev.txt => mport_cdev.rst} (84%)
rename Documentation/rapidio/{rapidio.txt => rapidio.rst} (97%)
rename Documentation/rapidio/{rio_cm.txt => rio_cm.rst} (76%)
rename Documentation/rapidio/{sysfs.txt => sysfs.rst} (75%)
rename Documentation/rapidio/{tsi721.txt => tsi721.rst} (79%)
rename Documentation/security/{LSM.rst => lsm-development.rst} (100%)
rename Documentation/{lsm.txt => security/lsm.rst} (100%)
rename Documentation/{SAK.txt => security/sak.rst} (99%)
rename Documentation/{siphash.txt => security/siphash.rst} (100%)
rename Documentation/thermal/{cpu-cooling-api.txt => cpu-cooling-api.rst} (82%)
rename Documentation/thermal/{exynos_thermal => exynos_thermal.rst} (67%)
rename Documentation/thermal/{exynos_thermal_emulation => exynos_thermal_emulation.rst} (36%)
create mode 100644 Documentation/thermal/index.rst
rename Documentation/thermal/{intel_powerclamp.txt => intel_powerclamp.rst} (76%)
rename Documentation/thermal/{nouveau_thermal => nouveau_thermal.rst} (64%)
rename Documentation/thermal/{power_allocator.txt => power_allocator.rst} (74%)
rename Documentation/thermal/{sysfs-api.txt => sysfs-api.rst} (66%)
rename Documentation/thermal/{x86_pkg_temperature_thermal => x86_pkg_temperature_thermal.rst} (80%)
rename Documentation/usb/{acm.txt => acm.rst} (100%)
rename Documentation/usb/{authorization.txt => authorization.rst} (100%)
rename Documentation/usb/{chipidea.txt => chipidea.rst} (100%)
rename Documentation/usb/{dwc3.txt => dwc3.rst} (100%)
rename Documentation/usb/{ehci.txt => ehci.rst} (100%)
rename Documentation/usb/{functionfs.txt => functionfs.rst} (100%)
rename Documentation/usb/{gadget-testing.txt => gadget-testing.rst} (99%)
rename Documentation/usb/{gadget_configfs.txt => gadget_configfs.rst} (100%)
rename Documentation/usb/{gadget_hid.txt => gadget_hid.rst} (100%)
rename Documentation/usb/{gadget_multi.txt => gadget_multi.rst} (100%)
rename Documentation/usb/{gadget_printer.txt => gadget_printer.rst} (100%)
rename Documentation/usb/{gadget_serial.txt => gadget_serial.rst} (100%)
create mode 100644 Documentation/usb/index.rst
rename Documentation/usb/{iuu_phoenix.txt => iuu_phoenix.rst} (100%)
rename Documentation/usb/{mass-storage.txt => mass-storage.rst} (100%)
rename Documentation/usb/{misc_usbsevseg.txt => misc_usbsevseg.rst} (100%)
rename Documentation/usb/{mtouchusb.txt => mtouchusb.rst} (100%)
rename Documentation/usb/{ohci.txt => ohci.rst} (100%)
rename Documentation/usb/{rio.txt => rio.rst} (100%)
create mode 100644 Documentation/usb/text_files.rst
rename Documentation/usb/{usb-help.txt => usb-help.rst} (100%)
rename Documentation/usb/{usb-serial.txt => usb-serial.rst} (100%)
rename Documentation/usb/{usbip_protocol.txt => usbip_protocol.rst} (100%)
rename Documentation/usb/{usbmon.txt => usbmon.rst} (100%)
rename Documentation/usb/{WUSB-Design-overview.txt => wusb-design-overview.rst} (100%)
rename Documentation/{Intel-IOMMU.txt => x86/intel-iommu.rst} (99%)
rename Documentation/{intel_txt.txt => x86/intel_txt.rst} (99%)
--
2.21.0
^ permalink raw reply
* [PATCH v1 21/22] docs: admin-guide: add laptops documentation
From: Mauro Carvalho Chehab @ 2019-06-18 21:05 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Matan Ziv-Av, Mattia Dongili, Arnd Bergmann,
Greg Kroah-Hartman, Darren Hart, Andy Shevchenko,
platform-driver-x86
In-Reply-To: <cover.1560891322.git.mchehab+samsung@kernel.org>
The docs under Documentation/laptops contain users specific
information.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/ABI/testing/sysfs-block-device | 2 +-
Documentation/ABI/testing/sysfs-platform-asus-laptop | 2 +-
Documentation/admin-guide/index.rst | 1 +
Documentation/admin-guide/kernel-parameters.txt | 2 +-
Documentation/{ => admin-guide}/laptops/asus-laptop.rst | 0
.../{ => admin-guide}/laptops/disk-shock-protection.rst | 0
Documentation/{ => admin-guide}/laptops/index.rst | 1 -
Documentation/{ => admin-guide}/laptops/laptop-mode.rst | 0
Documentation/{ => admin-guide}/laptops/lg-laptop.rst | 1 -
Documentation/{ => admin-guide}/laptops/sony-laptop.rst | 0
Documentation/{ => admin-guide}/laptops/sonypi.rst | 0
Documentation/{ => admin-guide}/laptops/thinkpad-acpi.rst | 0
Documentation/{ => admin-guide}/laptops/toshiba_haps.rst | 0
Documentation/admin-guide/sysctl/vm.rst | 4 ++--
MAINTAINERS | 4 ++--
drivers/char/Kconfig | 2 +-
drivers/platform/x86/Kconfig | 4 ++--
17 files changed, 11 insertions(+), 12 deletions(-)
rename Documentation/{ => admin-guide}/laptops/asus-laptop.rst (100%)
rename Documentation/{ => admin-guide}/laptops/disk-shock-protection.rst (100%)
rename Documentation/{ => admin-guide}/laptops/index.rst (95%)
rename Documentation/{ => admin-guide}/laptops/laptop-mode.rst (100%)
rename Documentation/{ => admin-guide}/laptops/lg-laptop.rst (99%)
rename Documentation/{ => admin-guide}/laptops/sony-laptop.rst (100%)
rename Documentation/{ => admin-guide}/laptops/sonypi.rst (100%)
rename Documentation/{ => admin-guide}/laptops/thinkpad-acpi.rst (100%)
rename Documentation/{ => admin-guide}/laptops/toshiba_haps.rst (100%)
diff --git a/Documentation/ABI/testing/sysfs-block-device b/Documentation/ABI/testing/sysfs-block-device
index 0d57bbb4fddc..17f2bc7dd261 100644
--- a/Documentation/ABI/testing/sysfs-block-device
+++ b/Documentation/ABI/testing/sysfs-block-device
@@ -45,7 +45,7 @@ Description:
- Values below -2 are rejected with -EINVAL
For more information, see
- Documentation/laptops/disk-shock-protection.rst
+ Documentation/admin-guide/laptops/disk-shock-protection.rst
What: /sys/block/*/device/ncq_prio_enable
diff --git a/Documentation/ABI/testing/sysfs-platform-asus-laptop b/Documentation/ABI/testing/sysfs-platform-asus-laptop
index d67fa4bafa70..8b0e8205a6a2 100644
--- a/Documentation/ABI/testing/sysfs-platform-asus-laptop
+++ b/Documentation/ABI/testing/sysfs-platform-asus-laptop
@@ -31,7 +31,7 @@ Description:
To control the LED display, use the following :
echo 0x0T000DDD > /sys/devices/platform/asus_laptop/
where T control the 3 letters display, and DDD the 3 digits display.
- The DDD table can be found in Documentation/laptops/asus-laptop.rst
+ The DDD table can be found in Documentation/admin-guide/laptops/asus-laptop.rst
What: /sys/devices/platform/asus_laptop/bluetooth
Date: January 2007
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 5940ce8d16af..e4f0cb2a02bd 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -79,6 +79,7 @@ configure specific aspects of kernel behavior to your liking.
aoe/index
perf-security
acpi/index
+ laptops/index
btmrvl
clearing-warn-once
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 0b17312b9198..69a9e2e66dfb 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -4356,7 +4356,7 @@
Format: <integer>
sonypi.*= [HW] Sony Programmable I/O Control Device driver
- See Documentation/laptops/sonypi.rst
+ See Documentation/admin-guide/laptops/sonypi.rst
spectre_v2= [X86] Control mitigation of Spectre variant 2
(indirect branch speculation) vulnerability.
diff --git a/Documentation/laptops/asus-laptop.rst b/Documentation/admin-guide/laptops/asus-laptop.rst
similarity index 100%
rename from Documentation/laptops/asus-laptop.rst
rename to Documentation/admin-guide/laptops/asus-laptop.rst
diff --git a/Documentation/laptops/disk-shock-protection.rst b/Documentation/admin-guide/laptops/disk-shock-protection.rst
similarity index 100%
rename from Documentation/laptops/disk-shock-protection.rst
rename to Documentation/admin-guide/laptops/disk-shock-protection.rst
diff --git a/Documentation/laptops/index.rst b/Documentation/admin-guide/laptops/index.rst
similarity index 95%
rename from Documentation/laptops/index.rst
rename to Documentation/admin-guide/laptops/index.rst
index 001a30910d09..6b554e39863b 100644
--- a/Documentation/laptops/index.rst
+++ b/Documentation/admin-guide/laptops/index.rst
@@ -1,4 +1,3 @@
-:orphan:
==============
Laptop Drivers
diff --git a/Documentation/laptops/laptop-mode.rst b/Documentation/admin-guide/laptops/laptop-mode.rst
similarity index 100%
rename from Documentation/laptops/laptop-mode.rst
rename to Documentation/admin-guide/laptops/laptop-mode.rst
diff --git a/Documentation/laptops/lg-laptop.rst b/Documentation/admin-guide/laptops/lg-laptop.rst
similarity index 99%
rename from Documentation/laptops/lg-laptop.rst
rename to Documentation/admin-guide/laptops/lg-laptop.rst
index f2c2ffe31101..ce9b14671cb9 100644
--- a/Documentation/laptops/lg-laptop.rst
+++ b/Documentation/admin-guide/laptops/lg-laptop.rst
@@ -1,6 +1,5 @@
.. SPDX-License-Identifier: GPL-2.0+
-:orphan:
LG Gram laptop extra features
=============================
diff --git a/Documentation/laptops/sony-laptop.rst b/Documentation/admin-guide/laptops/sony-laptop.rst
similarity index 100%
rename from Documentation/laptops/sony-laptop.rst
rename to Documentation/admin-guide/laptops/sony-laptop.rst
diff --git a/Documentation/laptops/sonypi.rst b/Documentation/admin-guide/laptops/sonypi.rst
similarity index 100%
rename from Documentation/laptops/sonypi.rst
rename to Documentation/admin-guide/laptops/sonypi.rst
diff --git a/Documentation/laptops/thinkpad-acpi.rst b/Documentation/admin-guide/laptops/thinkpad-acpi.rst
similarity index 100%
rename from Documentation/laptops/thinkpad-acpi.rst
rename to Documentation/admin-guide/laptops/thinkpad-acpi.rst
diff --git a/Documentation/laptops/toshiba_haps.rst b/Documentation/admin-guide/laptops/toshiba_haps.rst
similarity index 100%
rename from Documentation/laptops/toshiba_haps.rst
rename to Documentation/admin-guide/laptops/toshiba_haps.rst
diff --git a/Documentation/admin-guide/sysctl/vm.rst b/Documentation/admin-guide/sysctl/vm.rst
index 4940ab610eb7..d918b11326f3 100644
--- a/Documentation/admin-guide/sysctl/vm.rst
+++ b/Documentation/admin-guide/sysctl/vm.rst
@@ -108,7 +108,7 @@ block_dump
==========
block_dump enables block I/O debugging when set to a nonzero value. More
-information on block I/O debugging is in Documentation/laptops/laptop-mode.rst.
+information on block I/O debugging is in Documentation/admin-guide/laptops/laptop-mode.rst.
compact_memory
@@ -298,7 +298,7 @@ laptop_mode
===========
laptop_mode is a knob that controls "laptop mode". All the things that are
-controlled by this knob are discussed in Documentation/laptops/laptop-mode.rst.
+controlled by this knob are discussed in Documentation/admin-guide/laptops/laptop-mode.rst.
legacy_va_layout
diff --git a/MAINTAINERS b/MAINTAINERS
index b7c81bd0f8e8..ab170522ec55 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -8927,7 +8927,7 @@ M: Matan Ziv-Av <matan@svgalib.org>
L: platform-driver-x86@vger.kernel.org
S: Maintained
F: Documentation/ABI/testing/sysfs-platform-lg-laptop
-F: Documentation/laptops/lg-laptop.rst
+F: Documentation/admin-guide/laptops/lg-laptop.rst
F: drivers/platform/x86/lg-laptop.c
LG2160 MEDIA DRIVER
@@ -14756,7 +14756,7 @@ M: Mattia Dongili <malattia@linux.it>
L: platform-driver-x86@vger.kernel.org
W: http://www.linux.it/~malattia/wiki/index.php/Sony_drivers
S: Maintained
-F: Documentation/laptops/sony-laptop.rst
+F: Documentation/admin-guide/laptops/sony-laptop.rst
F: drivers/char/sonypi.c
F: drivers/platform/x86/sony-laptop.c
F: include/linux/sony-laptop.h
diff --git a/drivers/char/Kconfig b/drivers/char/Kconfig
index 3a0f94929814..3e866885a405 100644
--- a/drivers/char/Kconfig
+++ b/drivers/char/Kconfig
@@ -382,7 +382,7 @@ config SONYPI
Device which can be found in many (all ?) Sony Vaio laptops.
If you have one of those laptops, read
- <file:Documentation/laptops/sonypi.rst>, and say Y or M here.
+ <file:Documentation/admin-guide/laptops/sonypi.rst>, and say Y or M here.
To compile this driver as a module, choose M here: the
module will be called sonypi.
diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig
index 9d866b6753fe..430f7f619553 100644
--- a/drivers/platform/x86/Kconfig
+++ b/drivers/platform/x86/Kconfig
@@ -451,7 +451,7 @@ config SONY_LAPTOP
screen brightness control, Fn keys and allows powering on/off some
devices.
- Read <file:Documentation/laptops/sony-laptop.rst> for more information.
+ Read <file:Documentation/admin-guide/laptops/sony-laptop.rst> for more information.
config SONYPI_COMPAT
bool "Sonypi compatibility"
@@ -503,7 +503,7 @@ config THINKPAD_ACPI
support for Fn-Fx key combinations, Bluetooth control, video
output switching, ThinkLight control, UltraBay eject and more.
For more information about this driver see
- <file:Documentation/laptops/thinkpad-acpi.rst> and
+ <file:Documentation/admin-guide/laptops/thinkpad-acpi.rst> and
<http://ibm-acpi.sf.net/> .
This driver was formerly known as ibm-acpi.
--
2.21.0
^ permalink raw reply related
* [PATCH v1 03/22] docs: ioctl: convert to ReST
From: Mauro Carvalho Chehab @ 2019-06-18 21:05 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Maarten Lankhorst, Maxime Ripard, Sean Paul,
David Airlie, Daniel Vetter, dri-devel
In-Reply-To: <cover.1560891322.git.mchehab+samsung@kernel.org>
Rename the iio 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 cdrom.txt and hdio.txt have their own particular syntax.
In order to speedup the conversion, I used a small ancillary
perl script:
my $d;
$d .= $_ while(<>);
$d =~ s/(\nCDROM\S+)\s+(\w[^\n]*)/$1\n\t$2\n/g;
$d =~ s/(\nHDIO\S+)\s+(\w[^\n]*)/$1\n\t$2\n/g;
$d =~ s/(\n\s*usage:)[\s\n]*(\w[^\n]*)/$1:\n\n\t $2\n/g;
$d =~ s/(\n\s*)(E\w+[\s\n]*\w[^\n]*)/$1- $2/g;
$d =~ s/(\n\s*)(inputs|outputs|notes):\s*(\w[^\n]*)/$1$2:\n\t\t$3\n/g;
print $d;
It basically add blank lines on a few interesting places. The
script is not perfect: still several things require manual work,
but it saved quite some time doing some obvious stuff.
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: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
...g-up-ioctls.txt => botching-up-ioctls.rst} | 1 +
Documentation/ioctl/{cdrom.txt => cdrom.rst} | 908 +++++++++++-------
Documentation/ioctl/{hdio.txt => hdio.rst} | 835 ++++++++++------
Documentation/ioctl/index.rst | 16 +
...{ioctl-decoding.txt => ioctl-decoding.rst} | 13 +-
drivers/gpu/drm/drm_ioctl.c | 2 +-
6 files changed, 1168 insertions(+), 607 deletions(-)
rename Documentation/ioctl/{botching-up-ioctls.txt => botching-up-ioctls.rst} (99%)
rename Documentation/ioctl/{cdrom.txt => cdrom.rst} (39%)
rename Documentation/ioctl/{hdio.txt => hdio.rst} (54%)
create mode 100644 Documentation/ioctl/index.rst
rename Documentation/ioctl/{ioctl-decoding.txt => ioctl-decoding.rst} (54%)
diff --git a/Documentation/ioctl/botching-up-ioctls.txt b/Documentation/ioctl/botching-up-ioctls.rst
similarity index 99%
rename from Documentation/ioctl/botching-up-ioctls.txt
rename to Documentation/ioctl/botching-up-ioctls.rst
index 883fb034bd04..ac697fef3545 100644
--- a/Documentation/ioctl/botching-up-ioctls.txt
+++ b/Documentation/ioctl/botching-up-ioctls.rst
@@ -1,3 +1,4 @@
+=================================
(How to avoid) Botching up ioctls
=================================
diff --git a/Documentation/ioctl/cdrom.txt b/Documentation/ioctl/cdrom.rst
similarity index 39%
rename from Documentation/ioctl/cdrom.txt
rename to Documentation/ioctl/cdrom.rst
index a4d62a9d6771..3b4c0506de46 100644
--- a/Documentation/ioctl/cdrom.txt
+++ b/Documentation/ioctl/cdrom.rst
@@ -1,9 +1,10 @@
- Summary of CDROM ioctl calls.
- ============================
+============================
+Summary of CDROM ioctl calls
+============================
- Edward A. Falk <efalk@google.com>
+- Edward A. Falk <efalk@google.com>
- November, 2004
+November, 2004
This document attempts to describe the ioctl(2) calls supported by
the CDROM layer. These are by-and-large implemented (as of Linux 2.6)
@@ -12,6 +13,7 @@ in drivers/cdrom/cdrom.c and drivers/block/scsi_ioctl.c
ioctl values are listed in <linux/cdrom.h>. As of this writing, they
are as follows:
+ ====================== ===============================================
CDROMPAUSE Pause Audio Operation
CDROMRESUME Resume paused Audio Operation
CDROMPLAYMSF Play Audio MSF (struct cdrom_msf)
@@ -24,22 +26,22 @@ are as follows:
CDROMVOLCTRL Control output volume (struct cdrom_volctrl)
CDROMSUBCHNL Read subchannel data (struct cdrom_subchnl)
CDROMREADMODE2 Read CDROM mode 2 data (2336 Bytes)
- (struct cdrom_read)
+ (struct cdrom_read)
CDROMREADMODE1 Read CDROM mode 1 data (2048 Bytes)
- (struct cdrom_read)
+ (struct cdrom_read)
CDROMREADAUDIO (struct cdrom_read_audio)
CDROMEJECT_SW enable(1)/disable(0) auto-ejecting
CDROMMULTISESSION Obtain the start-of-last-session
- address of multi session disks
- (struct cdrom_multisession)
+ address of multi session disks
+ (struct cdrom_multisession)
CDROM_GET_MCN Obtain the "Universal Product Code"
- if available (struct cdrom_mcn)
+ if available (struct cdrom_mcn)
CDROM_GET_UPC Deprecated, use CDROM_GET_MCN instead.
CDROMRESET hard-reset the drive
CDROMVOLREAD Get the drive's volume setting
- (struct cdrom_volctrl)
+ (struct cdrom_volctrl)
CDROMREADRAW read data in raw mode (2352 Bytes)
- (struct cdrom_read)
+ (struct cdrom_read)
CDROMREADCOOKED read data in cooked mode
CDROMSEEK seek msf address
CDROMPLAYBLK scsi-cd only, (struct cdrom_blk)
@@ -65,16 +67,13 @@ are as follows:
CDROM_SEND_PACKET send a packet to the drive
CDROM_NEXT_WRITABLE get next writable block
CDROM_LAST_WRITTEN get last block written on disc
+ ====================== ===============================================
The information that follows was determined from reading kernel source
code. It is likely that some corrections will be made over time.
-
-
-
-
-
+------------------------------------------------------------------------------
General:
@@ -91,795 +90,1034 @@ General:
Unless otherwise specified, all data structures and constants
are defined in <linux/cdrom.h>
+------------------------------------------------------------------------------
+CDROMPAUSE
+ Pause Audio Operation
-CDROMPAUSE Pause Audio Operation
- usage:
+ usage::
ioctl(fd, CDROMPAUSE, 0);
- inputs: none
- outputs: none
+ inputs:
+ none
+
+
+ outputs:
+ none
+
error return:
- ENOSYS cd drive not audio-capable.
+ - ENOSYS cd drive not audio-capable.
-CDROMRESUME Resume paused Audio Operation
+CDROMRESUME
+ Resume paused Audio Operation
- usage:
+
+ usage::
ioctl(fd, CDROMRESUME, 0);
- inputs: none
- outputs: none
+ inputs:
+ none
+
+
+ outputs:
+ none
+
error return:
- ENOSYS cd drive not audio-capable.
+ - ENOSYS cd drive not audio-capable.
-CDROMPLAYMSF Play Audio MSF (struct cdrom_msf)
+CDROMPLAYMSF
+ Play Audio MSF
- usage:
+ (struct cdrom_msf)
+
+
+ usage::
struct cdrom_msf msf;
+
ioctl(fd, CDROMPLAYMSF, &msf);
inputs:
- cdrom_msf structure, describing a segment of music to play
+ cdrom_msf structure, describing a segment of music to play
+
+
+ outputs:
+ none
- outputs: none
error return:
- ENOSYS cd drive not audio-capable.
+ - ENOSYS cd drive not audio-capable.
notes:
- MSF stands for minutes-seconds-frames
- LBA stands for logical block address
+ - MSF stands for minutes-seconds-frames
+ - LBA stands for logical block address
+ - Segment is described as start and end times, where each time
+ is described as minutes:seconds:frames.
+ A frame is 1/75 of a second.
- Segment is described as start and end times, where each time
- is described as minutes:seconds:frames. A frame is 1/75 of
- a second.
+CDROMPLAYTRKIND
+ Play Audio Track/index
-CDROMPLAYTRKIND Play Audio Track/index (struct cdrom_ti)
+ (struct cdrom_ti)
- usage:
+
+ usage::
struct cdrom_ti ti;
+
ioctl(fd, CDROMPLAYTRKIND, &ti);
inputs:
- cdrom_ti structure, describing a segment of music to play
+ cdrom_ti structure, describing a segment of music to play
+
+
+ outputs:
+ none
- outputs: none
error return:
- ENOSYS cd drive not audio-capable.
+ - ENOSYS cd drive not audio-capable.
notes:
- Segment is described as start and end times, where each time
- is described as a track and an index.
+ - Segment is described as start and end times, where each time
+ is described as a track and an index.
-CDROMREADTOCHDR Read TOC header (struct cdrom_tochdr)
+CDROMREADTOCHDR
+ Read TOC header
- usage:
+ (struct cdrom_tochdr)
+
+
+ usage::
cdrom_tochdr header;
+
ioctl(fd, CDROMREADTOCHDR, &header);
inputs:
- cdrom_tochdr structure
+ cdrom_tochdr structure
+
outputs:
- cdrom_tochdr structure
+ cdrom_tochdr structure
+
error return:
- ENOSYS cd drive not audio-capable.
+ - ENOSYS cd drive not audio-capable.
-CDROMREADTOCENTRY Read TOC entry (struct cdrom_tocentry)
+CDROMREADTOCENTRY
+ Read TOC entry
- usage:
+ (struct cdrom_tocentry)
+
+
+ usage::
struct cdrom_tocentry entry;
+
ioctl(fd, CDROMREADTOCENTRY, &entry);
inputs:
- cdrom_tocentry structure
+ cdrom_tocentry structure
+
outputs:
- cdrom_tocentry structure
+ cdrom_tocentry structure
+
error return:
- ENOSYS cd drive not audio-capable.
- EINVAL entry.cdte_format not CDROM_MSF or CDROM_LBA
- EINVAL requested track out of bounds
- EIO I/O error reading TOC
+ - ENOSYS cd drive not audio-capable.
+ - EINVAL entry.cdte_format not CDROM_MSF or CDROM_LBA
+ - EINVAL requested track out of bounds
+ - EIO I/O error reading TOC
notes:
- TOC stands for Table Of Contents
- MSF stands for minutes-seconds-frames
- LBA stands for logical block address
+ - TOC stands for Table Of Contents
+ - MSF stands for minutes-seconds-frames
+ - LBA stands for logical block address
-CDROMSTOP Stop the cdrom drive
+CDROMSTOP
+ Stop the cdrom drive
- usage:
+
+ usage::
ioctl(fd, CDROMSTOP, 0);
- inputs: none
- outputs: none
+ inputs:
+ none
+
+
+ outputs:
+ none
+
error return:
- ENOSYS cd drive not audio-capable.
+ - ENOSYS cd drive not audio-capable.
notes:
- Exact interpretation of this ioctl depends on the device,
- but most seem to spin the drive down.
+ - Exact interpretation of this ioctl depends on the device,
+ but most seem to spin the drive down.
-CDROMSTART Start the cdrom drive
+CDROMSTART
+ Start the cdrom drive
- usage:
+
+ usage::
ioctl(fd, CDROMSTART, 0);
- inputs: none
- outputs: none
+ inputs:
+ none
+
+
+ outputs:
+ none
+
error return:
- ENOSYS cd drive not audio-capable.
+ - ENOSYS cd drive not audio-capable.
notes:
- Exact interpretation of this ioctl depends on the device,
- but most seem to spin the drive up and/or close the tray.
- Other devices ignore the ioctl completely.
+ - Exact interpretation of this ioctl depends on the device,
+ but most seem to spin the drive up and/or close the tray.
+ Other devices ignore the ioctl completely.
-CDROMEJECT Ejects the cdrom media
+CDROMEJECT
+ - Ejects the cdrom media
- usage:
+
+ usage::
ioctl(fd, CDROMEJECT, 0);
- inputs: none
- outputs: none
+ inputs:
+ none
+
+
+ outputs:
+ none
+
error returns:
- ENOSYS cd drive not capable of ejecting
- EBUSY other processes are accessing drive, or door is locked
+ - ENOSYS cd drive not capable of ejecting
+ - EBUSY other processes are accessing drive, or door is locked
notes:
- See CDROM_LOCKDOOR, below.
+ - See CDROM_LOCKDOOR, below.
-CDROMCLOSETRAY pendant of CDROMEJECT
- usage:
+CDROMCLOSETRAY
+ pendant of CDROMEJECT
+
+
+ usage::
ioctl(fd, CDROMCLOSETRAY, 0);
- inputs: none
- outputs: none
+ inputs:
+ none
+
+
+ outputs:
+ none
+
error returns:
- ENOSYS cd drive not capable of closing the tray
- EBUSY other processes are accessing drive, or door is locked
+ - ENOSYS cd drive not capable of closing the tray
+ - EBUSY other processes are accessing drive, or door is locked
notes:
- See CDROM_LOCKDOOR, below.
+ - See CDROM_LOCKDOOR, below.
-CDROMVOLCTRL Control output volume (struct cdrom_volctrl)
- usage:
+CDROMVOLCTRL
+ Control output volume (struct cdrom_volctrl)
+
+
+ usage::
struct cdrom_volctrl volume;
+
ioctl(fd, CDROMVOLCTRL, &volume);
inputs:
- cdrom_volctrl structure containing volumes for up to 4
- channels.
+ cdrom_volctrl structure containing volumes for up to 4
+ channels.
+
+ outputs:
+ none
- outputs: none
error return:
- ENOSYS cd drive not audio-capable.
+ - ENOSYS cd drive not audio-capable.
-CDROMVOLREAD Get the drive's volume setting
- (struct cdrom_volctrl)
+CDROMVOLREAD
+ Get the drive's volume setting
- usage:
+ (struct cdrom_volctrl)
+
+
+ usage::
struct cdrom_volctrl volume;
+
ioctl(fd, CDROMVOLREAD, &volume);
- inputs: none
+ inputs:
+ none
+
outputs:
- The current volume settings.
+ The current volume settings.
+
error return:
- ENOSYS cd drive not audio-capable.
+ - ENOSYS cd drive not audio-capable.
-CDROMSUBCHNL Read subchannel data (struct cdrom_subchnl)
+CDROMSUBCHNL
+ Read subchannel data
- usage:
+ (struct cdrom_subchnl)
+
+
+ usage::
struct cdrom_subchnl q;
+
ioctl(fd, CDROMSUBCHNL, &q);
inputs:
- cdrom_subchnl structure
+ cdrom_subchnl structure
+
outputs:
- cdrom_subchnl structure
+ cdrom_subchnl structure
+
error return:
- ENOSYS cd drive not audio-capable.
- EINVAL format not CDROM_MSF or CDROM_LBA
+ - ENOSYS cd drive not audio-capable.
+ - EINVAL format not CDROM_MSF or CDROM_LBA
notes:
- Format is converted to CDROM_MSF or CDROM_LBA
- as per user request on return
+ - Format is converted to CDROM_MSF or CDROM_LBA
+ as per user request on return
-CDROMREADRAW read data in raw mode (2352 Bytes)
- (struct cdrom_read)
+CDROMREADRAW
+ read data in raw mode (2352 Bytes)
- usage:
+ (struct cdrom_read)
+
+ usage::
union {
+
struct cdrom_msf msf; /* input */
char buffer[CD_FRAMESIZE_RAW]; /* return */
} arg;
ioctl(fd, CDROMREADRAW, &arg);
inputs:
- cdrom_msf structure indicating an address to read.
- Only the start values are significant.
+ cdrom_msf structure indicating an address to read.
+
+ Only the start values are significant.
outputs:
- Data written to address provided by user.
+ Data written to address provided by user.
+
error return:
- EINVAL address less than 0, or msf less than 0:2:0
- ENOMEM out of memory
+ - EINVAL address less than 0, or msf less than 0:2:0
+ - ENOMEM out of memory
notes:
- As of 2.6.8.1, comments in <linux/cdrom.h> indicate that this
- ioctl accepts a cdrom_read structure, but actual source code
- reads a cdrom_msf structure and writes a buffer of data to
- the same address.
+ - As of 2.6.8.1, comments in <linux/cdrom.h> indicate that this
+ ioctl accepts a cdrom_read structure, but actual source code
+ reads a cdrom_msf structure and writes a buffer of data to
+ the same address.
- MSF values are converted to LBA values via this formula:
+ - MSF values are converted to LBA values via this formula::
- lba = (((m * CD_SECS) + s) * CD_FRAMES + f) - CD_MSF_OFFSET;
+ lba = (((m * CD_SECS) + s) * CD_FRAMES + f) - CD_MSF_OFFSET;
-CDROMREADMODE1 Read CDROM mode 1 data (2048 Bytes)
- (struct cdrom_read)
+CDROMREADMODE1
+ Read CDROM mode 1 data (2048 Bytes)
+
+ (struct cdrom_read)
notes:
- Identical to CDROMREADRAW except that block size is
- CD_FRAMESIZE (2048) bytes
+ Identical to CDROMREADRAW except that block size is
+ CD_FRAMESIZE (2048) bytes
+
+CDROMREADMODE2
+ Read CDROM mode 2 data (2336 Bytes)
-CDROMREADMODE2 Read CDROM mode 2 data (2336 Bytes)
- (struct cdrom_read)
+ (struct cdrom_read)
notes:
- Identical to CDROMREADRAW except that block size is
- CD_FRAMESIZE_RAW0 (2336) bytes
+ Identical to CDROMREADRAW except that block size is
+ CD_FRAMESIZE_RAW0 (2336) bytes
-CDROMREADAUDIO (struct cdrom_read_audio)
+CDROMREADAUDIO
+ (struct cdrom_read_audio)
- usage:
+ usage::
struct cdrom_read_audio ra;
+
ioctl(fd, CDROMREADAUDIO, &ra);
inputs:
- cdrom_read_audio structure containing read start
- point and length
+ cdrom_read_audio structure containing read start
+ point and length
outputs:
- audio data, returned to buffer indicated by ra
+ audio data, returned to buffer indicated by ra
+
error return:
- EINVAL format not CDROM_MSF or CDROM_LBA
- EINVAL nframes not in range [1 75]
- ENXIO drive has no queue (probably means invalid fd)
- ENOMEM out of memory
+ - EINVAL format not CDROM_MSF or CDROM_LBA
+ - EINVAL nframes not in range [1 75]
+ - ENXIO drive has no queue (probably means invalid fd)
+ - ENOMEM out of memory
-CDROMEJECT_SW enable(1)/disable(0) auto-ejecting
+CDROMEJECT_SW
+ enable(1)/disable(0) auto-ejecting
- usage:
+
+ usage::
int val;
+
ioctl(fd, CDROMEJECT_SW, val);
inputs:
- Flag specifying auto-eject flag.
+ Flag specifying auto-eject flag.
+
+
+ outputs:
+ none
- outputs: none
error return:
- ENOSYS Drive is not capable of ejecting.
- EBUSY Door is locked
+ - ENOSYS Drive is not capable of ejecting.
+ - EBUSY Door is locked
-CDROMMULTISESSION Obtain the start-of-last-session
- address of multi session disks
- (struct cdrom_multisession)
- usage:
+CDROMMULTISESSION
+ Obtain the start-of-last-session address of multi session disks
+
+ (struct cdrom_multisession)
+
+ usage::
struct cdrom_multisession ms_info;
+
ioctl(fd, CDROMMULTISESSION, &ms_info);
inputs:
- cdrom_multisession structure containing desired
+ cdrom_multisession structure containing desired
+
format.
outputs:
- cdrom_multisession structure is filled with last_session
- information.
+ cdrom_multisession structure is filled with last_session
+ information.
error return:
- EINVAL format not CDROM_MSF or CDROM_LBA
+ - EINVAL format not CDROM_MSF or CDROM_LBA
-CDROM_GET_MCN Obtain the "Universal Product Code"
- if available (struct cdrom_mcn)
+CDROM_GET_MCN
+ Obtain the "Universal Product Code"
+ if available
- usage:
+ (struct cdrom_mcn)
+
+
+ usage::
struct cdrom_mcn mcn;
+
ioctl(fd, CDROM_GET_MCN, &mcn);
- inputs: none
+ inputs:
+ none
+
outputs:
- Universal Product Code
+ Universal Product Code
+
error return:
- ENOSYS Drive is not capable of reading MCN data.
+ - ENOSYS Drive is not capable of reading MCN data.
notes:
- Source code comments state:
+ - Source code comments state::
- The following function is implemented, although very few
- audio discs give Universal Product Code information, which
- should just be the Medium Catalog Number on the box. Note,
- that the way the code is written on the CD is /not/ uniform
- across all discs!
+ The following function is implemented, although very few
+ audio discs give Universal Product Code information, which
+ should just be the Medium Catalog Number on the box. Note,
+ that the way the code is written on the CD is /not/ uniform
+ across all discs!
-CDROM_GET_UPC CDROM_GET_MCN (deprecated)
+CDROM_GET_UPC
+ CDROM_GET_MCN (deprecated)
+
Not implemented, as of 2.6.8.1
-CDROMRESET hard-reset the drive
+CDROMRESET
+ hard-reset the drive
- usage:
+
+ usage::
ioctl(fd, CDROMRESET, 0);
- inputs: none
- outputs: none
+ inputs:
+ none
+
+
+ outputs:
+ none
+
error return:
- EACCES Access denied: requires CAP_SYS_ADMIN
- ENOSYS Drive is not capable of resetting.
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+ - ENOSYS Drive is not capable of resetting.
-CDROMREADCOOKED read data in cooked mode
+CDROMREADCOOKED
+ read data in cooked mode
- usage:
+
+ usage::
u8 buffer[CD_FRAMESIZE]
+
ioctl(fd, CDROMREADCOOKED, buffer);
- inputs: none
+ inputs:
+ none
+
outputs:
- 2048 bytes of data, "cooked" mode.
+ 2048 bytes of data, "cooked" mode.
+
notes:
- Not implemented on all drives.
+ Not implemented on all drives.
-CDROMREADALL read all 2646 bytes
+
+CDROMREADALL
+ read all 2646 bytes
+
Same as CDROMREADCOOKED, but reads 2646 bytes.
-CDROMSEEK seek msf address
+CDROMSEEK
+ seek msf address
- usage:
+
+ usage::
struct cdrom_msf msf;
+
ioctl(fd, CDROMSEEK, &msf);
inputs:
- MSF address to seek to.
+ MSF address to seek to.
- outputs: none
+ outputs:
+ none
-CDROMPLAYBLK scsi-cd only, (struct cdrom_blk)
- usage:
+
+CDROMPLAYBLK
+ scsi-cd only
+
+ (struct cdrom_blk)
+
+
+ usage::
struct cdrom_blk blk;
+
ioctl(fd, CDROMPLAYBLK, &blk);
inputs:
- Region to play
+ Region to play
+
+
+ outputs:
+ none
- outputs: none
CDROMGETSPINDOWN
-
- usage:
+ usage::
char spindown;
+
ioctl(fd, CDROMGETSPINDOWN, &spindown);
- inputs: none
+ inputs:
+ none
+
outputs:
- The value of the current 4-bit spindown value.
+ The value of the current 4-bit spindown value.
+
CDROMSETSPINDOWN
-
- usage:
+ usage::
char spindown
+
ioctl(fd, CDROMSETSPINDOWN, &spindown);
inputs:
- 4-bit value used to control spindown (TODO: more detail here)
+ 4-bit value used to control spindown (TODO: more detail here)
- outputs: none
+ outputs:
+ none
-CDROM_SET_OPTIONS Set behavior options
- usage:
+
+CDROM_SET_OPTIONS
+ Set behavior options
+
+
+ usage::
int options;
+
ioctl(fd, CDROM_SET_OPTIONS, options);
inputs:
- New values for drive options. The logical 'or' of:
+ New values for drive options. The logical 'or' of:
+
+ ============== ==================================
CDO_AUTO_CLOSE close tray on first open(2)
CDO_AUTO_EJECT open tray on last release
CDO_USE_FFLAGS use O_NONBLOCK information on open
CDO_LOCK lock tray on open files
CDO_CHECK_TYPE check type on open for data
+ ============== ==================================
outputs:
- Returns the resulting options settings in the
- ioctl return value. Returns -1 on error.
+ Returns the resulting options settings in the
+ ioctl return value. Returns -1 on error.
error return:
- ENOSYS selected option(s) not supported by drive.
+ - ENOSYS selected option(s) not supported by drive.
-CDROM_CLEAR_OPTIONS Clear behavior options
+CDROM_CLEAR_OPTIONS
+ Clear behavior options
+
Same as CDROM_SET_OPTIONS, except that selected options are
turned off.
-CDROM_SELECT_SPEED Set the CD-ROM speed
+CDROM_SELECT_SPEED
+ Set the CD-ROM speed
- usage:
+
+ usage::
int speed;
+
ioctl(fd, CDROM_SELECT_SPEED, speed);
inputs:
- New drive speed.
+ New drive speed.
+
+
+ outputs:
+ none
- outputs: none
error return:
- ENOSYS speed selection not supported by drive.
+ - ENOSYS speed selection not supported by drive.
-CDROM_SELECT_DISC Select disc (for juke-boxes)
+CDROM_SELECT_DISC
+ Select disc (for juke-boxes)
- usage:
+
+ usage::
int disk;
+
ioctl(fd, CDROM_SELECT_DISC, disk);
inputs:
- Disk to load into drive.
+ Disk to load into drive.
+
+
+ outputs:
+ none
- outputs: none
error return:
- EINVAL Disk number beyond capacity of drive
+ - EINVAL Disk number beyond capacity of drive
-CDROM_MEDIA_CHANGED Check is media changed
+CDROM_MEDIA_CHANGED
+ Check is media changed
- usage:
+
+ usage::
int slot;
+
ioctl(fd, CDROM_MEDIA_CHANGED, slot);
inputs:
- Slot number to be tested, always zero except for jukeboxes.
- May also be special values CDSL_NONE or CDSL_CURRENT
+ Slot number to be tested, always zero except for jukeboxes.
+
+ May also be special values CDSL_NONE or CDSL_CURRENT
outputs:
- Ioctl return value is 0 or 1 depending on whether the media
+ Ioctl return value is 0 or 1 depending on whether the media
+
has been changed, or -1 on error.
error returns:
- ENOSYS Drive can't detect media change
- EINVAL Slot number beyond capacity of drive
- ENOMEM Out of memory
+ - ENOSYS Drive can't detect media change
+ - EINVAL Slot number beyond capacity of drive
+ - ENOMEM Out of memory
-CDROM_DRIVE_STATUS Get tray position, etc.
+CDROM_DRIVE_STATUS
+ Get tray position, etc.
- usage:
+
+ usage::
int slot;
+
ioctl(fd, CDROM_DRIVE_STATUS, slot);
inputs:
- Slot number to be tested, always zero except for jukeboxes.
- May also be special values CDSL_NONE or CDSL_CURRENT
+ Slot number to be tested, always zero except for jukeboxes.
+
+ May also be special values CDSL_NONE or CDSL_CURRENT
outputs:
- Ioctl return value will be one of the following values
+ Ioctl return value will be one of the following values
+
from <linux/cdrom.h>:
+ =================== ==========================
CDS_NO_INFO Information not available.
CDS_NO_DISC
CDS_TRAY_OPEN
CDS_DRIVE_NOT_READY
CDS_DISC_OK
-1 error
+ =================== ==========================
error returns:
- ENOSYS Drive can't detect drive status
- EINVAL Slot number beyond capacity of drive
- ENOMEM Out of memory
+ - ENOSYS Drive can't detect drive status
+ - EINVAL Slot number beyond capacity of drive
+ - ENOMEM Out of memory
-CDROM_DISC_STATUS Get disc type, etc.
+CDROM_DISC_STATUS
+ Get disc type, etc.
- usage:
+
+ usage::
ioctl(fd, CDROM_DISC_STATUS, 0);
- inputs: none
+
+ inputs:
+ none
+
outputs:
- Ioctl return value will be one of the following values
+ Ioctl return value will be one of the following values
+
from <linux/cdrom.h>:
- CDS_NO_INFO
- CDS_AUDIO
- CDS_MIXED
- CDS_XA_2_2
- CDS_XA_2_1
- CDS_DATA_1
- error returns: none at present
+ - CDS_NO_INFO
+ - CDS_AUDIO
+ - CDS_MIXED
+ - CDS_XA_2_2
+ - CDS_XA_2_1
+ - CDS_DATA_1
+
+ error returns:
+ none at present
notes:
- Source code comments state:
+ - Source code comments state::
- Ok, this is where problems start. The current interface for
- the CDROM_DISC_STATUS ioctl is flawed. It makes the false
- assumption that CDs are all CDS_DATA_1 or all CDS_AUDIO, etc.
- Unfortunately, while this is often the case, it is also
- very common for CDs to have some tracks with data, and some
- tracks with audio. Just because I feel like it, I declare
- the following to be the best way to cope. If the CD has
- ANY data tracks on it, it will be returned as a data CD.
- If it has any XA tracks, I will return it as that. Now I
- could simplify this interface by combining these returns with
- the above, but this more clearly demonstrates the problem
- with the current interface. Too bad this wasn't designed
- to use bitmasks... -Erik
- Well, now we have the option CDS_MIXED: a mixed-type CD.
- User level programmers might feel the ioctl is not very
- useful.
- ---david
+ Ok, this is where problems start. The current interface for
+ the CDROM_DISC_STATUS ioctl is flawed. It makes the false
+ assumption that CDs are all CDS_DATA_1 or all CDS_AUDIO, etc.
+ Unfortunately, while this is often the case, it is also
+ very common for CDs to have some tracks with data, and some
+ tracks with audio. Just because I feel like it, I declare
+ the following to be the best way to cope. If the CD has
+ ANY data tracks on it, it will be returned as a data CD.
+ If it has any XA tracks, I will return it as that. Now I
+ could simplify this interface by combining these returns with
+ the above, but this more clearly demonstrates the problem
+ with the current interface. Too bad this wasn't designed
+ to use bitmasks... -Erik
+ Well, now we have the option CDS_MIXED: a mixed-type CD.
+ User level programmers might feel the ioctl is not very
+ useful.
+ ---david
-CDROM_CHANGER_NSLOTS Get number of slots
- usage:
+CDROM_CHANGER_NSLOTS
+ Get number of slots
+
+
+ usage::
ioctl(fd, CDROM_CHANGER_NSLOTS, 0);
- inputs: none
+
+ inputs:
+ none
+
outputs:
- The ioctl return value will be the number of slots in a
- CD changer. Typically 1 for non-multi-disk devices.
+ The ioctl return value will be the number of slots in a
+ CD changer. Typically 1 for non-multi-disk devices.
- error returns: none
+ error returns:
+ none
-CDROM_LOCKDOOR lock or unlock door
+CDROM_LOCKDOOR
+ lock or unlock door
- usage:
+
+ usage::
int lock;
+
ioctl(fd, CDROM_LOCKDOOR, lock);
inputs:
- Door lock flag, 1=lock, 0=unlock
+ Door lock flag, 1=lock, 0=unlock
+
+
+ outputs:
+ none
- outputs: none
error returns:
- EDRIVE_CANT_DO_THIS Door lock function not supported.
- EBUSY Attempt to unlock when multiple users
- have the drive open and not CAP_SYS_ADMIN
+ - EDRIVE_CANT_DO_THIS
+
+ Door lock function not supported.
+ - EBUSY
+
+ Attempt to unlock when multiple users
+ have the drive open and not CAP_SYS_ADMIN
notes:
- As of 2.6.8.1, the lock flag is a global lock, meaning that
- all CD drives will be locked or unlocked together. This is
- probably a bug.
+ As of 2.6.8.1, the lock flag is a global lock, meaning that
+ all CD drives will be locked or unlocked together. This is
+ probably a bug.
- The EDRIVE_CANT_DO_THIS value is defined in <linux/cdrom.h>
- and is currently (2.6.8.1) the same as EOPNOTSUPP
+ The EDRIVE_CANT_DO_THIS value is defined in <linux/cdrom.h>
+ and is currently (2.6.8.1) the same as EOPNOTSUPP
-CDROM_DEBUG Turn debug messages on/off
+CDROM_DEBUG
+ Turn debug messages on/off
- usage:
+
+ usage::
int debug;
+
ioctl(fd, CDROM_DEBUG, debug);
inputs:
- Cdrom debug flag, 0=disable, 1=enable
+ Cdrom debug flag, 0=disable, 1=enable
+
outputs:
- The ioctl return value will be the new debug flag.
+ The ioctl return value will be the new debug flag.
+
error return:
- EACCES Access denied: requires CAP_SYS_ADMIN
+ - EACCES Access denied: requires CAP_SYS_ADMIN
-CDROM_GET_CAPABILITY get capabilities
+CDROM_GET_CAPABILITY
+ get capabilities
- usage:
+
+ usage::
ioctl(fd, CDROM_GET_CAPABILITY, 0);
- inputs: none
+
+ inputs:
+ none
+
outputs:
- The ioctl return value is the current device capability
- flags. See CDC_CLOSE_TRAY, CDC_OPEN_TRAY, etc.
+ The ioctl return value is the current device capability
+ flags. See CDC_CLOSE_TRAY, CDC_OPEN_TRAY, etc.
-CDROMAUDIOBUFSIZ set the audio buffer size
+CDROMAUDIOBUFSIZ
+ set the audio buffer size
- usage:
+
+ usage::
int arg;
+
ioctl(fd, CDROMAUDIOBUFSIZ, val);
inputs:
- New audio buffer size
+ New audio buffer size
+
outputs:
- The ioctl return value is the new audio buffer size, or -1
- on error.
+ The ioctl return value is the new audio buffer size, or -1
+ on error.
error return:
- ENOSYS Not supported by this driver.
+ - ENOSYS Not supported by this driver.
notes:
- Not supported by all drivers.
+ Not supported by all drivers.
+
DVD_READ_STRUCT Read structure
- usage:
+ usage::
dvd_struct s;
+
ioctl(fd, DVD_READ_STRUCT, &s);
inputs:
- dvd_struct structure, containing:
+ dvd_struct structure, containing:
+
+ =================== ==========================================
type specifies the information desired, one of
- DVD_STRUCT_PHYSICAL, DVD_STRUCT_COPYRIGHT,
+ DVD_STRUCT_PHYSICAL, DVD_STRUCT_COPYRIGHT,
DVD_STRUCT_DISCKEY, DVD_STRUCT_BCA,
DVD_STRUCT_MANUFACT
physical.layer_num desired layer, indexed from 0
copyright.layer_num desired layer, indexed from 0
disckey.agid
+ =================== ==========================================
outputs:
- dvd_struct structure, containing:
+ dvd_struct structure, containing:
+
+ =================== ================================
physical for type == DVD_STRUCT_PHYSICAL
copyright for type == DVD_STRUCT_COPYRIGHT
disckey.value for type == DVD_STRUCT_DISCKEY
bca.{len,value} for type == DVD_STRUCT_BCA
manufact.{len,valu} for type == DVD_STRUCT_MANUFACT
+ =================== ================================
error returns:
- EINVAL physical.layer_num exceeds number of layers
- EIO Received invalid response from drive
+ - EINVAL physical.layer_num exceeds number of layers
+ - EIO Received invalid response from drive
@@ -891,77 +1129,105 @@ DVD_WRITE_STRUCT Write structure
DVD_AUTH Authentication
- usage:
+ usage::
dvd_authinfo ai;
+
ioctl(fd, DVD_AUTH, &ai);
inputs:
- dvd_authinfo structure. See <linux/cdrom.h>
+ dvd_authinfo structure. See <linux/cdrom.h>
+
outputs:
- dvd_authinfo structure.
+ dvd_authinfo structure.
+
error return:
- ENOTTY ai.type not recognized.
+ - ENOTTY ai.type not recognized.
-CDROM_SEND_PACKET send a packet to the drive
+CDROM_SEND_PACKET
+ send a packet to the drive
- usage:
+
+ usage::
struct cdrom_generic_command cgc;
+
ioctl(fd, CDROM_SEND_PACKET, &cgc);
inputs:
- cdrom_generic_command structure containing the packet to send.
+ cdrom_generic_command structure containing the packet to send.
+
+
+ outputs:
+ none
- outputs: none
cdrom_generic_command structure containing results.
error return:
- EIO command failed.
- EPERM Operation not permitted, either because a
+ - EIO
+
+ command failed.
+ - EPERM
+
+ Operation not permitted, either because a
write command was attempted on a drive which
is opened read-only, or because the command
requires CAP_SYS_RAWIO
- EINVAL cgc.data_direction not set
+ - EINVAL
+ cgc.data_direction not set
-CDROM_NEXT_WRITABLE get next writable block
- usage:
+CDROM_NEXT_WRITABLE
+ get next writable block
+
+
+ usage::
long next;
+
ioctl(fd, CDROM_NEXT_WRITABLE, &next);
- inputs: none
+ inputs:
+ none
+
outputs:
- The next writable block.
+ The next writable block.
+
notes:
- If the device does not support this ioctl directly, the
+ If the device does not support this ioctl directly, the
+
ioctl will return CDROM_LAST_WRITTEN + 7.
-CDROM_LAST_WRITTEN get last block written on disc
+CDROM_LAST_WRITTEN
+ get last block written on disc
- usage:
+
+ usage::
long last;
+
ioctl(fd, CDROM_LAST_WRITTEN, &last);
- inputs: none
+ inputs:
+ none
+
outputs:
- The last block written on disc
+ The last block written on disc
+
notes:
- If the device does not support this ioctl directly, the
- result is derived from the disc's table of contents. If the
- table of contents can't be read, this ioctl returns an
- error.
+ If the device does not support this ioctl directly, the
+ result is derived from the disc's table of contents. If the
+ table of contents can't be read, this ioctl returns an
+ error.
diff --git a/Documentation/ioctl/hdio.txt b/Documentation/ioctl/hdio.rst
similarity index 54%
rename from Documentation/ioctl/hdio.txt
rename to Documentation/ioctl/hdio.rst
index 18eb98c44ffe..e822e3dff176 100644
--- a/Documentation/ioctl/hdio.txt
+++ b/Documentation/ioctl/hdio.rst
@@ -1,9 +1,10 @@
- Summary of HDIO_ ioctl calls.
- ============================
+==============================
+Summary of `HDIO_` ioctl calls
+==============================
- Edward A. Falk <efalk@google.com>
+- Edward A. Falk <efalk@google.com>
- November, 2004
+November, 2004
This document attempts to describe the ioctl(2) calls supported by
the HD/IDE layer. These are by-and-large implemented (as of Linux 2.6)
@@ -14,6 +15,7 @@ are as follows:
ioctls that pass argument pointers to user space:
+ ======================= =======================================
HDIO_GETGEO get device geometry
HDIO_GET_UNMASKINTR get current unmask setting
HDIO_GET_MULTCOUNT get current IDE blockmode setting
@@ -36,9 +38,11 @@ are as follows:
HDIO_DRIVE_TASK execute task and special drive command
HDIO_DRIVE_CMD execute a special drive command
HDIO_DRIVE_CMD_AEB HDIO_DRIVE_TASK
+ ======================= =======================================
ioctls that pass non-pointer values:
+ ======================= =======================================
HDIO_SET_MULTCOUNT change IDE blockmode
HDIO_SET_UNMASKINTR permit other irqs during I/O
HDIO_SET_KEEPSETTINGS keep ioctl settings on reset
@@ -57,16 +61,13 @@ are as follows:
HDIO_SET_IDE_SCSI Set scsi emulation mode on/off
HDIO_SET_SCSI_IDE not implemented yet
+ ======================= =======================================
The information that follows was determined from reading kernel source
code. It is likely that some corrections will be made over time.
-
-
-
-
-
+------------------------------------------------------------------------------
General:
@@ -80,459 +81,610 @@ General:
Unless otherwise specified, all data structures and constants
are defined in <linux/hdreg.h>
+------------------------------------------------------------------------------
+HDIO_GETGEO
+ get device geometry
-HDIO_GETGEO get device geometry
- usage:
+ usage::
struct hd_geometry geom;
+
ioctl(fd, HDIO_GETGEO, &geom);
- inputs: none
+ inputs:
+ none
+
+
outputs:
+ hd_geometry structure containing:
- hd_geometry structure containing:
+ ========= ==================================
heads number of heads
sectors number of sectors/track
cylinders number of cylinders, mod 65536
start starting sector of this partition.
+ ========= ==================================
error returns:
- EINVAL if the device is not a disk drive or floppy drive,
- or if the user passes a null pointer
+ - EINVAL
+
+ if the device is not a disk drive or floppy drive,
+ or if the user passes a null pointer
notes:
+ Not particularly useful with modern disk drives, whose geometry
+ is a polite fiction anyway. Modern drives are addressed
+ purely by sector number nowadays (lba addressing), and the
+ drive geometry is an abstraction which is actually subject
+ to change. Currently (as of Nov 2004), the geometry values
+ are the "bios" values -- presumably the values the drive had
+ when Linux first booted.
- Not particularly useful with modern disk drives, whose geometry
- is a polite fiction anyway. Modern drives are addressed
- purely by sector number nowadays (lba addressing), and the
- drive geometry is an abstraction which is actually subject
- to change. Currently (as of Nov 2004), the geometry values
- are the "bios" values -- presumably the values the drive had
- when Linux first booted.
+ In addition, the cylinders field of the hd_geometry is an
+ unsigned short, meaning that on most architectures, this
+ ioctl will not return a meaningful value on drives with more
+ than 65535 tracks.
- In addition, the cylinders field of the hd_geometry is an
- unsigned short, meaning that on most architectures, this
- ioctl will not return a meaningful value on drives with more
- than 65535 tracks.
+ The start field is unsigned long, meaning that it will not
+ contain a meaningful value for disks over 219 Gb in size.
- The start field is unsigned long, meaning that it will not
- contain a meaningful value for disks over 219 Gb in size.
+HDIO_GET_UNMASKINTR
+ get current unmask setting
-HDIO_GET_UNMASKINTR get current unmask setting
- usage:
+ usage::
long val;
+
ioctl(fd, HDIO_GET_UNMASKINTR, &val);
- inputs: none
+ inputs:
+ none
+
+
outputs:
- The value of the drive's current unmask setting
+ The value of the drive's current unmask setting
-HDIO_SET_UNMASKINTR permit other irqs during I/O
- usage:
+
+HDIO_SET_UNMASKINTR
+ permit other irqs during I/O
+
+
+ usage::
unsigned long val;
+
ioctl(fd, HDIO_SET_UNMASKINTR, val);
inputs:
- New value for unmask flag
+ New value for unmask flag
+
+
+
+ outputs:
+ none
+
- outputs: none
error return:
- EINVAL (bdev != bdev->bd_contains) (not sure what this means)
- EACCES Access denied: requires CAP_SYS_ADMIN
- EINVAL value out of range [0 1]
- EBUSY Controller busy
+ - EINVAL (bdev != bdev->bd_contains) (not sure what this means)
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+ - EINVAL value out of range [0 1]
+ - EBUSY Controller busy
-HDIO_GET_MULTCOUNT get current IDE blockmode setting
+HDIO_GET_MULTCOUNT
+ get current IDE blockmode setting
- usage:
+
+ usage::
long val;
+
ioctl(fd, HDIO_GET_MULTCOUNT, &val);
- inputs: none
+ inputs:
+ none
+
+
outputs:
- The value of the current IDE block mode setting. This
- controls how many sectors the drive will transfer per
- interrupt.
+ The value of the current IDE block mode setting. This
+ controls how many sectors the drive will transfer per
+ interrupt.
-HDIO_SET_MULTCOUNT change IDE blockmode
+HDIO_SET_MULTCOUNT
+ change IDE blockmode
- usage:
+
+ usage::
int val;
+
ioctl(fd, HDIO_SET_MULTCOUNT, val);
inputs:
- New value for IDE block mode setting. This controls how many
- sectors the drive will transfer per interrupt.
+ New value for IDE block mode setting. This controls how many
+ sectors the drive will transfer per interrupt.
+
+ outputs:
+ none
+
- outputs: none
error return:
- EINVAL (bdev != bdev->bd_contains) (not sure what this means)
- EACCES Access denied: requires CAP_SYS_ADMIN
- EINVAL value out of range supported by disk.
- EBUSY Controller busy or blockmode already set.
- EIO Drive did not accept new block mode.
+ - EINVAL (bdev != bdev->bd_contains) (not sure what this means)
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+ - EINVAL value out of range supported by disk.
+ - EBUSY Controller busy or blockmode already set.
+ - EIO Drive did not accept new block mode.
notes:
-
- Source code comments read:
+ Source code comments read::
This is tightly woven into the driver->do_special cannot
touch. DON'T do it again until a total personality rewrite
is committed.
If blockmode has already been set, this ioctl will fail with
- EBUSY
+ -EBUSY
-HDIO_GET_QDMA get use-qdma flag
+HDIO_GET_QDMA
+ get use-qdma flag
+
Not implemented, as of 2.6.8.1
-HDIO_SET_XFER set transfer rate via proc
+HDIO_SET_XFER
+ set transfer rate via proc
+
Not implemented, as of 2.6.8.1
-HDIO_OBSOLETE_IDENTITY OBSOLETE, DO NOT USE
+HDIO_OBSOLETE_IDENTITY
+ OBSOLETE, DO NOT USE
+
Same as HDIO_GET_IDENTITY (see below), except that it only
returns the first 142 bytes of drive identity information.
-HDIO_GET_IDENTITY get IDE identification info
+HDIO_GET_IDENTITY
+ get IDE identification info
- usage:
+
+ usage::
unsigned char identity[512];
+
ioctl(fd, HDIO_GET_IDENTITY, identity);
- inputs: none
+ inputs:
+ none
+
+
outputs:
-
- ATA drive identity information. For full description, see
- the IDENTIFY DEVICE and IDENTIFY PACKET DEVICE commands in
- the ATA specification.
+ ATA drive identity information. For full description, see
+ the IDENTIFY DEVICE and IDENTIFY PACKET DEVICE commands in
+ the ATA specification.
error returns:
- EINVAL (bdev != bdev->bd_contains) (not sure what this means)
- ENOMSG IDENTIFY DEVICE information not available
+ - EINVAL (bdev != bdev->bd_contains) (not sure what this means)
+ - ENOMSG IDENTIFY DEVICE information not available
notes:
+ Returns information that was obtained when the drive was
+ probed. Some of this information is subject to change, and
+ this ioctl does not re-probe the drive to update the
+ information.
- Returns information that was obtained when the drive was
- probed. Some of this information is subject to change, and
- this ioctl does not re-probe the drive to update the
- information.
+ This information is also available from /proc/ide/hdX/identify
- This information is also available from /proc/ide/hdX/identify
+HDIO_GET_KEEPSETTINGS
+ get keep-settings-on-reset flag
-HDIO_GET_KEEPSETTINGS get keep-settings-on-reset flag
- usage:
+ usage::
long val;
+
ioctl(fd, HDIO_GET_KEEPSETTINGS, &val);
- inputs: none
+ inputs:
+ none
+
+
outputs:
- The value of the current "keep settings" flag
+ The value of the current "keep settings" flag
+
+
notes:
+ When set, indicates that kernel should restore settings
+ after a drive reset.
- When set, indicates that kernel should restore settings
- after a drive reset.
+HDIO_SET_KEEPSETTINGS
+ keep ioctl settings on reset
-HDIO_SET_KEEPSETTINGS keep ioctl settings on reset
- usage:
+ usage::
long val;
+
ioctl(fd, HDIO_SET_KEEPSETTINGS, val);
inputs:
- New value for keep_settings flag
+ New value for keep_settings flag
+
+
+
+ outputs:
+ none
+
- outputs: none
error return:
- EINVAL (bdev != bdev->bd_contains) (not sure what this means)
- EACCES Access denied: requires CAP_SYS_ADMIN
- EINVAL value out of range [0 1]
- EBUSY Controller busy
+ - EINVAL (bdev != bdev->bd_contains) (not sure what this means)
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+ - EINVAL value out of range [0 1]
+ - EBUSY Controller busy
-HDIO_GET_32BIT get current io_32bit setting
+HDIO_GET_32BIT
+ get current io_32bit setting
- usage:
+
+ usage::
long val;
+
ioctl(fd, HDIO_GET_32BIT, &val);
- inputs: none
+ inputs:
+ none
+
+
outputs:
- The value of the current io_32bit setting
+ The value of the current io_32bit setting
+
+
notes:
+ 0=16-bit, 1=32-bit, 2,3 = 32bit+sync
- 0=16-bit, 1=32-bit, 2,3 = 32bit+sync
-HDIO_GET_NOWERR get ignore-write-error flag
- usage:
+HDIO_GET_NOWERR
+ get ignore-write-error flag
+
+
+ usage::
long val;
+
ioctl(fd, HDIO_GET_NOWERR, &val);
- inputs: none
+ inputs:
+ none
+
+
outputs:
- The value of the current ignore-write-error flag
+ The value of the current ignore-write-error flag
-HDIO_GET_DMA get use-dma flag
- usage:
+
+HDIO_GET_DMA
+ get use-dma flag
+
+
+ usage::
long val;
+
ioctl(fd, HDIO_GET_DMA, &val);
- inputs: none
+ inputs:
+ none
+
+
outputs:
- The value of the current use-dma flag
+ The value of the current use-dma flag
-HDIO_GET_NICE get nice flags
- usage:
+
+HDIO_GET_NICE
+ get nice flags
+
+
+ usage::
long nice;
+
ioctl(fd, HDIO_GET_NICE, &nice);
- inputs: none
+ inputs:
+ none
+
+
outputs:
+ The drive's "nice" values.
+
- The drive's "nice" values.
notes:
+ Per-drive flags which determine when the system will give more
+ bandwidth to other devices sharing the same IDE bus.
- Per-drive flags which determine when the system will give more
- bandwidth to other devices sharing the same IDE bus.
- See <linux/hdreg.h>, near symbol IDE_NICE_DSC_OVERLAP.
+ See <linux/hdreg.h>, near symbol IDE_NICE_DSC_OVERLAP.
-HDIO_SET_NICE set nice flags
+HDIO_SET_NICE
+ set nice flags
- usage:
+
+ usage::
unsigned long nice;
+
...
ioctl(fd, HDIO_SET_NICE, nice);
inputs:
- bitmask of nice flags.
+ bitmask of nice flags.
+
+
+
+ outputs:
+ none
+
- outputs: none
error returns:
- EACCES Access denied: requires CAP_SYS_ADMIN
- EPERM Flags other than DSC_OVERLAP and NICE_1 set.
- EPERM DSC_OVERLAP specified but not supported by drive
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+ - EPERM Flags other than DSC_OVERLAP and NICE_1 set.
+ - EPERM DSC_OVERLAP specified but not supported by drive
notes:
+ This ioctl sets the DSC_OVERLAP and NICE_1 flags from values
+ provided by the user.
- This ioctl sets the DSC_OVERLAP and NICE_1 flags from values
- provided by the user.
+ Nice flags are listed in <linux/hdreg.h>, starting with
+ IDE_NICE_DSC_OVERLAP. These values represent shifts.
- Nice flags are listed in <linux/hdreg.h>, starting with
- IDE_NICE_DSC_OVERLAP. These values represent shifts.
+HDIO_GET_WCACHE
+ get write cache mode on|off
-HDIO_GET_WCACHE get write cache mode on|off
- usage:
+ usage::
long val;
+
ioctl(fd, HDIO_GET_WCACHE, &val);
- inputs: none
+ inputs:
+ none
+
+
outputs:
- The value of the current write cache mode
+ The value of the current write cache mode
-HDIO_GET_ACOUSTIC get acoustic value
- usage:
+
+HDIO_GET_ACOUSTIC
+ get acoustic value
+
+
+ usage::
long val;
+
ioctl(fd, HDIO_GET_ACOUSTIC, &val);
- inputs: none
+ inputs:
+ none
+
+
outputs:
- The value of the current acoustic settings
+ The value of the current acoustic settings
+
+
notes:
+ See HDIO_SET_ACOUSTIC
+
- See HDIO_SET_ACOUSTIC
HDIO_GET_ADDRESS
+ usage::
- usage:
long val;
+
ioctl(fd, HDIO_GET_ADDRESS, &val);
- inputs: none
+ inputs:
+ none
+
+
outputs:
- The value of the current addressing mode:
- 0 = 28-bit
- 1 = 48-bit
- 2 = 48-bit doing 28-bit
- 3 = 64-bit
+ The value of the current addressing mode:
+ = ===================
+ 0 28-bit
+ 1 48-bit
+ 2 48-bit doing 28-bit
+ 3 64-bit
+ = ===================
-HDIO_GET_BUSSTATE get the bus state of the hwif
- usage:
+HDIO_GET_BUSSTATE
+ get the bus state of the hwif
+
+
+ usage::
long state;
+
ioctl(fd, HDIO_SCAN_HWIF, &state);
- inputs: none
+ inputs:
+ none
+
+
outputs:
- Current power state of the IDE bus. One of BUSSTATE_OFF,
- BUSSTATE_ON, or BUSSTATE_TRISTATE
+ Current power state of the IDE bus. One of BUSSTATE_OFF,
+ BUSSTATE_ON, or BUSSTATE_TRISTATE
error returns:
- EACCES Access denied: requires CAP_SYS_ADMIN
+ - EACCES Access denied: requires CAP_SYS_ADMIN
-HDIO_SET_BUSSTATE set the bus state of the hwif
+HDIO_SET_BUSSTATE
+ set the bus state of the hwif
- usage:
+
+ usage::
int state;
+
...
ioctl(fd, HDIO_SCAN_HWIF, state);
inputs:
- Desired IDE power state. One of BUSSTATE_OFF, BUSSTATE_ON,
- or BUSSTATE_TRISTATE
+ Desired IDE power state. One of BUSSTATE_OFF, BUSSTATE_ON,
+ or BUSSTATE_TRISTATE
+
+ outputs:
+ none
+
- outputs: none
error returns:
- EACCES Access denied: requires CAP_SYS_RAWIO
- EOPNOTSUPP Hardware interface does not support bus power control
+ - EACCES Access denied: requires CAP_SYS_RAWIO
+ - EOPNOTSUPP Hardware interface does not support bus power control
-HDIO_TRISTATE_HWIF execute a channel tristate
+HDIO_TRISTATE_HWIF
+ execute a channel tristate
+
Not implemented, as of 2.6.8.1. See HDIO_SET_BUSSTATE
-HDIO_DRIVE_RESET execute a device reset
+HDIO_DRIVE_RESET
+ execute a device reset
- usage:
+
+ usage::
int args[3]
+
...
ioctl(fd, HDIO_DRIVE_RESET, args);
- inputs: none
+ inputs:
+ none
+
+
+
+ outputs:
+ none
+
- outputs: none
error returns:
- EACCES Access denied: requires CAP_SYS_ADMIN
- ENXIO No such device: phy dead or ctl_addr == 0
- EIO I/O error: reset timed out or hardware error
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+ - ENXIO No such device: phy dead or ctl_addr == 0
+ - EIO I/O error: reset timed out or hardware error
notes:
- Execute a reset on the device as soon as the current IO
- operation has completed.
+ - Execute a reset on the device as soon as the current IO
+ operation has completed.
- Executes an ATAPI soft reset if applicable, otherwise
- executes an ATA soft reset on the controller.
+ - Executes an ATAPI soft reset if applicable, otherwise
+ executes an ATA soft reset on the controller.
-HDIO_DRIVE_TASKFILE execute raw taskfile
+HDIO_DRIVE_TASKFILE
+ execute raw taskfile
- Note: If you don't have a copy of the ANSI ATA specification
- handy, you should probably ignore this ioctl.
- Execute an ATA disk command directly by writing the "taskfile"
- registers of the drive. Requires ADMIN and RAWIO access
- privileges.
+ Note:
+ If you don't have a copy of the ANSI ATA specification
+ handy, you should probably ignore this ioctl.
- usage:
+ - Execute an ATA disk command directly by writing the "taskfile"
+ registers of the drive. Requires ADMIN and RAWIO access
+ privileges.
+
+ usage::
struct {
+
ide_task_request_t req_task;
u8 outbuf[OUTPUT_SIZE];
u8 inbuf[INPUT_SIZE];
@@ -548,6 +700,7 @@ HDIO_DRIVE_TASKFILE execute raw taskfile
(See below for details on memory area passed to ioctl.)
+ ============ ===================================================
io_ports[8] values to be written to taskfile registers
hob_ports[8] high-order bytes, for extended commands.
out_flags flags indicating which registers are valid
@@ -557,24 +710,29 @@ HDIO_DRIVE_TASKFILE execute raw taskfile
out_size size of output buffer
outbuf buffer of data to be transmitted to disk
inbuf buffer of data to be received from disk (see [1])
+ ============ ===================================================
outputs:
+ =========== ====================================================
io_ports[] values returned in the taskfile registers
hob_ports[] high-order bytes, for extended commands.
out_flags flags indicating which registers are valid (see [2])
in_flags flags indicating which registers should be returned
outbuf buffer of data to be transmitted to disk (see [1])
inbuf buffer of data to be received from disk
+ =========== ====================================================
error returns:
- EACCES CAP_SYS_ADMIN or CAP_SYS_RAWIO privilege not set.
- ENOMSG Device is not a disk drive.
- ENOMEM Unable to allocate memory for task
- EFAULT req_cmd == TASKFILE_IN_OUT (not implemented as of 2.6.8)
- EPERM req_cmd == TASKFILE_MULTI_OUT and drive
- multi-count not yet set.
- EIO Drive failed the command.
+ - EACCES CAP_SYS_ADMIN or CAP_SYS_RAWIO privilege not set.
+ - ENOMSG Device is not a disk drive.
+ - ENOMEM Unable to allocate memory for task
+ - EFAULT req_cmd == TASKFILE_IN_OUT (not implemented as of 2.6.8)
+ - EPERM
+
+ req_cmd == TASKFILE_MULTI_OUT and drive
+ multi-count not yet set.
+ - EIO Drive failed the command.
notes:
@@ -615,22 +773,25 @@ HDIO_DRIVE_TASKFILE execute raw taskfile
Command is passed to the disk drive via the ide_task_request_t
structure, which contains these fields:
+ ============ ===============================================
io_ports[8] values for the taskfile registers
hob_ports[8] high-order bytes, for extended commands
out_flags flags indicating which entries in the
- io_ports[] and hob_ports[] arrays
+ io_ports[] and hob_ports[] arrays
contain valid values. Type ide_reg_valid_t.
in_flags flags indicating which entries in the
- io_ports[] and hob_ports[] arrays
+ io_ports[] and hob_ports[] arrays
are expected to contain valid values
on return.
data_phase See below
req_cmd Command type, see below
out_size output (user->drive) buffer size, bytes
in_size input (drive->user) buffer size, bytes
+ ============ ===============================================
When out_flags is zero, the following registers are loaded.
+ ============ ===============================================
HOB_FEATURE If the drive supports LBA48
HOB_NSECTOR If the drive supports LBA48
HOB_SECTOR If the drive supports LBA48
@@ -644,9 +805,11 @@ HDIO_DRIVE_TASKFILE execute raw taskfile
SELECT First, masked with 0xE0 if LBA48, 0xEF
otherwise; then, or'ed with the default
value of SELECT.
+ ============ ===============================================
If any bit in out_flags is set, the following registers are loaded.
+ ============ ===============================================
HOB_DATA If out_flags.b.data is set. HOB_DATA will
travel on DD8-DD15 on little endian machines
and on DD0-DD7 on big endian machines.
@@ -664,6 +827,7 @@ HDIO_DRIVE_TASKFILE execute raw taskfile
HCYL If out_flags.b.hcyl is set
SELECT Or'ed with the default value of SELECT and
loaded regardless of out_flags.b.select.
+ ============ ===============================================
Taskfile registers are read back from the drive into
{io|hob}_ports[] after the command completes iff one of the
@@ -674,6 +838,7 @@ HDIO_DRIVE_TASKFILE execute raw taskfile
2. One or more than one bits are set in out_flags.
3. The requested data_phase is TASKFILE_NO_DATA.
+ ============ ===============================================
HOB_DATA If in_flags.b.data is set. It will contain
DD8-DD15 on little endian machines and
DD0-DD7 on big endian machines.
@@ -689,10 +854,12 @@ HDIO_DRIVE_TASKFILE execute raw taskfile
SECTOR
LCYL
HCYL
+ ============ ===============================================
The data_phase field describes the data transfer to be
performed. Value is one of:
+ =================== ========================================
TASKFILE_IN
TASKFILE_MULTI_IN
TASKFILE_OUT
@@ -708,15 +875,18 @@ HDIO_DRIVE_TASKFILE execute raw taskfile
TASKFILE_P_OUT unimplemented
TASKFILE_P_OUT_DMA unimplemented
TASKFILE_P_OUT_DMAQ unimplemented
+ =================== ========================================
The req_cmd field classifies the command type. It may be
one of:
+ ======================== =======================================
IDE_DRIVE_TASK_NO_DATA
IDE_DRIVE_TASK_SET_XFER unimplemented
IDE_DRIVE_TASK_IN
IDE_DRIVE_TASK_OUT unimplemented
IDE_DRIVE_TASK_RAW_WRITE
+ ======================== =======================================
[6] Do not access {in|out}_flags->all except for resetting
all the bits. Always access individual bit fields. ->all
@@ -726,45 +896,57 @@ HDIO_DRIVE_TASKFILE execute raw taskfile
-HDIO_DRIVE_CMD execute a special drive command
+HDIO_DRIVE_CMD
+ execute a special drive command
+
Note: If you don't have a copy of the ANSI ATA specification
handy, you should probably ignore this ioctl.
- usage:
+ usage::
u8 args[4+XFER_SIZE];
+
...
ioctl(fd, HDIO_DRIVE_CMD, args);
inputs:
+ Commands other than WIN_SMART:
- Commands other than WIN_SMART
+ ======= =======
args[0] COMMAND
args[1] NSECTOR
args[2] FEATURE
args[3] NSECTOR
+ ======= =======
- WIN_SMART
+ WIN_SMART:
+
+ ======= =======
args[0] COMMAND
args[1] SECTOR
args[2] FEATURE
args[3] NSECTOR
+ ======= =======
outputs:
+ args[] buffer is filled with register values followed by any
+
- args[] buffer is filled with register values followed by any
data returned by the disk.
+
+ ======== ====================================================
args[0] status
args[1] error
args[2] NSECTOR
args[3] undefined
args[4+] NSECTOR * 512 bytes of data returned by the command.
+ ======== ====================================================
error returns:
- EACCES Access denied: requires CAP_SYS_RAWIO
- ENOMEM Unable to allocate memory for task
- EIO Drive reports error
+ - EACCES Access denied: requires CAP_SYS_RAWIO
+ - ENOMEM Unable to allocate memory for task
+ - EIO Drive reports error
notes:
@@ -789,20 +971,24 @@ HDIO_DRIVE_CMD execute a special drive command
-HDIO_DRIVE_TASK execute task and special drive command
+HDIO_DRIVE_TASK
+ execute task and special drive command
+
Note: If you don't have a copy of the ANSI ATA specification
handy, you should probably ignore this ioctl.
- usage:
+ usage::
u8 args[7];
+
...
ioctl(fd, HDIO_DRIVE_TASK, args);
inputs:
+ Taskfile register values:
- Taskfile register values:
+ ======= =======
args[0] COMMAND
args[1] FEATURE
args[2] NSECTOR
@@ -810,10 +996,13 @@ HDIO_DRIVE_TASK execute task and special drive command
args[4] LCYL
args[5] HCYL
args[6] SELECT
+ ======= =======
outputs:
+ Taskfile register values:
- Taskfile register values:
+
+ ======= =======
args[0] status
args[1] error
args[2] NSECTOR
@@ -821,12 +1010,13 @@ HDIO_DRIVE_TASK execute task and special drive command
args[4] LCYL
args[5] HCYL
args[6] SELECT
+ ======= =======
error returns:
- EACCES Access denied: requires CAP_SYS_RAWIO
- ENOMEM Unable to allocate memory for task
- ENOMSG Device is not a disk drive.
- EIO Drive failed the command.
+ - EACCES Access denied: requires CAP_SYS_RAWIO
+ - ENOMEM Unable to allocate memory for task
+ - ENOMSG Device is not a disk drive.
+ - EIO Drive failed the command.
notes:
@@ -836,236 +1026,317 @@ HDIO_DRIVE_TASK execute task and special drive command
-HDIO_DRIVE_CMD_AEB HDIO_DRIVE_TASK
+HDIO_DRIVE_CMD_AEB
+ HDIO_DRIVE_TASK
+
Not implemented, as of 2.6.8.1
-HDIO_SET_32BIT change io_32bit flags
+HDIO_SET_32BIT
+ change io_32bit flags
- usage:
+
+ usage::
int val;
+
ioctl(fd, HDIO_SET_32BIT, val);
inputs:
- New value for io_32bit flag
+ New value for io_32bit flag
+
+
+
+ outputs:
+ none
+
- outputs: none
error return:
- EINVAL (bdev != bdev->bd_contains) (not sure what this means)
- EACCES Access denied: requires CAP_SYS_ADMIN
- EINVAL value out of range [0 3]
- EBUSY Controller busy
+ - EINVAL (bdev != bdev->bd_contains) (not sure what this means)
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+ - EINVAL value out of range [0 3]
+ - EBUSY Controller busy
-HDIO_SET_NOWERR change ignore-write-error flag
+HDIO_SET_NOWERR
+ change ignore-write-error flag
- usage:
+
+ usage::
int val;
+
ioctl(fd, HDIO_SET_NOWERR, val);
inputs:
- New value for ignore-write-error flag. Used for ignoring
+ New value for ignore-write-error flag. Used for ignoring
+
+
WRERR_STAT
- outputs: none
+ outputs:
+ none
+
+
error return:
- EINVAL (bdev != bdev->bd_contains) (not sure what this means)
- EACCES Access denied: requires CAP_SYS_ADMIN
- EINVAL value out of range [0 1]
- EBUSY Controller busy
+ - EINVAL (bdev != bdev->bd_contains) (not sure what this means)
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+ - EINVAL value out of range [0 1]
+ - EBUSY Controller busy
-HDIO_SET_DMA change use-dma flag
+HDIO_SET_DMA
+ change use-dma flag
- usage:
+
+ usage::
long val;
+
ioctl(fd, HDIO_SET_DMA, val);
inputs:
- New value for use-dma flag
+ New value for use-dma flag
+
+
+
+ outputs:
+ none
+
- outputs: none
error return:
- EINVAL (bdev != bdev->bd_contains) (not sure what this means)
- EACCES Access denied: requires CAP_SYS_ADMIN
- EINVAL value out of range [0 1]
- EBUSY Controller busy
+ - EINVAL (bdev != bdev->bd_contains) (not sure what this means)
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+ - EINVAL value out of range [0 1]
+ - EBUSY Controller busy
-HDIO_SET_PIO_MODE reconfig interface to new speed
+HDIO_SET_PIO_MODE
+ reconfig interface to new speed
- usage:
+
+ usage::
long val;
+
ioctl(fd, HDIO_SET_PIO_MODE, val);
inputs:
- New interface speed.
+ New interface speed.
+
+
+
+ outputs:
+ none
+
- outputs: none
error return:
- EINVAL (bdev != bdev->bd_contains) (not sure what this means)
- EACCES Access denied: requires CAP_SYS_ADMIN
- EINVAL value out of range [0 255]
- EBUSY Controller busy
+ - EINVAL (bdev != bdev->bd_contains) (not sure what this means)
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+ - EINVAL value out of range [0 255]
+ - EBUSY Controller busy
-HDIO_SCAN_HWIF register and (re)scan interface
+HDIO_SCAN_HWIF
+ register and (re)scan interface
- usage:
+
+ usage::
int args[3]
+
...
ioctl(fd, HDIO_SCAN_HWIF, args);
inputs:
+
+ ======= =========================
args[0] io address to probe
+
+
args[1] control address to probe
args[2] irq number
+ ======= =========================
+
+ outputs:
+ none
+
- outputs: none
error returns:
- EACCES Access denied: requires CAP_SYS_RAWIO
- EIO Probe failed.
+ - EACCES Access denied: requires CAP_SYS_RAWIO
+ - EIO Probe failed.
notes:
+ This ioctl initializes the addresses and irq for a disk
+ controller, probes for drives, and creates /proc/ide
+ interfaces as appropriate.
- This ioctl initializes the addresses and irq for a disk
- controller, probes for drives, and creates /proc/ide
- interfaces as appropriate.
+HDIO_UNREGISTER_HWIF
+ unregister interface
-HDIO_UNREGISTER_HWIF unregister interface
- usage:
+ usage::
int index;
+
ioctl(fd, HDIO_UNREGISTER_HWIF, index);
inputs:
- index index of hardware interface to unregister
+ index index of hardware interface to unregister
+
+
+
+ outputs:
+ none
+
- outputs: none
error returns:
- EACCES Access denied: requires CAP_SYS_RAWIO
+ - EACCES Access denied: requires CAP_SYS_RAWIO
notes:
+ This ioctl removes a hardware interface from the kernel.
- This ioctl removes a hardware interface from the kernel.
+ Currently (2.6.8) this ioctl silently fails if any drive on
+ the interface is busy.
- Currently (2.6.8) this ioctl silently fails if any drive on
- the interface is busy.
+HDIO_SET_WCACHE
+ change write cache enable-disable
-HDIO_SET_WCACHE change write cache enable-disable
- usage:
+ usage::
int val;
+
ioctl(fd, HDIO_SET_WCACHE, val);
inputs:
- New value for write cache enable
+ New value for write cache enable
+
+
+
+ outputs:
+ none
+
- outputs: none
error return:
- EINVAL (bdev != bdev->bd_contains) (not sure what this means)
- EACCES Access denied: requires CAP_SYS_ADMIN
- EINVAL value out of range [0 1]
- EBUSY Controller busy
+ - EINVAL (bdev != bdev->bd_contains) (not sure what this means)
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+ - EINVAL value out of range [0 1]
+ - EBUSY Controller busy
-HDIO_SET_ACOUSTIC change acoustic behavior
+HDIO_SET_ACOUSTIC
+ change acoustic behavior
- usage:
+
+ usage::
int val;
+
ioctl(fd, HDIO_SET_ACOUSTIC, val);
inputs:
- New value for drive acoustic settings
+ New value for drive acoustic settings
+
+
+
+ outputs:
+ none
+
- outputs: none
error return:
- EINVAL (bdev != bdev->bd_contains) (not sure what this means)
- EACCES Access denied: requires CAP_SYS_ADMIN
- EINVAL value out of range [0 254]
- EBUSY Controller busy
+ - EINVAL (bdev != bdev->bd_contains) (not sure what this means)
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+ - EINVAL value out of range [0 254]
+ - EBUSY Controller busy
-HDIO_SET_QDMA change use-qdma flag
+HDIO_SET_QDMA
+ change use-qdma flag
+
Not implemented, as of 2.6.8.1
-HDIO_SET_ADDRESS change lba addressing modes
+HDIO_SET_ADDRESS
+ change lba addressing modes
- usage:
+
+ usage::
int val;
+
ioctl(fd, HDIO_SET_ADDRESS, val);
inputs:
- New value for addressing mode
- 0 = 28-bit
- 1 = 48-bit
- 2 = 48-bit doing 28-bit
+ New value for addressing mode
+
+ = ===================
+ 0 28-bit
+ 1 48-bit
+ 2 48-bit doing 28-bit
+ = ===================
+
+ outputs:
+ none
+
- outputs: none
error return:
- EINVAL (bdev != bdev->bd_contains) (not sure what this means)
- EACCES Access denied: requires CAP_SYS_ADMIN
- EINVAL value out of range [0 2]
- EBUSY Controller busy
- EIO Drive does not support lba48 mode.
+ - EINVAL (bdev != bdev->bd_contains) (not sure what this means)
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+ - EINVAL value out of range [0 2]
+ - EBUSY Controller busy
+ - EIO Drive does not support lba48 mode.
HDIO_SET_IDE_SCSI
+ usage::
- usage:
long val;
+
ioctl(fd, HDIO_SET_IDE_SCSI, val);
inputs:
- New value for scsi emulation mode (?)
+ New value for scsi emulation mode (?)
+
+
+
+ outputs:
+ none
+
- outputs: none
error return:
- EINVAL (bdev != bdev->bd_contains) (not sure what this means)
- EACCES Access denied: requires CAP_SYS_ADMIN
- EINVAL value out of range [0 1]
- EBUSY Controller busy
+ - EINVAL (bdev != bdev->bd_contains) (not sure what this means)
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+ - EINVAL value out of range [0 1]
+ - EBUSY Controller busy
HDIO_SET_SCSI_IDE
-
Not implemented, as of 2.6.8.1
-
-
diff --git a/Documentation/ioctl/index.rst b/Documentation/ioctl/index.rst
new file mode 100644
index 000000000000..1a6f437566e3
--- /dev/null
+++ b/Documentation/ioctl/index.rst
@@ -0,0 +1,16 @@
+:orphan:
+
+======
+IOCTLs
+======
+
+.. toctree::
+ :maxdepth: 1
+
+ ioctl-number
+
+ botching-up-ioctls
+ ioctl-decoding
+
+ cdrom
+ hdio
diff --git a/Documentation/ioctl/ioctl-decoding.txt b/Documentation/ioctl/ioctl-decoding.rst
similarity index 54%
rename from Documentation/ioctl/ioctl-decoding.txt
rename to Documentation/ioctl/ioctl-decoding.rst
index e35efb0cec2e..380d6bb3e3ea 100644
--- a/Documentation/ioctl/ioctl-decoding.txt
+++ b/Documentation/ioctl/ioctl-decoding.rst
@@ -1,10 +1,16 @@
+==============================
+Decoding an IOCTL Magic Number
+==============================
+
To decode a hex IOCTL code:
Most architectures use this generic format, but check
include/ARCH/ioctl.h for specifics, e.g. powerpc
uses 3 bits to encode read/write and 13 bits for size.
- bits meaning
+ ====== ==================================
+ bits meaning
+ ====== ==================================
31-30 00 - no parameters: uses _IO macro
10 - read: _IOR
01 - write: _IOW
@@ -16,9 +22,10 @@ uses 3 bits to encode read/write and 13 bits for size.
unique to each driver
7-0 function #
+ ====== ==================================
So for example 0x82187201 is a read with arg length of 0x218,
-character 'r' function 1. Grepping the source reveals this is:
+character 'r' function 1. Grepping the source reveals this is::
-#define VFAT_IOCTL_READDIR_BOTH _IOR('r', 1, struct dirent [2])
+ #define VFAT_IOCTL_READDIR_BOTH _IOR('r', 1, struct dirent [2])
diff --git a/drivers/gpu/drm/drm_ioctl.c b/drivers/gpu/drm/drm_ioctl.c
index 9441a36a2469..bd810454d239 100644
--- a/drivers/gpu/drm/drm_ioctl.c
+++ b/drivers/gpu/drm/drm_ioctl.c
@@ -736,7 +736,7 @@ static const struct drm_ioctl_desc drm_ioctls[] = {
* };
*
* Please make sure that you follow all the best practices from
- * ``Documentation/ioctl/botching-up-ioctls.txt``. Note that drm_ioctl()
+ * ``Documentation/ioctl/botching-up-ioctls.rst``. Note that drm_ioctl()
* automatically zero-extends structures, hence make sure you can add more stuff
* at the end, i.e. don't put a variable sized array there.
*
--
2.21.0
^ permalink raw reply related
* [PATCH v1 13/22] docs: x86: move two x86-specific files to x86 arch dir
From: Mauro Carvalho Chehab @ 2019-06-18 21:05 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Thomas Gleixner, Ingo Molnar, Borislav Petkov,
H. Peter Anvin, x86, Ning Sun, James Morris, Serge E. Hallyn,
tboot-devel, linux-security-module
In-Reply-To: <cover.1560891322.git.mchehab+samsung@kernel.org>
Those two docs belong to the x86 architecture.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/x86/index.rst | 2 ++
Documentation/{Intel-IOMMU.rst => x86/intel-iommu.rst} | 1 -
Documentation/{ => x86}/intel_txt.rst | 1 -
MAINTAINERS | 2 +-
security/Kconfig | 2 +-
5 files changed, 4 insertions(+), 4 deletions(-)
rename Documentation/{Intel-IOMMU.rst => x86/intel-iommu.rst} (99%)
rename Documentation/{ => x86}/intel_txt.rst (99%)
diff --git a/Documentation/x86/index.rst b/Documentation/x86/index.rst
index f2de1b2d3ac7..af64c4bb4447 100644
--- a/Documentation/x86/index.rst
+++ b/Documentation/x86/index.rst
@@ -20,6 +20,8 @@ x86-specific Documentation
mtrr
pat
intel_mpx
+ intel-iommu
+ intel_txt
amd-memory-encryption
pti
mds
diff --git a/Documentation/Intel-IOMMU.rst b/Documentation/x86/intel-iommu.rst
similarity index 99%
rename from Documentation/Intel-IOMMU.rst
rename to Documentation/x86/intel-iommu.rst
index b001104c25c8..c7cf568c0ce7 100644
--- a/Documentation/Intel-IOMMU.rst
+++ b/Documentation/x86/intel-iommu.rst
@@ -1,4 +1,3 @@
-:orphan:
===================
Linux IOMMU Support
diff --git a/Documentation/intel_txt.rst b/Documentation/x86/intel_txt.rst
similarity index 99%
rename from Documentation/intel_txt.rst
rename to Documentation/x86/intel_txt.rst
index 5a55007ecf08..d6af4c7d7625 100644
--- a/Documentation/intel_txt.rst
+++ b/Documentation/x86/intel_txt.rst
@@ -1,4 +1,3 @@
-:orphan:
=====================
Intel(R) TXT Overview
diff --git a/MAINTAINERS b/MAINTAINERS
index 85a6f090ccc0..b7364119ce83 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -8208,7 +8208,7 @@ L: tboot-devel@lists.sourceforge.net
W: http://tboot.sourceforge.net
T: hg http://tboot.hg.sourceforge.net:8000/hgroot/tboot/tboot
S: Supported
-F: Documentation/intel_txt.rst
+F: Documentation/x86/intel_txt.rst
F: include/linux/tboot.h
F: arch/x86/kernel/tboot.c
diff --git a/security/Kconfig b/security/Kconfig
index 4da0d09c3e49..0d65594b5196 100644
--- a/security/Kconfig
+++ b/security/Kconfig
@@ -121,7 +121,7 @@ config INTEL_TXT
See <http://www.intel.com/technology/security/> for more information
about Intel(R) TXT.
See <http://tboot.sourceforge.net> for more information about tboot.
- See Documentation/intel_txt.rst for a description of how to enable
+ See Documentation/x86/intel_txt.rst for a description of how to enable
Intel TXT support in a kernel boot.
If you are unsure as to whether this is required, answer N.
--
2.21.0
^ permalink raw reply related
* [PATCH v1 02/22] docs: ioctl-number.txt: convert it to ReST format
From: Mauro Carvalho Chehab @ 2019-06-18 21:05 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Federico Vaga, Harry Wei, Alex Shi, Doug Ledford,
Jason Gunthorpe, linux-rdma
In-Reply-To: <cover.1560891322.git.mchehab+samsung@kernel.org>
The conversion itself is simple: add a markup for the
title of this file and add markups for both tables.
Yet, the big table here with IOCTL numbers is badly formatted:
on several lines, the "Include File" column has some values that
are bigger than the reserved space there.
Also, on several places, a comment was misplaced at the "Include
File" space.
So, most of the work here is to actually ensure that each field
will be properly fixed.
Also worth to mention that some URLs have the asterisk character
on it. Well, Sphinx has an issue with asterisks in the middle
of an string. As this is URL, use the alternate format: %2A.
As a side effect of this patch, it is now a lot easier to see that
some reserved ioctl numbers are missing the include files
where it is supposed to be used.
PS.: While this is part of a subdir, I opted to convert this
single file alone, as this file has a potential of conflicts,
as most subsystem maintainers touch it.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../{ioctl-number.txt => ioctl-number.rst} | 588 +++++++++---------
Documentation/process/submit-checklist.rst | 2 +-
.../it_IT/process/submit-checklist.rst | 2 +-
.../zh_CN/process/submit-checklist.rst | 2 +-
include/uapi/rdma/rdma_user_ioctl_cmds.h | 2 +-
5 files changed, 304 insertions(+), 292 deletions(-)
rename Documentation/ioctl/{ioctl-number.txt => ioctl-number.rst} (11%)
diff --git a/Documentation/ioctl/ioctl-number.txt b/Documentation/ioctl/ioctl-number.rst
similarity index 11%
rename from Documentation/ioctl/ioctl-number.txt
rename to Documentation/ioctl/ioctl-number.rst
index c9558146ac58..e6d07badafb1 100644
--- a/Documentation/ioctl/ioctl-number.txt
+++ b/Documentation/ioctl/ioctl-number.rst
@@ -1,15 +1,23 @@
+:orphan:
+
+=============
Ioctl Numbers
+=============
+
19 October 1999
+
Michael Elizabeth Chastain
<mec@shout.net>
If you are adding new ioctl's to the kernel, you should use the _IO
macros defined in <linux/ioctl.h>:
+ ====== == ============================================
_IO an ioctl with no parameters
_IOW an ioctl with write parameters (copy_from_user)
_IOR an ioctl with read parameters (copy_to_user)
_IOWR an ioctl with both write and read parameters.
+ ====== == ============================================
'Write' and 'read' are from the user's point of view, just like the
system calls 'write' and 'read'. For example, a SET_FOO ioctl would
@@ -60,291 +68,295 @@ This table lists ioctls visible from user land for Linux/x86. It contains
most drivers up to 2.6.31, but I know I am missing some. There has been
no attempt to list non-X86 architectures or ioctls from drivers/staging/.
-Code Seq#(hex) Include File Comments
-========================================================
-0x00 00-1F linux/fs.h conflict!
-0x00 00-1F scsi/scsi_ioctl.h conflict!
-0x00 00-1F linux/fb.h conflict!
-0x00 00-1F linux/wavefront.h conflict!
-0x02 all linux/fd.h
-0x03 all linux/hdreg.h
-0x04 D2-DC linux/umsdos_fs.h Dead since 2.6.11, but don't reuse these.
-0x06 all linux/lp.h
-0x09 all linux/raid/md_u.h
-0x10 00-0F drivers/char/s390/vmcp.h
-0x10 10-1F arch/s390/include/uapi/sclp_ctl.h
-0x10 20-2F arch/s390/include/uapi/asm/hypfs.h
-0x12 all linux/fs.h
- linux/blkpg.h
-0x1b all InfiniBand Subsystem <http://infiniband.sourceforge.net/>
-0x20 all drivers/cdrom/cm206.h
-0x22 all scsi/sg.h
-'!' 00-1F uapi/linux/seccomp.h
-'#' 00-3F IEEE 1394 Subsystem Block for the entire subsystem
-'$' 00-0F linux/perf_counter.h, linux/perf_event.h
-'%' 00-0F include/uapi/linux/stm.h
- System Trace Module subsystem
- <mailto:alexander.shishkin@linux.intel.com>
-'&' 00-07 drivers/firewire/nosy-user.h
-'1' 00-1F <linux/timepps.h> PPS kit from Ulrich Windl
- <ftp://ftp.de.kernel.org/pub/linux/daemons/ntp/PPS/>
-'2' 01-04 linux/i2o.h
-'3' 00-0F drivers/s390/char/raw3270.h conflict!
-'3' 00-1F linux/suspend_ioctls.h conflict!
- and kernel/power/user.c
-'8' all SNP8023 advanced NIC card
- <mailto:mcr@solidum.com>
-';' 64-7F linux/vfio.h
-'@' 00-0F linux/radeonfb.h conflict!
-'@' 00-0F drivers/video/aty/aty128fb.c conflict!
-'A' 00-1F linux/apm_bios.h conflict!
-'A' 00-0F linux/agpgart.h conflict!
- and drivers/char/agp/compat_ioctl.h
-'A' 00-7F sound/asound.h conflict!
-'B' 00-1F linux/cciss_ioctl.h conflict!
-'B' 00-0F include/linux/pmu.h conflict!
-'B' C0-FF advanced bbus
- <mailto:maassen@uni-freiburg.de>
-'C' all linux/soundcard.h conflict!
-'C' 01-2F linux/capi.h conflict!
-'C' F0-FF drivers/net/wan/cosa.h conflict!
-'D' all arch/s390/include/asm/dasd.h
-'D' 40-5F drivers/scsi/dpt/dtpi_ioctl.h
-'D' 05 drivers/scsi/pmcraid.h
-'E' all linux/input.h conflict!
-'E' 00-0F xen/evtchn.h conflict!
-'F' all linux/fb.h conflict!
-'F' 01-02 drivers/scsi/pmcraid.h conflict!
-'F' 20 drivers/video/fsl-diu-fb.h conflict!
-'F' 20 drivers/video/intelfb/intelfb.h conflict!
-'F' 20 linux/ivtvfb.h conflict!
-'F' 20 linux/matroxfb.h conflict!
-'F' 20 drivers/video/aty/atyfb_base.c conflict!
-'F' 00-0F video/da8xx-fb.h conflict!
-'F' 80-8F linux/arcfb.h conflict!
-'F' DD video/sstfb.h conflict!
-'G' 00-3F drivers/misc/sgi-gru/grulib.h conflict!
-'G' 00-0F linux/gigaset_dev.h conflict!
-'H' 00-7F linux/hiddev.h conflict!
-'H' 00-0F linux/hidraw.h conflict!
-'H' 01 linux/mei.h conflict!
-'H' 02 linux/mei.h conflict!
-'H' 03 linux/mei.h conflict!
-'H' 00-0F sound/asound.h conflict!
-'H' 20-40 sound/asound_fm.h conflict!
-'H' 80-8F sound/sfnt_info.h conflict!
-'H' 10-8F sound/emu10k1.h conflict!
-'H' 10-1F sound/sb16_csp.h conflict!
-'H' 10-1F sound/hda_hwdep.h conflict!
-'H' 40-4F sound/hdspm.h conflict!
-'H' 40-4F sound/hdsp.h conflict!
-'H' 90 sound/usb/usx2y/usb_stream.h
-'H' A0 uapi/linux/usb/cdc-wdm.h
-'H' C0-F0 net/bluetooth/hci.h conflict!
-'H' C0-DF net/bluetooth/hidp/hidp.h conflict!
-'H' C0-DF net/bluetooth/cmtp/cmtp.h conflict!
-'H' C0-DF net/bluetooth/bnep/bnep.h conflict!
-'H' F1 linux/hid-roccat.h <mailto:erazor_de@users.sourceforge.net>
-'H' F8-FA sound/firewire.h
-'I' all linux/isdn.h conflict!
-'I' 00-0F drivers/isdn/divert/isdn_divert.h conflict!
-'I' 40-4F linux/mISDNif.h conflict!
-'J' 00-1F drivers/scsi/gdth_ioctl.h
-'K' all linux/kd.h
-'L' 00-1F linux/loop.h conflict!
-'L' 10-1F drivers/scsi/mpt3sas/mpt3sas_ctl.h conflict!
-'L' 20-2F linux/lightnvm.h
-'L' E0-FF linux/ppdd.h encrypted disk device driver
- <http://linux01.gwdg.de/~alatham/ppdd.html>
-'M' all linux/soundcard.h conflict!
-'M' 01-16 mtd/mtd-abi.h conflict!
- and drivers/mtd/mtdchar.c
-'M' 01-03 drivers/scsi/megaraid/megaraid_sas.h
-'M' 00-0F drivers/video/fsl-diu-fb.h conflict!
-'N' 00-1F drivers/usb/scanner.h
-'N' 40-7F drivers/block/nvme.c
-'O' 00-06 mtd/ubi-user.h UBI
-'P' all linux/soundcard.h conflict!
-'P' 60-6F sound/sscape_ioctl.h conflict!
-'P' 00-0F drivers/usb/class/usblp.c conflict!
-'P' 01-09 drivers/misc/pci_endpoint_test.c conflict!
-'Q' all linux/soundcard.h
-'R' 00-1F linux/random.h conflict!
-'R' 01 linux/rfkill.h conflict!
-'R' C0-DF net/bluetooth/rfcomm.h
-'S' all linux/cdrom.h conflict!
-'S' 80-81 scsi/scsi_ioctl.h conflict!
-'S' 82-FF scsi/scsi.h conflict!
-'S' 00-7F sound/asequencer.h conflict!
-'T' all linux/soundcard.h conflict!
-'T' 00-AF sound/asound.h conflict!
-'T' all arch/x86/include/asm/ioctls.h conflict!
-'T' C0-DF linux/if_tun.h conflict!
-'U' all sound/asound.h conflict!
-'U' 00-CF linux/uinput.h conflict!
-'U' 00-EF linux/usbdevice_fs.h
-'U' C0-CF drivers/bluetooth/hci_uart.h
-'V' all linux/vt.h conflict!
-'V' all linux/videodev2.h conflict!
-'V' C0 linux/ivtvfb.h conflict!
-'V' C0 linux/ivtv.h conflict!
-'V' C0 media/davinci/vpfe_capture.h conflict!
-'V' C0 media/si4713.h conflict!
-'W' 00-1F linux/watchdog.h conflict!
-'W' 00-1F linux/wanrouter.h conflict! (pre 3.9)
-'W' 00-3F sound/asound.h conflict!
-'W' 40-5F drivers/pci/switch/switchtec.c
-'X' all fs/xfs/xfs_fs.h conflict!
- and fs/xfs/linux-2.6/xfs_ioctl32.h
- and include/linux/falloc.h
- and linux/fs.h
-'X' all fs/ocfs2/ocfs_fs.h conflict!
-'X' 01 linux/pktcdvd.h conflict!
-'Y' all linux/cyclades.h
-'Z' 14-15 drivers/message/fusion/mptctl.h
-'[' 00-3F linux/usb/tmc.h USB Test and Measurement Devices
- <mailto:gregkh@linuxfoundation.org>
-'a' all linux/atm*.h, linux/sonet.h ATM on linux
- <http://lrcwww.epfl.ch/>
-'a' 00-0F drivers/crypto/qat/qat_common/adf_cfg_common.h conflict! qat driver
-'b' 00-FF conflict! bit3 vme host bridge
- <mailto:natalia@nikhefk.nikhef.nl>
-'c' all linux/cm4000_cs.h conflict!
-'c' 00-7F linux/comstats.h conflict!
-'c' 00-7F linux/coda.h conflict!
-'c' 00-1F linux/chio.h conflict!
-'c' 80-9F arch/s390/include/asm/chsc.h conflict!
-'c' A0-AF arch/x86/include/asm/msr.h conflict!
-'d' 00-FF linux/char/drm/drm.h conflict!
-'d' 02-40 pcmcia/ds.h conflict!
-'d' F0-FF linux/digi1.h
-'e' all linux/digi1.h conflict!
-'f' 00-1F linux/ext2_fs.h conflict!
-'f' 00-1F linux/ext3_fs.h conflict!
-'f' 00-0F fs/jfs/jfs_dinode.h conflict!
-'f' 00-0F fs/ext4/ext4.h conflict!
-'f' 00-0F linux/fs.h conflict!
-'f' 00-0F fs/ocfs2/ocfs2_fs.h conflict!
-'g' 00-0F linux/usb/gadgetfs.h
-'g' 20-2F linux/usb/g_printer.h
-'h' 00-7F conflict! Charon filesystem
- <mailto:zapman@interlan.net>
-'h' 00-1F linux/hpet.h conflict!
-'h' 80-8F fs/hfsplus/ioctl.c
-'i' 00-3F linux/i2o-dev.h conflict!
-'i' 0B-1F linux/ipmi.h conflict!
-'i' 80-8F linux/i8k.h
-'j' 00-3F linux/joystick.h
-'k' 00-0F linux/spi/spidev.h conflict!
-'k' 00-05 video/kyro.h conflict!
-'k' 10-17 linux/hsi/hsi_char.h HSI character device
-'l' 00-3F linux/tcfs_fs.h transparent cryptographic file system
- <http://web.archive.org/web/*/http://mikonos.dia.unisa.it/tcfs>
-'l' 40-7F linux/udf_fs_i.h in development:
- <http://sourceforge.net/projects/linux-udf/>
-'m' 00-09 linux/mmtimer.h conflict!
-'m' all linux/mtio.h conflict!
-'m' all linux/soundcard.h conflict!
-'m' all linux/synclink.h conflict!
-'m' 00-19 drivers/message/fusion/mptctl.h conflict!
-'m' 00 drivers/scsi/megaraid/megaraid_ioctl.h conflict!
-'n' 00-7F linux/ncp_fs.h and fs/ncpfs/ioctl.c
-'n' 80-8F uapi/linux/nilfs2_api.h NILFS2
-'n' E0-FF linux/matroxfb.h matroxfb
-'o' 00-1F fs/ocfs2/ocfs2_fs.h OCFS2
-'o' 00-03 mtd/ubi-user.h conflict! (OCFS2 and UBI overlaps)
-'o' 40-41 mtd/ubi-user.h UBI
-'o' 01-A1 linux/dvb/*.h DVB
-'p' 00-0F linux/phantom.h conflict! (OpenHaptics needs this)
-'p' 00-1F linux/rtc.h conflict!
-'p' 00-3F linux/mc146818rtc.h conflict!
-'p' 40-7F linux/nvram.h
-'p' 80-9F linux/ppdev.h user-space parport
- <mailto:tim@cyberelk.net>
-'p' A1-A5 linux/pps.h LinuxPPS
- <mailto:giometti@linux.it>
-'q' 00-1F linux/serio.h
-'q' 80-FF linux/telephony.h Internet PhoneJACK, Internet LineJACK
- linux/ixjuser.h <http://web.archive.org/web/*/http://www.quicknet.net>
-'r' 00-1F linux/msdos_fs.h and fs/fat/dir.c
-'s' all linux/cdk.h
-'t' 00-7F linux/ppp-ioctl.h
-'t' 80-8F linux/isdn_ppp.h
-'t' 90-91 linux/toshiba.h toshiba and toshiba_acpi SMM
-'u' 00-1F linux/smb_fs.h gone
-'u' 20-3F linux/uvcvideo.h USB video class host driver
-'u' 40-4f linux/udmabuf.h userspace dma-buf misc device
-'v' 00-1F linux/ext2_fs.h conflict!
-'v' 00-1F linux/fs.h conflict!
-'v' 00-0F linux/sonypi.h conflict!
-'v' 00-0F media/v4l2-subdev.h conflict!
-'v' C0-FF linux/meye.h conflict!
-'w' all CERN SCI driver
-'y' 00-1F packet based user level communications
- <mailto:zapman@interlan.net>
-'z' 00-3F CAN bus card conflict!
- <mailto:hdstich@connectu.ulm.circular.de>
-'z' 40-7F CAN bus card conflict!
- <mailto:oe@port.de>
-'z' 10-4F drivers/s390/crypto/zcrypt_api.h conflict!
-'|' 00-7F linux/media.h
-0x80 00-1F linux/fb.h
-0x89 00-06 arch/x86/include/asm/sockios.h
-0x89 0B-DF linux/sockios.h
-0x89 E0-EF linux/sockios.h SIOCPROTOPRIVATE range
-0x89 E0-EF linux/dn.h PROTOPRIVATE range
-0x89 F0-FF linux/sockios.h SIOCDEVPRIVATE range
-0x8B all linux/wireless.h
-0x8C 00-3F WiNRADiO driver
- <http://www.winradio.com.au/>
-0x90 00 drivers/cdrom/sbpcd.h
-0x92 00-0F drivers/usb/mon/mon_bin.c
-0x93 60-7F linux/auto_fs.h
-0x94 all fs/btrfs/ioctl.h Btrfs filesystem
- and linux/fs.h some lifted to vfs/generic
-0x97 00-7F fs/ceph/ioctl.h Ceph file system
-0x99 00-0F 537-Addinboard driver
- <mailto:buk@buks.ipn.de>
-0xA0 all linux/sdp/sdp.h Industrial Device Project
- <mailto:kenji@bitgate.com>
-0xA1 0 linux/vtpm_proxy.h TPM Emulator Proxy Driver
-0xA3 80-8F Port ACL in development:
- <mailto:tlewis@mindspring.com>
-0xA3 90-9F linux/dtlk.h
-0xA4 00-1F uapi/linux/tee.h Generic TEE subsystem
-0xAA 00-3F linux/uapi/linux/userfaultfd.h
-0xAB 00-1F linux/nbd.h
-0xAC 00-1F linux/raw.h
-0xAD 00 Netfilter device in development:
- <mailto:rusty@rustcorp.com.au>
-0xAE all linux/kvm.h Kernel-based Virtual Machine
- <mailto:kvm@vger.kernel.org>
-0xAF 00-1F linux/fsl_hypervisor.h Freescale hypervisor
-0xB0 all RATIO devices in development:
- <mailto:vgo@ratio.de>
-0xB1 00-1F PPPoX <mailto:mostrows@styx.uwaterloo.ca>
-0xB3 00 linux/mmc/ioctl.h
-0xB4 00-0F linux/gpio.h <mailto:linux-gpio@vger.kernel.org>
-0xB5 00-0F uapi/linux/rpmsg.h <mailto:linux-remoteproc@vger.kernel.org>
-0xB6 all linux/fpga-dfl.h
-0xC0 00-0F linux/usb/iowarrior.h
-0xCA 00-0F uapi/misc/cxl.h
-0xCA 10-2F uapi/misc/ocxl.h
-0xCA 80-BF uapi/scsi/cxlflash_ioctl.h
-0xCB 00-1F CBM serial IEC bus in development:
- <mailto:michael.klein@puffin.lb.shuttle.de>
-0xCC 00-0F drivers/misc/ibmvmc.h pseries VMC driver
-0xCD 01 linux/reiserfs_fs.h
-0xCF 02 fs/cifs/ioctl.c
-0xDB 00-0F drivers/char/mwave/mwavepub.h
-0xDD 00-3F ZFCP device driver see drivers/s390/scsi/
- <mailto:aherrman@de.ibm.com>
-0xE5 00-3F linux/fuse.h
-0xEC 00-01 drivers/platform/chrome/cros_ec_dev.h ChromeOS EC driver
-0xF3 00-3F drivers/usb/misc/sisusbvga/sisusb.h sisfb (in development)
- <mailto:thomas@winischhofer.net>
-0xF4 00-1F video/mbxfb.h mbxfb
- <mailto:raph@8d.com>
-0xF6 all LTTng Linux Trace Toolkit Next Generation
- <mailto:mathieu.desnoyers@efficios.com>
-0xFD all linux/dm-ioctl.h
+==== ===== ======================================================= ================================================================
+Code Seq# Include File Comments
+ (hex)
+==== ===== ======================================================= ================================================================
+0x00 00-1F linux/fs.h conflict!
+0x00 00-1F scsi/scsi_ioctl.h conflict!
+0x00 00-1F linux/fb.h conflict!
+0x00 00-1F linux/wavefront.h conflict!
+0x02 all linux/fd.h
+0x03 all linux/hdreg.h
+0x04 D2-DC linux/umsdos_fs.h Dead since 2.6.11, but don't reuse these.
+0x06 all linux/lp.h
+0x09 all linux/raid/md_u.h
+0x10 00-0F drivers/char/s390/vmcp.h
+0x10 10-1F arch/s390/include/uapi/sclp_ctl.h
+0x10 20-2F arch/s390/include/uapi/asm/hypfs.h
+0x12 all linux/fs.h
+ linux/blkpg.h
+0x1b all InfiniBand Subsystem
+ <http://infiniband.sourceforge.net/>
+0x20 all drivers/cdrom/cm206.h
+0x22 all scsi/sg.h
+'!' 00-1F uapi/linux/seccomp.h
+'#' 00-3F IEEE 1394 Subsystem
+ Block for the entire subsystem
+'$' 00-0F linux/perf_counter.h, linux/perf_event.h
+'%' 00-0F include/uapi/linux/stm.h System Trace Module subsystem
+ <mailto:alexander.shishkin@linux.intel.com>
+'&' 00-07 drivers/firewire/nosy-user.h
+'1' 00-1F linux/timepps.h PPS kit from Ulrich Windl
+ <ftp://ftp.de.kernel.org/pub/linux/daemons/ntp/PPS/>
+'2' 01-04 linux/i2o.h
+'3' 00-0F drivers/s390/char/raw3270.h conflict!
+'3' 00-1F linux/suspend_ioctls.h, conflict!
+ kernel/power/user.c
+'8' all SNP8023 advanced NIC card
+ <mailto:mcr@solidum.com>
+';' 64-7F linux/vfio.h
+'@' 00-0F linux/radeonfb.h conflict!
+'@' 00-0F drivers/video/aty/aty128fb.c conflict!
+'A' 00-1F linux/apm_bios.h conflict!
+'A' 00-0F linux/agpgart.h, conflict!
+ drivers/char/agp/compat_ioctl.h
+'A' 00-7F sound/asound.h conflict!
+'B' 00-1F linux/cciss_ioctl.h conflict!
+'B' 00-0F include/linux/pmu.h conflict!
+'B' C0-FF advanced bbus <mailto:maassen@uni-freiburg.de>
+'C' all linux/soundcard.h conflict!
+'C' 01-2F linux/capi.h conflict!
+'C' F0-FF drivers/net/wan/cosa.h conflict!
+'D' all arch/s390/include/asm/dasd.h
+'D' 40-5F drivers/scsi/dpt/dtpi_ioctl.h
+'D' 05 drivers/scsi/pmcraid.h
+'E' all linux/input.h conflict!
+'E' 00-0F xen/evtchn.h conflict!
+'F' all linux/fb.h conflict!
+'F' 01-02 drivers/scsi/pmcraid.h conflict!
+'F' 20 drivers/video/fsl-diu-fb.h conflict!
+'F' 20 drivers/video/intelfb/intelfb.h conflict!
+'F' 20 linux/ivtvfb.h conflict!
+'F' 20 linux/matroxfb.h conflict!
+'F' 20 drivers/video/aty/atyfb_base.c conflict!
+'F' 00-0F video/da8xx-fb.h conflict!
+'F' 80-8F linux/arcfb.h conflict!
+'F' DD video/sstfb.h conflict!
+'G' 00-3F drivers/misc/sgi-gru/grulib.h conflict!
+'G' 00-0F linux/gigaset_dev.h conflict!
+'H' 00-7F linux/hiddev.h conflict!
+'H' 00-0F linux/hidraw.h conflict!
+'H' 01 linux/mei.h conflict!
+'H' 02 linux/mei.h conflict!
+'H' 03 linux/mei.h conflict!
+'H' 00-0F sound/asound.h conflict!
+'H' 20-40 sound/asound_fm.h conflict!
+'H' 80-8F sound/sfnt_info.h conflict!
+'H' 10-8F sound/emu10k1.h conflict!
+'H' 10-1F sound/sb16_csp.h conflict!
+'H' 10-1F sound/hda_hwdep.h conflict!
+'H' 40-4F sound/hdspm.h conflict!
+'H' 40-4F sound/hdsp.h conflict!
+'H' 90 sound/usb/usx2y/usb_stream.h
+'H' A0 uapi/linux/usb/cdc-wdm.h
+'H' C0-F0 net/bluetooth/hci.h conflict!
+'H' C0-DF net/bluetooth/hidp/hidp.h conflict!
+'H' C0-DF net/bluetooth/cmtp/cmtp.h conflict!
+'H' C0-DF net/bluetooth/bnep/bnep.h conflict!
+'H' F1 linux/hid-roccat.h <mailto:erazor_de@users.sourceforge.net>
+'H' F8-FA sound/firewire.h
+'I' all linux/isdn.h conflict!
+'I' 00-0F drivers/isdn/divert/isdn_divert.h conflict!
+'I' 40-4F linux/mISDNif.h conflict!
+'J' 00-1F drivers/scsi/gdth_ioctl.h
+'K' all linux/kd.h
+'L' 00-1F linux/loop.h conflict!
+'L' 10-1F drivers/scsi/mpt3sas/mpt3sas_ctl.h conflict!
+'L' 20-2F linux/lightnvm.h
+'L' E0-FF linux/ppdd.h encrypted disk device driver
+ <http://linux01.gwdg.de/~alatham/ppdd.html>
+'M' all linux/soundcard.h conflict!
+'M' 01-16 mtd/mtd-abi.h conflict!
+ and drivers/mtd/mtdchar.c
+'M' 01-03 drivers/scsi/megaraid/megaraid_sas.h
+'M' 00-0F drivers/video/fsl-diu-fb.h conflict!
+'N' 00-1F drivers/usb/scanner.h
+'N' 40-7F drivers/block/nvme.c
+'O' 00-06 mtd/ubi-user.h UBI
+'P' all linux/soundcard.h conflict!
+'P' 60-6F sound/sscape_ioctl.h conflict!
+'P' 00-0F drivers/usb/class/usblp.c conflict!
+'P' 01-09 drivers/misc/pci_endpoint_test.c conflict!
+'Q' all linux/soundcard.h
+'R' 00-1F linux/random.h conflict!
+'R' 01 linux/rfkill.h conflict!
+'R' C0-DF net/bluetooth/rfcomm.h
+'S' all linux/cdrom.h conflict!
+'S' 80-81 scsi/scsi_ioctl.h conflict!
+'S' 82-FF scsi/scsi.h conflict!
+'S' 00-7F sound/asequencer.h conflict!
+'T' all linux/soundcard.h conflict!
+'T' 00-AF sound/asound.h conflict!
+'T' all arch/x86/include/asm/ioctls.h conflict!
+'T' C0-DF linux/if_tun.h conflict!
+'U' all sound/asound.h conflict!
+'U' 00-CF linux/uinput.h conflict!
+'U' 00-EF linux/usbdevice_fs.h
+'U' C0-CF drivers/bluetooth/hci_uart.h
+'V' all linux/vt.h conflict!
+'V' all linux/videodev2.h conflict!
+'V' C0 linux/ivtvfb.h conflict!
+'V' C0 linux/ivtv.h conflict!
+'V' C0 media/davinci/vpfe_capture.h conflict!
+'V' C0 media/si4713.h conflict!
+'W' 00-1F linux/watchdog.h conflict!
+'W' 00-1F linux/wanrouter.h conflict! (pre 3.9)
+'W' 00-3F sound/asound.h conflict!
+'W' 40-5F drivers/pci/switch/switchtec.c
+'X' all fs/xfs/xfs_fs.h, conflict!
+ fs/xfs/linux-2.6/xfs_ioctl32.h,
+ include/linux/falloc.h,
+ linux/fs.h,
+'X' all fs/ocfs2/ocfs_fs.h conflict!
+'X' 01 linux/pktcdvd.h conflict!
+'Y' all linux/cyclades.h
+'Z' 14-15 drivers/message/fusion/mptctl.h
+'[' 00-3F linux/usb/tmc.h USB Test and Measurement Devices
+ <mailto:gregkh@linuxfoundation.org>
+'a' all linux/atm*.h, linux/sonet.h ATM on linux
+ <http://lrcwww.epfl.ch/>
+'a' 00-0F drivers/crypto/qat/qat_common/adf_cfg_common.h conflict! qat driver
+'b' 00-FF conflict! bit3 vme host bridge
+ <mailto:natalia@nikhefk.nikhef.nl>
+'c' all linux/cm4000_cs.h conflict!
+'c' 00-7F linux/comstats.h conflict!
+'c' 00-7F linux/coda.h conflict!
+'c' 00-1F linux/chio.h conflict!
+'c' 80-9F arch/s390/include/asm/chsc.h conflict!
+'c' A0-AF arch/x86/include/asm/msr.h conflict!
+'d' 00-FF linux/char/drm/drm.h conflict!
+'d' 02-40 pcmcia/ds.h conflict!
+'d' F0-FF linux/digi1.h
+'e' all linux/digi1.h conflict!
+'f' 00-1F linux/ext2_fs.h conflict!
+'f' 00-1F linux/ext3_fs.h conflict!
+'f' 00-0F fs/jfs/jfs_dinode.h conflict!
+'f' 00-0F fs/ext4/ext4.h conflict!
+'f' 00-0F linux/fs.h conflict!
+'f' 00-0F fs/ocfs2/ocfs2_fs.h conflict!
+'g' 00-0F linux/usb/gadgetfs.h
+'g' 20-2F linux/usb/g_printer.h
+'h' 00-7F conflict! Charon filesystem
+ <mailto:zapman@interlan.net>
+'h' 00-1F linux/hpet.h conflict!
+'h' 80-8F fs/hfsplus/ioctl.c
+'i' 00-3F linux/i2o-dev.h conflict!
+'i' 0B-1F linux/ipmi.h conflict!
+'i' 80-8F linux/i8k.h
+'j' 00-3F linux/joystick.h
+'k' 00-0F linux/spi/spidev.h conflict!
+'k' 00-05 video/kyro.h conflict!
+'k' 10-17 linux/hsi/hsi_char.h HSI character device
+'l' 00-3F linux/tcfs_fs.h transparent cryptographic file system
+ <http://web.archive.org/web/%2A/http://mikonos.dia.unisa.it/tcfs>
+'l' 40-7F linux/udf_fs_i.h in development:
+ <http://sourceforge.net/projects/linux-udf/>
+'m' 00-09 linux/mmtimer.h conflict!
+'m' all linux/mtio.h conflict!
+'m' all linux/soundcard.h conflict!
+'m' all linux/synclink.h conflict!
+'m' 00-19 drivers/message/fusion/mptctl.h conflict!
+'m' 00 drivers/scsi/megaraid/megaraid_ioctl.h conflict!
+'n' 00-7F linux/ncp_fs.h and fs/ncpfs/ioctl.c
+'n' 80-8F uapi/linux/nilfs2_api.h NILFS2
+'n' E0-FF linux/matroxfb.h matroxfb
+'o' 00-1F fs/ocfs2/ocfs2_fs.h OCFS2
+'o' 00-03 mtd/ubi-user.h conflict! (OCFS2 and UBI overlaps)
+'o' 40-41 mtd/ubi-user.h UBI
+'o' 01-A1 `linux/dvb/*.h` DVB
+'p' 00-0F linux/phantom.h conflict! (OpenHaptics needs this)
+'p' 00-1F linux/rtc.h conflict!
+'p' 00-3F linux/mc146818rtc.h conflict!
+'p' 40-7F linux/nvram.h
+'p' 80-9F linux/ppdev.h user-space parport
+ <mailto:tim@cyberelk.net>
+'p' A1-A5 linux/pps.h LinuxPPS
+ <mailto:giometti@linux.it>
+'q' 00-1F linux/serio.h
+'q' 80-FF linux/telephony.h Internet PhoneJACK, Internet LineJACK
+ linux/ixjuser.h <http://web.archive.org/web/%2A/http://www.quicknet.net>
+'r' 00-1F linux/msdos_fs.h and fs/fat/dir.c
+'s' all linux/cdk.h
+'t' 00-7F linux/ppp-ioctl.h
+'t' 80-8F linux/isdn_ppp.h
+'t' 90-91 linux/toshiba.h toshiba and toshiba_acpi SMM
+'u' 00-1F linux/smb_fs.h gone
+'u' 20-3F linux/uvcvideo.h USB video class host driver
+'u' 40-4f linux/udmabuf.h userspace dma-buf misc device
+'v' 00-1F linux/ext2_fs.h conflict!
+'v' 00-1F linux/fs.h conflict!
+'v' 00-0F linux/sonypi.h conflict!
+'v' 00-0F media/v4l2-subdev.h conflict!
+'v' C0-FF linux/meye.h conflict!
+'w' all CERN SCI driver
+'y' 00-1F packet based user level communications
+ <mailto:zapman@interlan.net>
+'z' 00-3F CAN bus card conflict!
+ <mailto:hdstich@connectu.ulm.circular.de>
+'z' 40-7F CAN bus card conflict!
+ <mailto:oe@port.de>
+'z' 10-4F drivers/s390/crypto/zcrypt_api.h conflict!
+'|' 00-7F linux/media.h
+0x80 00-1F linux/fb.h
+0x89 00-06 arch/x86/include/asm/sockios.h
+0x89 0B-DF linux/sockios.h
+0x89 E0-EF linux/sockios.h SIOCPROTOPRIVATE range
+0x89 E0-EF linux/dn.h PROTOPRIVATE range
+0x89 F0-FF linux/sockios.h SIOCDEVPRIVATE range
+0x8B all linux/wireless.h
+0x8C 00-3F WiNRADiO driver
+ <http://www.winradio.com.au/>
+0x90 00 drivers/cdrom/sbpcd.h
+0x92 00-0F drivers/usb/mon/mon_bin.c
+0x93 60-7F linux/auto_fs.h
+0x94 all fs/btrfs/ioctl.h Btrfs filesystem
+ and linux/fs.h some lifted to vfs/generic
+0x97 00-7F fs/ceph/ioctl.h Ceph file system
+0x99 00-0F 537-Addinboard driver
+ <mailto:buk@buks.ipn.de>
+0xA0 all linux/sdp/sdp.h Industrial Device Project
+ <mailto:kenji@bitgate.com>
+0xA1 0 linux/vtpm_proxy.h TPM Emulator Proxy Driver
+0xA3 80-8F Port ACL in development:
+ <mailto:tlewis@mindspring.com>
+0xA3 90-9F linux/dtlk.h
+0xA4 00-1F uapi/linux/tee.h Generic TEE subsystem
+0xAA 00-3F linux/uapi/linux/userfaultfd.h
+0xAB 00-1F linux/nbd.h
+0xAC 00-1F linux/raw.h
+0xAD 00 Netfilter device in development:
+ <mailto:rusty@rustcorp.com.au>
+0xAE all linux/kvm.h Kernel-based Virtual Machine
+ <mailto:kvm@vger.kernel.org>
+0xAF 00-1F linux/fsl_hypervisor.h Freescale hypervisor
+0xB0 all RATIO devices in development:
+ <mailto:vgo@ratio.de>
+0xB1 00-1F PPPoX
+ <mailto:mostrows@styx.uwaterloo.ca>
+0xB3 00 linux/mmc/ioctl.h
+0xB4 00-0F linux/gpio.h <mailto:linux-gpio@vger.kernel.org>
+0xB5 00-0F uapi/linux/rpmsg.h <mailto:linux-remoteproc@vger.kernel.org>
+0xB6 all linux/fpga-dfl.h
+0xC0 00-0F linux/usb/iowarrior.h
+0xCA 00-0F uapi/misc/cxl.h
+0xCA 10-2F uapi/misc/ocxl.h
+0xCA 80-BF uapi/scsi/cxlflash_ioctl.h
+0xCB 00-1F CBM serial IEC bus in development:
+ <mailto:michael.klein@puffin.lb.shuttle.de>
+0xCC 00-0F drivers/misc/ibmvmc.h pseries VMC driver
+0xCD 01 linux/reiserfs_fs.h
+0xCF 02 fs/cifs/ioctl.c
+0xDB 00-0F drivers/char/mwave/mwavepub.h
+0xDD 00-3F ZFCP device driver see drivers/s390/scsi/
+ <mailto:aherrman@de.ibm.com>
+0xE5 00-3F linux/fuse.h
+0xEC 00-01 drivers/platform/chrome/cros_ec_dev.h ChromeOS EC driver
+0xF3 00-3F drivers/usb/misc/sisusbvga/sisusb.h sisfb (in development)
+ <mailto:thomas@winischhofer.net>
+0xF4 00-1F video/mbxfb.h mbxfb
+ <mailto:raph@8d.com>
+0xF6 all LTTng Linux Trace Toolkit Next Generation
+ <mailto:mathieu.desnoyers@efficios.com>
+0xFD all linux/dm-ioctl.h
+==== ===== ======================================================= ================================================================
diff --git a/Documentation/process/submit-checklist.rst b/Documentation/process/submit-checklist.rst
index 365efc9e4aa8..8e56337d422d 100644
--- a/Documentation/process/submit-checklist.rst
+++ b/Documentation/process/submit-checklist.rst
@@ -107,7 +107,7 @@ and elsewhere regarding submitting Linux kernel patches.
and why.
26) If any ioctl's are added by the patch, then also update
- ``Documentation/ioctl/ioctl-number.txt``.
+ ``Documentation/ioctl/ioctl-number.rst``.
27) If your modified source code depends on or uses any of the kernel
APIs or features that are related to the following ``Kconfig`` symbols,
diff --git a/Documentation/translations/it_IT/process/submit-checklist.rst b/Documentation/translations/it_IT/process/submit-checklist.rst
index ea74cae958d7..995ee69fab11 100644
--- a/Documentation/translations/it_IT/process/submit-checklist.rst
+++ b/Documentation/translations/it_IT/process/submit-checklist.rst
@@ -117,7 +117,7 @@ sottomissione delle patch, in particolare
sorgenti che ne spieghi la logica: cosa fanno e perché.
25) Se la patch aggiunge nuove chiamate ioctl, allora aggiornate
- ``Documentation/ioctl/ioctl-number.txt``.
+ ``Documentation/ioctl/ioctl-number.rst``.
26) Se il codice che avete modificato dipende o usa una qualsiasi interfaccia o
funzionalità del kernel che è associata a uno dei seguenti simboli
diff --git a/Documentation/translations/zh_CN/process/submit-checklist.rst b/Documentation/translations/zh_CN/process/submit-checklist.rst
index f4785d2b0491..8738c55e42a2 100644
--- a/Documentation/translations/zh_CN/process/submit-checklist.rst
+++ b/Documentation/translations/zh_CN/process/submit-checklist.rst
@@ -97,7 +97,7 @@ Linux内核补丁提交清单
24) 所有内存屏障例如 ``barrier()``, ``rmb()``, ``wmb()`` 都需要源代码中的注
释来解释它们正在执行的操作及其原因的逻辑。
-25) 如果补丁添加了任何ioctl，那么也要更新 ``Documentation/ioctl/ioctl-number.txt``
+25) 如果补丁添加了任何ioctl，那么也要更新 ``Documentation/ioctl/ioctl-number.rst``
26) 如果修改后的源代码依赖或使用与以下 ``Kconfig`` 符号相关的任何内核API或
功能，则在禁用相关 ``Kconfig`` 符号和/或 ``=m`` （如果该选项可用）的情况
diff --git a/include/uapi/rdma/rdma_user_ioctl_cmds.h b/include/uapi/rdma/rdma_user_ioctl_cmds.h
index 26213f49f5c8..54e16a589472 100644
--- a/include/uapi/rdma/rdma_user_ioctl_cmds.h
+++ b/include/uapi/rdma/rdma_user_ioctl_cmds.h
@@ -36,7 +36,7 @@
#include <linux/types.h>
#include <linux/ioctl.h>
-/* Documentation/ioctl/ioctl-number.txt */
+/* Documentation/ioctl/ioctl-number.rst */
#define RDMA_IOCTL_MAGIC 0x1b
#define RDMA_VERBS_IOCTL \
_IOWR(RDMA_IOCTL_MAGIC, 1, struct ib_uverbs_ioctl_hdr)
--
2.21.0
^ permalink raw reply related
* [PATCH v1 06/22] docs: blockdev: convert to ReST
From: Mauro Carvalho Chehab @ 2019-06-18 21:05 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Jens Axboe, Jiri Kosina, Minchan Kim,
Nitin Gupta, Sergey Senozhatsky, Shuah Khan, linux-block,
linux-kselftest
In-Reply-To: <cover.1560891322.git.mchehab+samsung@kernel.org>
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: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../admin-guide/kernel-parameters.txt | 18 +-
...structure-v9.txt => data-structure-v9.rst} | 6 +-
Documentation/blockdev/drbd/figures.rst | 28 +++
.../blockdev/drbd/{README.txt => index.rst} | 15 +-
.../blockdev/{floppy.txt => floppy.rst} | 88 ++++----
Documentation/blockdev/index.rst | 16 ++
Documentation/blockdev/{nbd.txt => nbd.rst} | 2 +-
.../blockdev/{paride.txt => paride.rst} | 194 +++++++++--------
.../blockdev/{ramdisk.txt => ramdisk.rst} | 55 ++---
Documentation/blockdev/{zram.txt => zram.rst} | 195 ++++++++++++------
MAINTAINERS | 8 +-
drivers/block/Kconfig | 8 +-
drivers/block/floppy.c | 2 +-
drivers/block/zram/Kconfig | 6 +-
tools/testing/selftests/zram/README | 2 +-
15 files changed, 398 insertions(+), 245 deletions(-)
rename Documentation/blockdev/drbd/{data-structure-v9.txt => data-structure-v9.rst} (94%)
create mode 100644 Documentation/blockdev/drbd/figures.rst
rename Documentation/blockdev/drbd/{README.txt => index.rst} (55%)
rename Documentation/blockdev/{floppy.txt => floppy.rst} (81%)
create mode 100644 Documentation/blockdev/index.rst
rename Documentation/blockdev/{nbd.txt => nbd.rst} (96%)
rename Documentation/blockdev/{paride.txt => paride.rst} (81%)
rename Documentation/blockdev/{ramdisk.txt => ramdisk.rst} (84%)
rename Documentation/blockdev/{zram.txt => zram.rst} (76%)
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 873062810484..20780fbc948d 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -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
@@ -2238,7 +2238,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>
@@ -3283,7 +3283,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.
@@ -3527,7 +3527,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.
@@ -3542,10 +3542,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.
@@ -3657,7 +3657,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.
@@ -3679,7 +3679,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
@@ -3708,7 +3708,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
diff --git a/Documentation/blockdev/drbd/data-structure-v9.txt b/Documentation/blockdev/drbd/data-structure-v9.rst
similarity index 94%
rename from Documentation/blockdev/drbd/data-structure-v9.txt
rename to Documentation/blockdev/drbd/data-structure-v9.rst
index 1e52a0e32624..66036b901644 100644
--- a/Documentation/blockdev/drbd/data-structure-v9.txt
+++ b/Documentation/blockdev/drbd/data-structure-v9.rst
@@ -1,3 +1,7 @@
+================================
+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 |
diff --git a/Documentation/blockdev/drbd/figures.rst b/Documentation/blockdev/drbd/figures.rst
new file mode 100644
index 000000000000..3e3fd4b8a478
--- /dev/null
+++ b/Documentation/blockdev/drbd/figures.rst
@@ -0,0 +1,28 @@
+.. 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
diff --git a/Documentation/blockdev/drbd/README.txt b/Documentation/blockdev/drbd/index.rst
similarity index 55%
rename from Documentation/blockdev/drbd/README.txt
rename to Documentation/blockdev/drbd/index.rst
index 627b0a1bf35e..68ecd5c113e9 100644
--- a/Documentation/blockdev/drbd/README.txt
+++ b/Documentation/blockdev/drbd/index.rst
@@ -1,4 +1,9 @@
+==========================================
+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
+.. toctree::
+ :maxdepth: 1
-DRBD-8.3-data-packets.svg, DRBD-data-packets.svg
- relates some functions, and write packets.
-
-conn-states-8.dot, disk-states-8.dot, node-states-8.dot
- The sub graphs of DRBD's state transitions
+ data-structure-v9
+ figures
diff --git a/Documentation/blockdev/floppy.txt b/Documentation/blockdev/floppy.rst
similarity index 81%
rename from Documentation/blockdev/floppy.txt
rename to Documentation/blockdev/floppy.rst
index e2240f5ab64d..4a8f31cf4139 100644
--- a/Documentation/blockdev/floppy.txt
+++ b/Documentation/blockdev/floppy.rst
@@ -1,35 +1,37 @@
-This file describes the floppy driver.
+=============
+Floppy Driver
+=============
FAQ list:
=========
- A FAQ list may be found in the fdutils package (see below), and also
+A FAQ list may be found in the fdutils package (see below), and also
at <http://fdutils.linux.lu/faq.html>.
LILO configuration options (Thinkpad users, read this)
======================================================
- The floppy driver is configured using the 'floppy=' option in
+The floppy driver is configured using the 'floppy=' option in
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):
+Example: If your kernel is called linux-2.6.9, type the following line
+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"
- If you give options both in the lilo config file and on the boot
+If you give options both in the lilo config file and on the boot
prompt, the option strings of both places are concatenated, the boot
prompt options coming last. That's why there are also options to
restore the default behavior.
@@ -38,21 +40,23 @@ restore the default behavior.
Module configuration options
============================
- If you use the floppy driver as a module, use the following syntax:
-modprobe floppy floppy="<options>"
+If you use the floppy driver as a module, use the following syntax::
-Example:
- modprobe floppy floppy="omnibook messages"
+ modprobe floppy floppy="<options>"
- If you need certain options enabled every time you load the floppy driver,
-you can put:
+Example::
- options floppy floppy="omnibook messages"
+ modprobe floppy floppy="omnibook messages"
+
+If you need certain options enabled every time you load the floppy driver,
+you can put::
+
+ options floppy floppy="omnibook messages"
in a configuration file in /etc/modprobe.d/.
- The floppy driver related options are:
+The floppy driver related options are:
floppy=asus_pci
Sets the bit mask to allow only units 0 and 1. (default)
@@ -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,47 +202,54 @@ 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:
==================================================
- Additional parameters of the floppy driver can be configured at
+Additional parameters of the floppy driver can be configured at
runtime. Utilities which do this can be found in the fdutils package.
This package also contains a new version of mtools which allows to
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
==========================================
- If you have a question or a bug report about the floppy driver, mail
+If you have a question or a bug report about the floppy driver, mail
me at Alain.Knaff@poboxes.com . If you post to Usenet, preferably use
comp.os.linux.hardware. As the volume in these groups is rather high,
be sure to include the word "floppy" (or "FLOPPY") in the subject
line. If the reported problem happens when mounting floppy disks, be
sure to mention also the type of the filesystem in the subject line.
- Be sure to read the FAQ before mailing/posting any bug reports!
+Be sure to read the FAQ before mailing/posting any bug reports!
- Alain
+Alain
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
diff --git a/Documentation/blockdev/index.rst b/Documentation/blockdev/index.rst
new file mode 100644
index 000000000000..a9af6ed8b4aa
--- /dev/null
+++ b/Documentation/blockdev/index.rst
@@ -0,0 +1,16 @@
+:orphan:
+
+===========================
+The Linux RapidIO Subsystem
+===========================
+
+.. toctree::
+ :maxdepth: 1
+
+ floppy
+ nbd
+ paride
+ ramdisk
+ zram
+
+ drbd/index
diff --git a/Documentation/blockdev/nbd.txt b/Documentation/blockdev/nbd.rst
similarity index 96%
rename from Documentation/blockdev/nbd.txt
rename to Documentation/blockdev/nbd.rst
index db242ea2bce8..d78dfe559dcf 100644
--- a/Documentation/blockdev/nbd.txt
+++ b/Documentation/blockdev/nbd.rst
@@ -1,3 +1,4 @@
+==================================
Network Block Device (TCP version)
==================================
@@ -28,4 +29,3 @@ max_part
nbds_max
Number of block devices that should be initialized (default: 16).
-
diff --git a/Documentation/blockdev/paride.txt b/Documentation/blockdev/paride.rst
similarity index 81%
rename from Documentation/blockdev/paride.txt
rename to Documentation/blockdev/paride.rst
index ee6717e3771d..87b4278bf314 100644
--- a/Documentation/blockdev/paride.txt
+++ b/Documentation/blockdev/paride.rst
@@ -1,15 +1,17 @@
-
- Linux and parallel port IDE devices
+===================================
+Linux and parallel port IDE devices
+===================================
PARIDE v1.03 (c) 1997-8 Grant Guenther <grant@torque.net>
1. Introduction
+===============
Owing to the simplicity and near universality of the parallel port interface
to personal computers, many external devices such as portable hard-disk,
CD-ROM, LS-120 and tape drives use the parallel port to connect to their
host computer. While some devices (notably scanners) use ad-hoc methods
-to pass commands and data through the parallel port interface, most
+to pass commands and data through the parallel port interface, most
external devices are actually identical to an internal model, but with
a parallel-port adapter chip added in. Some of the original parallel port
adapters were little more than mechanisms for multiplexing a SCSI bus.
@@ -28,47 +30,50 @@ were to open up a parallel port CD-ROM drive, for instance, one would
find a standard ATAPI CD-ROM drive, a power supply, and a single adapter
that interconnected a standard PC parallel port cable and a standard
IDE cable. It is usually possible to exchange the CD-ROM device with
-any other device using the IDE interface.
+any other device using the IDE interface.
The document describes the support in Linux for parallel port IDE
devices. It does not cover parallel port SCSI devices, "ditto" tape
-drives or scanners. Many different devices are supported by the
+drives or scanners. Many different devices are supported by the
parallel port IDE subsystem, including:
- MicroSolutions backpack CD-ROM
- MicroSolutions backpack PD/CD
- MicroSolutions backpack hard-drives
- MicroSolutions backpack 8000t tape drive
- SyQuest EZ-135, EZ-230 & SparQ drives
- Avatar Shark
- Imation Superdisk LS-120
- Maxell Superdisk LS-120
- FreeCom Power CD
- Hewlett-Packard 5GB and 8GB tape drives
- Hewlett-Packard 7100 and 7200 CD-RW drives
+ - MicroSolutions backpack CD-ROM
+ - MicroSolutions backpack PD/CD
+ - MicroSolutions backpack hard-drives
+ - MicroSolutions backpack 8000t tape drive
+ - SyQuest EZ-135, EZ-230 & SparQ drives
+ - Avatar Shark
+ - Imation Superdisk LS-120
+ - Maxell Superdisk LS-120
+ - FreeCom Power CD
+ - Hewlett-Packard 5GB and 8GB tape drives
+ - Hewlett-Packard 7100 and 7200 CD-RW drives
as well as most of the clone and no-name products on the market.
To support such a wide range of devices, PARIDE, the parallel port IDE
subsystem, is actually structured in three parts. There is a base
paride module which provides a registry and some common methods for
-accessing the parallel ports. The second component is a set of
-high-level drivers for each of the different types of supported devices:
+accessing the parallel ports. The second component is a set of
+high-level drivers for each of the different types of supported devices:
+ === =============
pd IDE disk
pcd ATAPI CD-ROM
pf ATAPI disk
pt ATAPI tape
pg ATAPI generic
+ === =============
(Currently, the pg driver is only used with CD-R drives).
The high-level drivers function according to the relevant standards.
The third component of PARIDE is a set of low-level protocol drivers
for each of the parallel port IDE adapter chips. Thanks to the interest
-and encouragement of Linux users from many parts of the world,
+and encouragement of Linux users from many parts of the world,
support is available for almost all known adapter protocols:
+ ==== ====================================== ====
aten ATEN EH-100 (HK)
bpck Microsolutions backpack (US)
comm DataStor (old-type) "commuter" adapter (TW)
@@ -83,9 +88,11 @@ support is available for almost all known adapter protocols:
ktti KT Technology PHd adapter (SG)
on20 OnSpec 90c20 (US)
on26 OnSpec 90c26 (US)
+ ==== ====================================== ====
2. Using the PARIDE subsystem
+=============================
While configuring the Linux kernel, you may choose either to build
the PARIDE drivers into your kernel, or to build them as modules.
@@ -94,10 +101,10 @@ In either case, you will need to select "Parallel port IDE device support"
as well as at least one of the high-level drivers and at least one
of the parallel port communication protocols. If you do not know
what kind of parallel port adapter is used in your drive, you could
-begin by checking the file names and any text files on your DOS
+begin by checking the file names and any text files on your DOS
installation floppy. Alternatively, you can look at the markings on
the adapter chip itself. That's usually sufficient to identify the
-correct device.
+correct device.
You can actually select all the protocol modules, and allow the PARIDE
subsystem to try them all for you.
@@ -105,8 +112,9 @@ subsystem to try them all for you.
For the "brand-name" products listed above, here are the protocol
and high-level drivers that you would use:
+ ================ ============ ====== ========
Manufacturer Model Driver Protocol
-
+ ================ ============ ====== ========
MicroSolutions CD-ROM pcd bpck
MicroSolutions PD drive pf bpck
MicroSolutions hard-drive pd bpck
@@ -119,8 +127,10 @@ and high-level drivers that you would use:
Hewlett-Packard 5GB Tape pt epat
Hewlett-Packard 7200e (CD) pcd epat
Hewlett-Packard 7200e (CD-R) pg epat
+ ================ ============ ====== ========
2.1 Configuring built-in drivers
+---------------------------------
We recommend that you get to know how the drivers work and how to
configure them as loadable modules, before attempting to compile a
@@ -143,7 +153,7 @@ protocol identification number and, for some devices, the drive's
chain ID. While your system is booting, a number of messages are
displayed on the console. Like all such messages, they can be
reviewed with the 'dmesg' command. Among those messages will be
-some lines like:
+some lines like::
paride: bpck registered as protocol 0
paride: epat registered as protocol 1
@@ -158,10 +168,10 @@ the last two digits of the drive's serial number (but read MicroSolutions'
documentation about this).
As an example, let's assume that you have a MicroSolutions PD/CD drive
-with unit ID number 36 connected to the parallel port at 0x378, a SyQuest
-EZ-135 connected to the chained port on the PD/CD drive and also an
-Imation Superdisk connected to port 0x278. You could give the following
-options on your boot command:
+with unit ID number 36 connected to the parallel port at 0x378, a SyQuest
+EZ-135 connected to the chained port on the PD/CD drive and also an
+Imation Superdisk connected to port 0x278. You could give the following
+options on your boot command::
pd.drive0=0x378,1 pf.drive0=0x278,1 pf.drive1=0x378,0,36
@@ -169,24 +179,27 @@ In the last option, pf.drive1 configures device /dev/pf1, the 0x378
is the parallel port base address, the 0 is the protocol registration
number and 36 is the chain ID.
-Please note: while PARIDE will work both with and without the
+Please note: while PARIDE will work both with and without the
PARPORT parallel port sharing system that is included by the
"Parallel port support" option, PARPORT must be included and enabled
if you want to use chains of devices on the same parallel port.
2.2 Loading and configuring PARIDE as modules
+----------------------------------------------
It is much faster and simpler to get to understand the PARIDE drivers
-if you use them as loadable kernel modules.
+if you use them as loadable kernel modules.
-Note 1: using these drivers with the "kerneld" automatic module loading
-system is not recommended for beginners, and is not documented here.
+Note 1:
+ using these drivers with the "kerneld" automatic module loading
+ system is not recommended for beginners, and is not documented here.
-Note 2: if you build PARPORT support as a loadable module, PARIDE must
-also be built as loadable modules, and PARPORT must be loaded before the
-PARIDE modules.
+Note 2:
+ if you build PARPORT support as a loadable module, PARIDE must
+ also be built as loadable modules, and PARPORT must be loaded before
+ the PARIDE modules.
-To use PARIDE, you must begin by
+To use PARIDE, you must begin by::
insmod paride
@@ -195,8 +208,8 @@ among other tasks.
Then, load as many of the protocol modules as you think you might need.
As you load each module, it will register the protocols that it supports,
-and print a log message to your kernel log file and your console. For
-example:
+and print a log message to your kernel log file and your console. For
+example::
# insmod epat
paride: epat registered as protocol 0
@@ -205,22 +218,22 @@ example:
paride: k971 registered as protocol 2
Finally, you can load high-level drivers for each kind of device that
-you have connected. By default, each driver will autoprobe for a single
+you have connected. By default, each driver will autoprobe for a single
device, but you can support up to four similar devices by giving their
individual co-ordinates when you load the driver.
For example, if you had two no-name CD-ROM drives both using the
KingByte KBIC-951A adapter, one on port 0x378 and the other on 0x3bc
-you could give the following command:
+you could give the following command::
# insmod pcd drive0=0x378,1 drive1=0x3bc,1
For most adapters, giving a port address and protocol number is sufficient,
-but check the source files in linux/drivers/block/paride for more
+but check the source files in linux/drivers/block/paride for more
information. (Hopefully someone will write some man pages one day !).
As another example, here's what happens when PARPORT is installed, and
-a SyQuest EZ-135 is attached to port 0x378:
+a SyQuest EZ-135 is attached to port 0x378::
# insmod paride
paride: version 1.0 installed
@@ -237,46 +250,47 @@ Note that the last line is the output from the generic partition table
scanner - in this case it reports that it has found a disk with one partition.
2.3 Using a PARIDE device
+--------------------------
Once the drivers have been loaded, you can access PARIDE devices in the
same way as their traditional counterparts. You will probably need to
create the device "special files". Here is a simple script that you can
-cut to a file and execute:
+cut to a file and execute::
-#!/bin/bash
-#
-# mkd -- a script to create the device special files for the PARIDE subsystem
-#
-function mkdev {
- mknod $1 $2 $3 $4 ; chmod 0660 $1 ; chown root:disk $1
-}
-#
-function pd {
- D=$( printf \\$( printf "x%03x" $[ $1 + 97 ] ) )
- mkdev pd$D b 45 $[ $1 * 16 ]
- for P in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
- do mkdev pd$D$P b 45 $[ $1 * 16 + $P ]
- done
-}
-#
-cd /dev
-#
-for u in 0 1 2 3 ; do pd $u ; done
-for u in 0 1 2 3 ; do mkdev pcd$u b 46 $u ; done
-for u in 0 1 2 3 ; do mkdev pf$u b 47 $u ; done
-for u in 0 1 2 3 ; do mkdev pt$u c 96 $u ; done
-for u in 0 1 2 3 ; do mkdev npt$u c 96 $[ $u + 128 ] ; done
-for u in 0 1 2 3 ; do mkdev pg$u c 97 $u ; done
-#
-# end of mkd
+ #!/bin/bash
+ #
+ # mkd -- a script to create the device special files for the PARIDE subsystem
+ #
+ function mkdev {
+ mknod $1 $2 $3 $4 ; chmod 0660 $1 ; chown root:disk $1
+ }
+ #
+ function pd {
+ D=$( printf \\$( printf "x%03x" $[ $1 + 97 ] ) )
+ mkdev pd$D b 45 $[ $1 * 16 ]
+ for P in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+ do mkdev pd$D$P b 45 $[ $1 * 16 + $P ]
+ done
+ }
+ #
+ cd /dev
+ #
+ for u in 0 1 2 3 ; do pd $u ; done
+ for u in 0 1 2 3 ; do mkdev pcd$u b 46 $u ; done
+ for u in 0 1 2 3 ; do mkdev pf$u b 47 $u ; done
+ for u in 0 1 2 3 ; do mkdev pt$u c 96 $u ; done
+ for u in 0 1 2 3 ; do mkdev npt$u c 96 $[ $u + 128 ] ; done
+ for u in 0 1 2 3 ; do mkdev pg$u c 97 $u ; done
+ #
+ # end of mkd
With the device files and drivers in place, you can access PARIDE devices
-like any other Linux device. For example, to mount a CD-ROM in pcd0, use:
+like any other Linux device. For example, to mount a CD-ROM in pcd0, use::
mount /dev/pcd0 /cdrom
If you have a fresh Avatar Shark cartridge, and the drive is pda, you
-might do something like:
+might do something like::
fdisk /dev/pda -- make a new partition table with
partition 1 of type 83
@@ -289,41 +303,46 @@ might do something like:
Devices like the Imation superdisk work in the same way, except that
they do not have a partition table. For example to make a 120MB
-floppy that you could share with a DOS system:
+floppy that you could share with a DOS system::
mkdosfs /dev/pf0
mount /dev/pf0 /mnt
2.4 The pf driver
+------------------
The pf driver is intended for use with parallel port ATAPI disk
devices. The most common devices in this category are PD drives
and LS-120 drives. Traditionally, media for these devices are not
partitioned. Consequently, the pf driver does not support partitioned
-media. This may be changed in a future version of the driver.
+media. This may be changed in a future version of the driver.
2.5 Using the pt driver
+------------------------
The pt driver for parallel port ATAPI tape drives is a minimal driver.
-It does not yet support many of the standard tape ioctl operations.
+It does not yet support many of the standard tape ioctl operations.
For best performance, a block size of 32KB should be used. You will
probably want to set the parallel port delay to 0, if you can.
2.6 Using the pg driver
+------------------------
The pg driver can be used in conjunction with the cdrecord program
to create CD-ROMs. Please get cdrecord version 1.6.1 or later
-from ftp://ftp.fokus.gmd.de/pub/unix/cdrecord/ . To record CD-R media
-your parallel port should ideally be set to EPP mode, and the "port delay"
-should be set to 0. With those settings it is possible to record at 2x
+from ftp://ftp.fokus.gmd.de/pub/unix/cdrecord/ . To record CD-R media
+your parallel port should ideally be set to EPP mode, and the "port delay"
+should be set to 0. With those settings it is possible to record at 2x
speed without any buffer underruns. If you cannot get the driver to work
in EPP mode, try to use "bidirectional" or "PS/2" mode and 1x speeds only.
3. Troubleshooting
+==================
3.1 Use EPP mode if you can
+----------------------------
The most common problems that people report with the PARIDE drivers
concern the parallel port CMOS settings. At this time, none of the
@@ -332,6 +351,7 @@ If you are able to do so, please set your parallel port into EPP mode
using your CMOS setup procedure.
3.2 Check the port delay
+-------------------------
Some parallel ports cannot reliably transfer data at full speed. To
offset the errors, the PARIDE protocol modules introduce a "port
@@ -347,23 +367,25 @@ read the comments at the beginning of the driver source files in
linux/drivers/block/paride.
3.3 Some drives need a printer reset
+-------------------------------------
There appear to be a number of "noname" external drives on the market
that do not always power up correctly. We have noticed this with some
drives based on OnSpec and older Freecom adapters. In these rare cases,
the adapter can often be reinitialised by issuing a "printer reset" on
-the parallel port. As the reset operation is potentially disruptive in
-multiple device environments, the PARIDE drivers will not do it
-automatically. You can however, force a printer reset by doing:
+the parallel port. As the reset operation is potentially disruptive in
+multiple device environments, the PARIDE drivers will not do it
+automatically. You can however, force a printer reset by doing::
insmod lp reset=1
rmmod lp
If you have one of these marginal cases, you should probably build
your paride drivers as modules, and arrange to do the printer reset
-before loading the PARIDE drivers.
+before loading the PARIDE drivers.
3.4 Use the verbose option and dmesg if you need help
+------------------------------------------------------
While a lot of testing has gone into these drivers to make them work
as smoothly as possible, problems will arise. If you do have problems,
@@ -373,7 +395,7 @@ clues, then please make sure that only one drive is hooked to your system,
and that either (a) PARPORT is enabled or (b) no other device driver
is using your parallel port (check in /proc/ioports). Then, load the
appropriate drivers (you can load several protocol modules if you want)
-as in:
+as in::
# insmod paride
# insmod epat
@@ -394,12 +416,14 @@ by e-mail to grant@torque.net, or join the linux-parport mailing list
and post your report there.
3.5 For more information or help
+---------------------------------
You can join the linux-parport mailing list by sending a mail message
-to
+to:
+
linux-parport-request@torque.net
-with the single word
+with the single word::
subscribe
@@ -412,6 +436,4 @@ have in your mail headers, when sending mail to the list server.
You might also find some useful information on the linux-parport
web pages (although they are not always up to date) at
- http://web.archive.org/web/*/http://www.torque.net/parport/
-
-
+ http://web.archive.org/web/%2E/http://www.torque.net/parport/
diff --git a/Documentation/blockdev/ramdisk.txt b/Documentation/blockdev/ramdisk.rst
similarity index 84%
rename from Documentation/blockdev/ramdisk.txt
rename to Documentation/blockdev/ramdisk.rst
index 501e12e0323e..b7c2268f8dec 100644
--- a/Documentation/blockdev/ramdisk.txt
+++ b/Documentation/blockdev/ramdisk.rst
@@ -1,7 +1,8 @@
+==========================================
Using the RAM disk block device with Linux
-------------------------------------------
+==========================================
-Contents:
+.. Contents:
1) Overview
2) Kernel Command Line Parameters
@@ -42,7 +43,7 @@ rescue floppy disk.
2a) Kernel Command Line Parameters
ramdisk_size=N
- ==============
+ Size of the ramdisk.
This parameter tells the RAM disk driver to set up RAM disks of N k size. The
default is 4096 (4 MB).
@@ -50,16 +51,13 @@ default is 4096 (4 MB).
2b) Module parameters
rd_nr
- =====
- /dev/ramX devices created.
+ /dev/ramX devices created.
max_part
- ========
- Maximum partition number.
+ Maximum partition number.
rd_size
- =======
- See ramdisk_size.
+ See ramdisk_size.
3) Using "rdev -r"
------------------
@@ -71,11 +69,11 @@ to 2 MB (2^11) of where to find the RAM disk (this used to be the size). Bit
prompt/wait sequence is to be given before trying to read the RAM disk. Since
the RAM disk dynamically grows as data is being written into it, a size field
is not required. Bits 11 to 13 are not currently used and may as well be zero.
-These numbers are no magical secrets, as seen below:
+These numbers are no magical secrets, as seen below::
-./arch/x86/kernel/setup.c:#define RAMDISK_IMAGE_START_MASK 0x07FF
-./arch/x86/kernel/setup.c:#define RAMDISK_PROMPT_FLAG 0x8000
-./arch/x86/kernel/setup.c:#define RAMDISK_LOAD_FLAG 0x4000
+ ./arch/x86/kernel/setup.c:#define RAMDISK_IMAGE_START_MASK 0x07FF
+ ./arch/x86/kernel/setup.c:#define RAMDISK_PROMPT_FLAG 0x8000
+ ./arch/x86/kernel/setup.c:#define RAMDISK_LOAD_FLAG 0x4000
Consider a typical two floppy disk setup, where you will have the
kernel on disk one, and have already put a RAM disk image onto disk #2.
@@ -92,20 +90,23 @@ sequence so that you have a chance to switch floppy disks.
The command line equivalent is: "prompt_ramdisk=1"
Putting that together gives 2^15 + 2^14 + 0 = 49152 for an rdev word.
-So to create disk one of the set, you would do:
+So to create disk one of the set, you would do::
/usr/src/linux# cat arch/x86/boot/zImage > /dev/fd0
/usr/src/linux# rdev /dev/fd0 /dev/fd0
/usr/src/linux# rdev -r /dev/fd0 49152
-If you make a boot disk that has LILO, then for the above, you would use:
+If you make a boot disk that has LILO, then for the above, you would use::
+
append = "ramdisk_start=0 load_ramdisk=1 prompt_ramdisk=1"
-Since the default start = 0 and the default prompt = 1, you could use:
+
+Since the default start = 0 and the default prompt = 1, you could use::
+
append = "load_ramdisk=1"
4) An Example of Creating a Compressed RAM Disk
-----------------------------------------------
+-----------------------------------------------
To create a RAM disk image, you will need a spare block device to
construct it on. This can be the RAM disk device itself, or an
@@ -120,11 +121,11 @@ a) Decide on the RAM disk size that you want. Say 2 MB for this example.
Create it by writing to the RAM disk device. (This step is not currently
required, but may be in the future.) It is wise to zero out the
area (esp. for disks) so that maximal compression is achieved for
- the unused blocks of the image that you are about to create.
+ the unused blocks of the image that you are about to create::
dd if=/dev/zero of=/dev/ram0 bs=1k count=2048
-b) Make a filesystem on it. Say ext2fs for this example.
+b) Make a filesystem on it. Say ext2fs for this example::
mke2fs -vm0 /dev/ram0 2048
@@ -133,11 +134,11 @@ c) Mount it, copy the files you want to it (eg: /etc/* /dev/* ...)
d) Compress the contents of the RAM disk. The level of compression
will be approximately 50% of the space used by the files. Unused
- space on the RAM disk will compress to almost nothing.
+ space on the RAM disk will compress to almost nothing::
dd if=/dev/ram0 bs=1k count=2048 | gzip -v9 > /tmp/ram_image.gz
-e) Put the kernel onto the floppy
+e) Put the kernel onto the floppy::
dd if=zImage of=/dev/fd0 bs=1k
@@ -146,13 +147,13 @@ f) Put the RAM disk image onto the floppy, after the kernel. Use an offset
(possibly larger) kernel onto the same floppy later without overlapping
the RAM disk image. An offset of 400 kB for kernels about 350 kB in
size would be reasonable. Make sure offset+size of ram_image.gz is
- not larger than the total space on your floppy (usually 1440 kB).
+ not larger than the total space on your floppy (usually 1440 kB)::
dd if=/tmp/ram_image.gz of=/dev/fd0 bs=1k seek=400
g) Use "rdev" to set the boot device, RAM disk offset, prompt flag, etc.
For prompt_ramdisk=1, load_ramdisk=1, ramdisk_start=400, one would
- have 2^15 + 2^14 + 400 = 49552.
+ have 2^15 + 2^14 + 400 = 49552::
rdev /dev/fd0 /dev/fd0
rdev -r /dev/fd0 49552
@@ -160,15 +161,17 @@ g) Use "rdev" to set the boot device, RAM disk offset, prompt flag, etc.
That is it. You now have your boot/root compressed RAM disk floppy. Some
users may wish to combine steps (d) and (f) by using a pipe.
---------------------------------------------------------------------------
+
Paul Gortmaker 12/95
Changelog:
----------
-10-22-04 : Updated to reflect changes in command line options, remove
+10-22-04 :
+ Updated to reflect changes in command line options, remove
obsolete references, general cleanup.
James Nelson (james4765@gmail.com)
-12-95 : Original Document
+12-95 :
+ Original Document
diff --git a/Documentation/blockdev/zram.txt b/Documentation/blockdev/zram.rst
similarity index 76%
rename from Documentation/blockdev/zram.txt
rename to Documentation/blockdev/zram.rst
index 4df0ce271085..2111231c9c0f 100644
--- a/Documentation/blockdev/zram.txt
+++ b/Documentation/blockdev/zram.rst
@@ -1,7 +1,9 @@
+========================================
zram: Compressed RAM based block devices
-----------------------------------------
+========================================
-* Introduction
+Introduction
+============
The zram module creates RAM based block devices named /dev/zram<id>
(<id> = 0, 1, ...). Pages written to these disks are compressed and stored
@@ -12,9 +14,11 @@ use as swap disks, various caches under /var and maybe many more :)
Statistics for individual zram devices are exported through sysfs nodes at
/sys/block/zram<id>/
-* Usage
+Usage
+=====
There are several ways to configure and manage zram device(-s):
+
a) using zram and zram_control sysfs attributes
b) using zramctl utility, provided by util-linux (util-linux@vger.kernel.org).
@@ -22,7 +26,7 @@ In this document we will describe only 'manual' zram configuration steps,
IOW, zram and zram_control sysfs attributes.
In order to get a better idea about zramctl please consult util-linux
-documentation, zramctl man-page or `zramctl --help'. Please be informed
+documentation, zramctl man-page or `zramctl --help`. Please be informed
that zram maintainers do not develop/maintain util-linux or zramctl, should
you have any questions please contact util-linux@vger.kernel.org
@@ -30,19 +34,23 @@ Following shows a typical sequence of steps for using zram.
WARNING
=======
+
For the sake of simplicity we skip error checking parts in most of the
examples below. However, it is your sole responsibility to handle errors.
zram sysfs attributes always return negative values in case of errors.
The list of possible return codes:
--EBUSY -- an attempt to modify an attribute that cannot be changed once
-the device has been initialised. Please reset device first;
--ENOMEM -- zram was not able to allocate enough memory to fulfil your
-needs;
--EINVAL -- invalid input has been provided.
+
+======== =============================================================
+-EBUSY an attempt to modify an attribute that cannot be changed once
+ the device has been initialised. Please reset device first;
+-ENOMEM zram was not able to allocate enough memory to fulfil your
+ needs;
+-EINVAL invalid input has been provided.
+======== =============================================================
If you use 'echo', the returned value that is changed by 'echo' utility,
-and, in general case, something like:
+and, in general case, something like::
echo 3 > /sys/block/zram0/max_comp_streams
if [ $? -ne 0 ];
@@ -51,7 +59,11 @@ and, in general case, something like:
should suffice.
-1) Load Module:
+1) Load Module
+==============
+
+::
+
modprobe zram num_devices=4
This creates 4 devices: /dev/zram{0,1,2,3}
@@ -59,6 +71,8 @@ num_devices parameter is optional and tells zram how many devices should be
pre-created. Default: 1.
2) Set max number of compression streams
+========================================
+
Regardless the value passed to this attribute, ZRAM will always
allocate multiple compression streams - one per online CPUs - thus
allowing several concurrent compression operations. The number of
@@ -66,16 +80,20 @@ allocated compression streams goes down when some of the CPUs
become offline. There is no single-compression-stream mode anymore,
unless you are running a UP system or has only 1 CPU online.
-To find out how many streams are currently available:
+To find out how many streams are currently available::
+
cat /sys/block/zram0/max_comp_streams
3) Select compression algorithm
+===============================
+
Using comp_algorithm device attribute one can see available and
currently selected (shown in square brackets) compression algorithms,
change selected compression algorithm (once the device is initialised
there is no way to change compression algorithm).
-Examples:
+Examples::
+
#show supported compression algorithms
cat /sys/block/zram0/comp_algorithm
lzo [lz4]
@@ -83,20 +101,23 @@ Examples:
#select lzo compression algorithm
echo lzo > /sys/block/zram0/comp_algorithm
-For the time being, the `comp_algorithm' content does not necessarily
+For the time being, the `comp_algorithm` content does not necessarily
show every compression algorithm supported by the kernel. We keep this
list primarily to simplify device configuration and one can configure
a new device with a compression algorithm that is not listed in
-`comp_algorithm'. The thing is that, internally, ZRAM uses Crypto API
+`comp_algorithm`. The thing is that, internally, ZRAM uses Crypto API
and, if some of the algorithms were built as modules, it's impossible
to list all of them using, for instance, /proc/crypto or any other
method. This, however, has an advantage of permitting the usage of
custom crypto compression modules (implementing S/W or H/W compression).
4) Set Disksize
+===============
+
Set disk size by writing the value to sysfs node 'disksize'.
The value can be either in bytes or you can use mem suffixes.
-Examples:
+Examples::
+
# Initialize /dev/zram0 with 50MB disksize
echo $((50*1024*1024)) > /sys/block/zram0/disksize
@@ -111,10 +132,13 @@ since we expect a 2:1 compression ratio. Note that zram uses about 0.1% of the
size of the disk when not in use so a huge zram is wasteful.
5) Set memory limit: Optional
+=============================
+
Set memory limit by writing the value to sysfs node 'mem_limit'.
The value can be either in bytes or you can use mem suffixes.
In addition, you could change the value in runtime.
-Examples:
+Examples::
+
# limit /dev/zram0 with 50MB memory
echo $((50*1024*1024)) > /sys/block/zram0/mem_limit
@@ -126,7 +150,11 @@ Examples:
# To disable memory limit
echo 0 > /sys/block/zram0/mem_limit
-6) Activate:
+6) Activate
+===========
+
+::
+
mkswap /dev/zram0
swapon /dev/zram0
@@ -134,6 +162,7 @@ Examples:
mount /dev/zram1 /tmp
7) Add/remove zram devices
+==========================
zram provides a control interface, which enables dynamic (on-demand) device
addition and removal.
@@ -142,37 +171,44 @@ In order to add a new /dev/zramX device, perform read operation on hot_add
attribute. This will return either new device's device id (meaning that you
can use /dev/zram<id>) or error code.
-Example:
+Example::
+
cat /sys/class/zram-control/hot_add
1
To remove the existing /dev/zramX device (where X is a device id)
-execute
+execute::
+
echo X > /sys/class/zram-control/hot_remove
-8) Stats:
+8) Stats
+========
+
Per-device statistics are exported as various nodes under /sys/block/zram<id>/
A brief description of exported device attributes. For more details please
read Documentation/ABI/testing/sysfs-block-zram.
+====================== ====== ===============================================
Name access description
----- ------ -----------
+====================== ====== ===============================================
disksize RW show and set the device's disk size
initstate RO shows the initialization state of the device
reset WO trigger device reset
-mem_used_max WO reset the `mem_used_max' counter (see later)
-mem_limit WO specifies the maximum amount of memory ZRAM can use
- to store the compressed data
-writeback_limit WO specifies the maximum amount of write IO zram can
- write out to backing device as 4KB unit
+mem_used_max WO reset the `mem_used_max` counter (see later)
+mem_limit WO specifies the maximum amount of memory ZRAM can
+ use to store the compressed data
+writeback_limit WO specifies the maximum amount of write IO zram
+ can write out to backing device as 4KB unit
writeback_limit_enable RW show and set writeback_limit feature
-max_comp_streams RW the number of possible concurrent compress operations
+max_comp_streams RW the number of possible concurrent compress
+ operations
comp_algorithm RW show and change the compression algorithm
compact WO trigger memory compaction
debug_stat RO this file is used for zram debugging purposes
backing_dev RW set up backend storage for zram to write out
idle WO mark allocated slot as idle
+====================== ====== ===============================================
User space is advised to use the following files to read the device statistics.
@@ -188,23 +224,31 @@ The stat file represents device's I/O statistics not accounted by block
layer and, thus, not available in zram<id>/stat file. It consists of a
single line of text and contains the following stats separated by
whitespace:
- failed_reads the number of failed reads
- failed_writes the number of failed writes
- invalid_io the number of non-page-size-aligned I/O requests
+
+ ============= =============================================================
+ failed_reads The number of failed reads
+ failed_writes The number of failed writes
+ invalid_io The number of non-page-size-aligned I/O requests
notify_free Depending on device usage scenario it may account
+
a) the number of pages freed because of swap slot free
- notifications or b) the number of pages freed because of
- REQ_OP_DISCARD requests sent by bio. The former ones are
- sent to a swap block device when a swap slot is freed,
- which implies that this disk is being used as a swap disk.
+ notifications
+ b) the number of pages freed because of
+ REQ_OP_DISCARD requests sent by bio. The former ones are
+ sent to a swap block device when a swap slot is freed,
+ which implies that this disk is being used as a swap disk.
+
The latter ones are sent by filesystem mounted with
discard option, whenever some data blocks are getting
discarded.
+ ============= =============================================================
File /sys/block/zram<id>/mm_stat
The stat file represents device's mm statistics. It consists of a single
line of text and contains the following stats separated by whitespace:
+
+ ================ =============================================================
orig_data_size uncompressed size of data stored in this disk.
This excludes same-element-filled pages (same_pages) since
no memory is allocated for them.
@@ -223,58 +267,71 @@ line of text and contains the following stats separated by whitespace:
No memory is allocated for such pages.
pages_compacted the number of pages freed during compaction
huge_pages the number of incompressible pages
+ ================ =============================================================
File /sys/block/zram<id>/bd_stat
The stat file represents device's backing device statistics. It consists of
a single line of text and contains the following stats separated by whitespace:
+
+ ============== =============================================================
bd_count size of data written in backing device.
Unit: 4K bytes
bd_reads the number of reads from backing device
Unit: 4K bytes
bd_writes the number of writes to backing device
Unit: 4K bytes
+ ============== =============================================================
+
+9) Deactivate
+=============
+
+::
-9) Deactivate:
swapoff /dev/zram0
umount /dev/zram1
-10) Reset:
- Write any positive value to 'reset' sysfs node
- echo 1 > /sys/block/zram0/reset
- echo 1 > /sys/block/zram1/reset
+10) Reset
+=========
+
+ Write any positive value to 'reset' sysfs node::
+
+ echo 1 > /sys/block/zram0/reset
+ echo 1 > /sys/block/zram1/reset
This frees all the memory allocated for the given device and
resets the disksize to zero. You must set the disksize again
before reusing the device.
-* Optional Feature
+Optional Feature
+================
-= writeback
+writeback
+---------
With CONFIG_ZRAM_WRITEBACK, zram can write idle/incompressible page
to backing storage rather than keeping it in memory.
-To use the feature, admin should set up backing device via
+To use the feature, admin should set up backing device via::
- "echo /dev/sda5 > /sys/block/zramX/backing_dev"
+ echo /dev/sda5 > /sys/block/zramX/backing_dev
before disksize setting. It supports only partition at this moment.
-If admin want to use incompressible page writeback, they could do via
+If admin want to use incompressible page writeback, they could do via::
- "echo huge > /sys/block/zramX/write"
+ echo huge > /sys/block/zramX/write
To use idle page writeback, first, user need to declare zram pages
-as idle.
+as idle::
- "echo all > /sys/block/zramX/idle"
+ echo all > /sys/block/zramX/idle
From now on, any pages on zram are idle pages. The idle mark
will be removed until someone request access of the block.
IOW, unless there is access request, those pages are still idle pages.
-Admin can request writeback of those idle pages at right timing via
+Admin can request writeback of those idle pages at right timing via::
- "echo idle > /sys/block/zramX/writeback"
+ echo idle > /sys/block/zramX/writeback
With the command, zram writeback idle pages from memory to the storage.
@@ -285,7 +342,7 @@ to guarantee storage health for entire product life.
To overcome the concern, zram supports "writeback_limit" feature.
The "writeback_limit_enable"'s default value is 0 so that it doesn't limit
any writeback. IOW, if admin want to apply writeback budget, he should
-enable writeback_limit_enable via
+enable writeback_limit_enable via::
$ echo 1 > /sys/block/zramX/writeback_limit_enable
@@ -296,7 +353,7 @@ until admin set the budget via /sys/block/zramX/writeback_limit.
assigned via /sys/block/zramX/writeback_limit is meaninless.)
If admin want to limit writeback as per-day 400M, he could do it
-like below.
+like below::
$ MB_SHIFT=20
$ 4K_SHIFT=12
@@ -305,16 +362,16 @@ like below.
$ echo 1 > /sys/block/zram0/writeback_limit_enable
If admin want to allow further write again once the bugdet is exausted,
-he could do it like below
+he could do it like below::
$ echo $((400<<MB_SHIFT>>4K_SHIFT)) > \
/sys/block/zram0/writeback_limit
-If admin want to see remaining writeback budget since he set,
+If admin want to see remaining writeback budget since he set::
$ cat /sys/block/zramX/writeback_limit
-If admin want to disable writeback limit, he could do
+If admin want to disable writeback limit, he could do::
$ echo 0 > /sys/block/zramX/writeback_limit_enable
@@ -326,25 +383,35 @@ budget in next setting is user's job.
If admin want to measure writeback count in a certain period, he could
know it via /sys/block/zram0/bd_stat's 3rd column.
-= memory tracking
+memory tracking
+===============
With CONFIG_ZRAM_MEMORY_TRACKING, user can know information of the
zram block. It could be useful to catch cold or incompressible
pages of the process with*pagemap.
+
If you enable the feature, you could see block state via
-/sys/kernel/debug/zram/zram0/block_state". The output is as follows,
+/sys/kernel/debug/zram/zram0/block_state". The output is as follows::
300 75.033841 .wh.
301 63.806904 s...
302 63.806919 ..hi
-First column is zram's block index.
-Second column is access time since the system was booted
-Third column is state of the block.
-(s: same page
-w: written page to backing store
-h: huge page
-i: idle page)
+First column
+ zram's block index.
+Second column
+ access time since the system was booted
+Third column
+ state of the block:
+
+ s:
+ same page
+ w:
+ written page to backing store
+ h:
+ huge page
+ i:
+ idle page
First line of above example says 300th block is accessed at 75.033841sec
and the block's state is huge so it is written back to the backing
diff --git a/MAINTAINERS b/MAINTAINERS
index b2254bc8e495..163327d6a856 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -10961,7 +10961,7 @@ M: Josef Bacik <josef@toxicpanda.com>
S: Maintained
L: linux-block@vger.kernel.org
L: nbd@other.debian.org
-F: Documentation/blockdev/nbd.txt
+F: Documentation/blockdev/nbd.rst
F: drivers/block/nbd.c
F: include/trace/events/nbd.h
F: include/uapi/linux/nbd.h
@@ -11963,7 +11963,7 @@ PARIDE DRIVERS FOR PARALLEL PORT IDE DEVICES
M: Tim Waugh <tim@cyberelk.net>
L: linux-parport@lists.infradead.org (subscribers-only)
S: Maintained
-F: Documentation/blockdev/paride.txt
+F: Documentation/blockdev/paride.rst
F: drivers/block/paride/
PARISC ARCHITECTURE
@@ -13245,7 +13245,7 @@ F: drivers/net/wireless/ralink/rt2x00/
RAMDISK RAM BLOCK DEVICE DRIVER
M: Jens Axboe <axboe@kernel.dk>
S: Maintained
-F: Documentation/blockdev/ramdisk.txt
+F: Documentation/blockdev/ramdisk.rst
F: drivers/block/brd.c
RANCHU VIRTUAL BOARD FOR MIPS
@@ -17584,7 +17584,7 @@ R: Sergey Senozhatsky <sergey.senozhatsky.work@gmail.com>
L: linux-kernel@vger.kernel.org
S: Maintained
F: drivers/block/zram/
-F: Documentation/blockdev/zram.txt
+F: Documentation/blockdev/zram.rst
ZS DECSTATION Z85C30 SERIAL DRIVER
M: "Maciej W. Rozycki" <macro@linux-mips.org>
diff --git a/drivers/block/Kconfig b/drivers/block/Kconfig
index 96ec7e0fc1ea..c43690b973d8 100644
--- a/drivers/block/Kconfig
+++ b/drivers/block/Kconfig
@@ -31,7 +31,7 @@ config BLK_DEV_FD
If you want to use the floppy disk drive(s) of your PC under Linux,
say Y. Information about this driver, especially important for IBM
Thinkpad users, is contained in
- <file:Documentation/blockdev/floppy.txt>.
+ <file:Documentation/blockdev/floppy.rst>.
That file also contains the location of the Floppy driver FAQ as
well as location of the fdutils package used to configure additional
parameters of the driver at run time.
@@ -96,7 +96,7 @@ config PARIDE
your computer's parallel port. Most of them are actually IDE devices
using a parallel port IDE adapter. This option enables the PARIDE
subsystem which contains drivers for many of these external drives.
- Read <file:Documentation/blockdev/paride.txt> for more information.
+ Read <file:Documentation/blockdev/paride.rst> for more information.
If you have said Y to the "Parallel-port support" configuration
option, you may share a single port between your printer and other
@@ -261,7 +261,7 @@ config BLK_DEV_NBD
userland (making server and client physically the same computer,
communicating using the loopback network device).
- Read <file:Documentation/blockdev/nbd.txt> for more information,
+ Read <file:Documentation/blockdev/nbd.rst> for more information,
especially about where to find the server code, which runs in user
space and does not need special kernel support.
@@ -303,7 +303,7 @@ config BLK_DEV_RAM
during the initial install of Linux.
Note that the kernel command line option "ramdisk=XX" is now obsolete.
- For details, read <file:Documentation/blockdev/ramdisk.txt>.
+ For details, read <file:Documentation/blockdev/ramdisk.rst>.
To compile this driver as a module, choose M here: the
module will be called brd. An alias "rd" has been defined
diff --git a/drivers/block/floppy.c b/drivers/block/floppy.c
index 9fb9b312ab6b..af02ca97dcd6 100644
--- a/drivers/block/floppy.c
+++ b/drivers/block/floppy.c
@@ -4424,7 +4424,7 @@ static int __init floppy_setup(char *str)
pr_cont("\n");
} else
DPRINT("botched floppy option\n");
- DPRINT("Read Documentation/blockdev/floppy.txt\n");
+ DPRINT("Read Documentation/blockdev/floppy.rst\n");
return 0;
}
diff --git a/drivers/block/zram/Kconfig b/drivers/block/zram/Kconfig
index 1ffc64770643..e06b99d54816 100644
--- a/drivers/block/zram/Kconfig
+++ b/drivers/block/zram/Kconfig
@@ -12,7 +12,7 @@ config ZRAM
It has several use cases, for example: /tmp storage, use as swap
disks and maybe many more.
- See Documentation/blockdev/zram.txt for more information.
+ See Documentation/blockdev/zram.rst for more information.
config ZRAM_WRITEBACK
bool "Write back incompressible or idle page to backing device"
@@ -26,7 +26,7 @@ config ZRAM_WRITEBACK
With /sys/block/zramX/{idle,writeback}, application could ask
idle page's writeback to the backing device to save in memory.
- See Documentation/blockdev/zram.txt for more information.
+ See Documentation/blockdev/zram.rst for more information.
config ZRAM_MEMORY_TRACKING
bool "Track zRam block status"
@@ -36,4 +36,4 @@ config ZRAM_MEMORY_TRACKING
of zRAM. Admin could see the information via
/sys/kernel/debug/zram/zramX/block_state.
- See Documentation/blockdev/zram.txt for more information.
+ See Documentation/blockdev/zram.rst for more information.
diff --git a/tools/testing/selftests/zram/README b/tools/testing/selftests/zram/README
index 7972cc512408..5fa378391d3b 100644
--- a/tools/testing/selftests/zram/README
+++ b/tools/testing/selftests/zram/README
@@ -37,4 +37,4 @@ Commands required for testing:
- mkfs/ mkfs.ext4
For more information please refer:
-kernel-source-tree/Documentation/blockdev/zram.txt
+kernel-source-tree/Documentation/blockdev/zram.rst
--
2.21.0
^ permalink raw reply related
* [PATCH v1 04/22] docs: thermal: convert to ReST
From: Mauro Carvalho Chehab @ 2019-06-18 21:05 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Amit Daniel Kachhap, Viresh Kumar, Javi Merino,
Kukjin Kim, Krzysztof Kozlowski, Zhang Rui, Eduardo Valentin,
Daniel Lezcano, linux-pm, linux-arm-kernel, linux-samsung-soc,
Arjan van de Ven
In-Reply-To: <cover.1560891322.git.mchehab+samsung@kernel.org>
Rename the thermal documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.
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: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
...pu-cooling-api.txt => cpu-cooling-api.rst} | 39 +-
.../{exynos_thermal => exynos_thermal.rst} | 47 +-
...emulation => exynos_thermal_emulation.rst} | 66 +--
Documentation/thermal/index.rst | 18 +
...el_powerclamp.txt => intel_powerclamp.rst} | 177 +++----
.../{nouveau_thermal => nouveau_thermal.rst} | 54 +-
...ower_allocator.txt => power_allocator.rst} | 140 ++---
.../thermal/{sysfs-api.txt => sysfs-api.rst} | 490 ++++++++++++------
...hermal => x86_pkg_temperature_thermal.rst} | 28 +-
MAINTAINERS | 2 +-
include/linux/thermal.h | 4 +-
11 files changed, 665 insertions(+), 400 deletions(-)
rename Documentation/thermal/{cpu-cooling-api.txt => cpu-cooling-api.rst} (82%)
rename Documentation/thermal/{exynos_thermal => exynos_thermal.rst} (67%)
rename Documentation/thermal/{exynos_thermal_emulation => exynos_thermal_emulation.rst} (36%)
create mode 100644 Documentation/thermal/index.rst
rename Documentation/thermal/{intel_powerclamp.txt => intel_powerclamp.rst} (76%)
rename Documentation/thermal/{nouveau_thermal => nouveau_thermal.rst} (64%)
rename Documentation/thermal/{power_allocator.txt => power_allocator.rst} (74%)
rename Documentation/thermal/{sysfs-api.txt => sysfs-api.rst} (66%)
rename Documentation/thermal/{x86_pkg_temperature_thermal => x86_pkg_temperature_thermal.rst} (80%)
diff --git a/Documentation/thermal/cpu-cooling-api.txt b/Documentation/thermal/cpu-cooling-api.rst
similarity index 82%
rename from Documentation/thermal/cpu-cooling-api.txt
rename to Documentation/thermal/cpu-cooling-api.rst
index 7df567eaea1a..645d914c45a6 100644
--- a/Documentation/thermal/cpu-cooling-api.txt
+++ b/Documentation/thermal/cpu-cooling-api.rst
@@ -1,5 +1,6 @@
+=======================
CPU cooling APIs How To
-===================================
+=======================
Written by Amit Daniel Kachhap <amit.kachhap@linaro.org>
@@ -8,40 +9,54 @@ Updated: 6 Jan 2015
Copyright (c) 2012 Samsung Electronics Co., Ltd(http://www.samsung.com)
0. Introduction
+===============
The generic cpu cooling(freq clipping) provides registration/unregistration APIs
to the caller. The binding of the cooling devices to the trip point is left for
the user. The registration APIs returns the cooling device pointer.
1. cpu cooling APIs
+===================
1.1 cpufreq registration/unregistration APIs
-1.1.1 struct thermal_cooling_device *cpufreq_cooling_register(
- struct cpumask *clip_cpus)
+--------------------------------------------
+
+ ::
+
+ struct thermal_cooling_device
+ *cpufreq_cooling_register(struct cpumask *clip_cpus)
This interface function registers the cpufreq cooling device with the name
"thermal-cpufreq-%x". This api can support multiple instances of cpufreq
cooling devices.
- clip_cpus: cpumask of cpus where the frequency constraints will happen.
+ clip_cpus:
+ cpumask of cpus where the frequency constraints will happen.
-1.1.2 struct thermal_cooling_device *of_cpufreq_cooling_register(
- struct cpufreq_policy *policy)
+ ::
+
+ struct thermal_cooling_device
+ *of_cpufreq_cooling_register(struct cpufreq_policy *policy)
This interface function registers the cpufreq cooling device with
the name "thermal-cpufreq-%x" linking it with a device tree node, in
order to bind it via the thermal DT code. This api can support multiple
instances of cpufreq cooling devices.
- policy: CPUFreq policy.
+ policy:
+ CPUFreq policy.
-1.1.3 void cpufreq_cooling_unregister(struct thermal_cooling_device *cdev)
+
+ ::
+
+ void cpufreq_cooling_unregister(struct thermal_cooling_device *cdev)
This interface function unregisters the "thermal-cpufreq-%x" cooling device.
cdev: Cooling device pointer which has to be unregistered.
2. Power models
+===============
The power API registration functions provide a simple power model for
CPUs. The current power is calculated as dynamic power (static power isn't
@@ -65,9 +80,9 @@ For a given processor implementation the primary factors are:
variation. In pathological cases this variation can be significant,
but typically it is of a much lesser impact than the factors above.
-A high level dynamic power consumption model may then be represented as:
+A high level dynamic power consumption model may then be represented as::
-Pdyn = f(run) * Voltage^2 * Frequency * Utilisation
+ Pdyn = f(run) * Voltage^2 * Frequency * Utilisation
f(run) here represents the described execution behaviour and its
result has a units of Watts/Hz/Volt^2 (this often expressed in
@@ -80,9 +95,9 @@ factors. Therefore, in initial implementation that contribution is
represented as a constant coefficient. This is a simplification
consistent with the relative contribution to overall power variation.
-In this simplified representation our model becomes:
+In this simplified representation our model becomes::
-Pdyn = Capacitance * Voltage^2 * Frequency * Utilisation
+ Pdyn = Capacitance * Voltage^2 * Frequency * Utilisation
Where `capacitance` is a constant that represents an indicative
running time dynamic power coefficient in fundamental units of
diff --git a/Documentation/thermal/exynos_thermal b/Documentation/thermal/exynos_thermal.rst
similarity index 67%
rename from Documentation/thermal/exynos_thermal
rename to Documentation/thermal/exynos_thermal.rst
index 9010c4416967..5bd556566c70 100644
--- a/Documentation/thermal/exynos_thermal
+++ b/Documentation/thermal/exynos_thermal.rst
@@ -1,8 +1,11 @@
+========================
Kernel driver exynos_tmu
-=================
+========================
Supported chips:
+
* ARM SAMSUNG EXYNOS4, EXYNOS5 series of SoC
+
Datasheet: Not publicly available
Authors: Donggeun Kim <dg77.kim@samsung.com>
@@ -19,32 +22,39 @@ Temperature can be taken from the temperature code.
There are three equations converting from temperature to temperature code.
The three equations are:
- 1. Two point trimming
+ 1. Two point trimming::
+
Tc = (T - 25) * (TI2 - TI1) / (85 - 25) + TI1
- 2. One point trimming
+ 2. One point trimming::
+
Tc = T + TI1 - 25
- 3. No trimming
+ 3. No trimming::
+
Tc = T + 50
- Tc: Temperature code, T: Temperature,
- TI1: Trimming info for 25 degree Celsius (stored at TRIMINFO register)
+ Tc:
+ Temperature code, T: Temperature,
+ TI1:
+ Trimming info for 25 degree Celsius (stored at TRIMINFO register)
Temperature code measured at 25 degree Celsius which is unchanged
- TI2: Trimming info for 85 degree Celsius (stored at TRIMINFO register)
+ TI2:
+ Trimming info for 85 degree Celsius (stored at TRIMINFO register)
Temperature code measured at 85 degree Celsius which is unchanged
TMU(Thermal Management Unit) in EXYNOS4/5 generates interrupt
when temperature exceeds pre-defined levels.
The maximum number of configurable threshold is five.
-The threshold levels are defined as follows:
+The threshold levels are defined as follows::
+
Level_0: current temperature > trigger_level_0 + threshold
Level_1: current temperature > trigger_level_1 + threshold
Level_2: current temperature > trigger_level_2 + threshold
Level_3: current temperature > trigger_level_3 + threshold
- The threshold and each trigger_level are set
- through the corresponding registers.
+The threshold and each trigger_level are set
+through the corresponding registers.
When an interrupt occurs, this driver notify kernel thermal framework
with the function exynos_report_trigger.
@@ -54,24 +64,27 @@ it can be used to synchronize the cooling action.
TMU driver description:
-----------------------
-The exynos thermal driver is structured as,
+The exynos thermal driver is structured as::
Kernel Core thermal framework
(thermal_core.c, step_wise.c, cpu_cooling.c)
^
|
|
-TMU configuration data -------> TMU Driver <------> Exynos Core thermal wrapper
-(exynos_tmu_data.c) (exynos_tmu.c) (exynos_thermal_common.c)
-(exynos_tmu_data.h) (exynos_tmu.h) (exynos_thermal_common.h)
+ TMU configuration data -----> TMU Driver <----> Exynos Core thermal wrapper
+ (exynos_tmu_data.c) (exynos_tmu.c) (exynos_thermal_common.c)
+ (exynos_tmu_data.h) (exynos_tmu.h) (exynos_thermal_common.h)
-a) TMU configuration data: This consist of TMU register offsets/bitfields
+a) TMU configuration data:
+ This consist of TMU register offsets/bitfields
described through structure exynos_tmu_registers. Also several
other platform data (struct exynos_tmu_platform_data) members
are used to configure the TMU.
-b) TMU driver: This component initialises the TMU controller and sets different
+b) TMU driver:
+ This component initialises the TMU controller and sets different
thresholds. It invokes core thermal implementation with the call
exynos_report_trigger.
-c) Exynos Core thermal wrapper: This provides 3 wrapper function to use the
+c) Exynos Core thermal wrapper:
+ This provides 3 wrapper function to use the
Kernel core thermal framework. They are exynos_unregister_thermal,
exynos_register_thermal and exynos_report_trigger.
diff --git a/Documentation/thermal/exynos_thermal_emulation b/Documentation/thermal/exynos_thermal_emulation.rst
similarity index 36%
rename from Documentation/thermal/exynos_thermal_emulation
rename to Documentation/thermal/exynos_thermal_emulation.rst
index b15efec6ca28..c21d10838bc5 100644
--- a/Documentation/thermal/exynos_thermal_emulation
+++ b/Documentation/thermal/exynos_thermal_emulation.rst
@@ -1,5 +1,6 @@
-EXYNOS EMULATION MODE
-========================
+=====================
+Exynos Emulation Mode
+=====================
Copyright (C) 2012 Samsung Electronics
@@ -8,46 +9,53 @@ Written by Jonghwa Lee <jonghwa3.lee@samsung.com>
Description
-----------
-Exynos 4x12 (4212, 4412) and 5 series provide emulation mode for thermal management unit.
-Thermal emulation mode supports software debug for TMU's operation. User can set temperature
-manually with software code and TMU will read current temperature from user value not from
-sensor's value.
+Exynos 4x12 (4212, 4412) and 5 series provide emulation mode for thermal
+management unit. Thermal emulation mode supports software debug for
+TMU's operation. User can set temperature manually with software code
+and TMU will read current temperature from user value not from sensor's
+value.
-Enabling CONFIG_THERMAL_EMULATION option will make this support available.
-When it's enabled, sysfs node will be created as
+Enabling CONFIG_THERMAL_EMULATION option will make this support
+available. When it's enabled, sysfs node will be created as
/sys/devices/virtual/thermal/thermal_zone'zone id'/emul_temp.
-The sysfs node, 'emul_node', will contain value 0 for the initial state. When you input any
-temperature you want to update to sysfs node, it automatically enable emulation mode and
-current temperature will be changed into it.
-(Exynos also supports user changeable delay time which would be used to delay of
- changing temperature. However, this node only uses same delay of real sensing time, 938us.)
+The sysfs node, 'emul_node', will contain value 0 for the initial state.
+When you input any temperature you want to update to sysfs node, it
+automatically enable emulation mode and current temperature will be
+changed into it.
-Exynos emulation mode requires synchronous of value changing and enabling. It means when you
-want to update the any value of delay or next temperature, then you have to enable emulation
-mode at the same time. (Or you have to keep the mode enabling.) If you don't, it fails to
-change the value to updated one and just use last succeessful value repeatedly. That's why
-this node gives users the right to change termerpature only. Just one interface makes it more
-simply to use.
+(Exynos also supports user changeable delay time which would be used to
+delay of changing temperature. However, this node only uses same delay
+of real sensing time, 938us.)
+
+Exynos emulation mode requires synchronous of value changing and
+enabling. It means when you want to update the any value of delay or
+next temperature, then you have to enable emulation mode at the same
+time. (Or you have to keep the mode enabling.) If you don't, it fails to
+change the value to updated one and just use last succeessful value
+repeatedly. That's why this node gives users the right to change
+termerpature only. Just one interface makes it more simply to use.
Disabling emulation mode only requires writing value 0 to sysfs node.
+::
-TEMP 120 |
+
+ TEMP 120 |
|
100 |
|
80 |
- | +-----------
- 60 | | |
- | +-------------| |
+ | +-----------
+ 60 | | |
+ | +-------------| |
40 | | | |
- | | | |
- 20 | | | +----------
- | | | | |
+ | | | |
+ 20 | | | +----------
+ | | | | |
0 |______________|_____________|__________|__________|_________
- A A A A TIME
+ A A A A TIME
|<----->| |<----->| |<----->| |
| 938us | | | | | |
-emulation : 0 50 | 70 | 20 | 0
-current temp : sensor 50 70 20 sensor
+ emulation : 0 50 | 70 | 20 | 0
+ current temp: sensor 50 70 20 sensor
diff --git a/Documentation/thermal/index.rst b/Documentation/thermal/index.rst
new file mode 100644
index 000000000000..8c1c00146cad
--- /dev/null
+++ b/Documentation/thermal/index.rst
@@ -0,0 +1,18 @@
+:orphan:
+
+=======
+Thermal
+=======
+
+.. toctree::
+ :maxdepth: 1
+
+ cpu-cooling-api
+ sysfs-api
+ power_allocator
+
+ exynos_thermal
+ exynos_thermal_emulation
+ intel_powerclamp
+ nouveau_thermal
+ x86_pkg_temperature_thermal
diff --git a/Documentation/thermal/intel_powerclamp.txt b/Documentation/thermal/intel_powerclamp.rst
similarity index 76%
rename from Documentation/thermal/intel_powerclamp.txt
rename to Documentation/thermal/intel_powerclamp.rst
index b5df21168fbc..3f6dfb0b3ea6 100644
--- a/Documentation/thermal/intel_powerclamp.txt
+++ b/Documentation/thermal/intel_powerclamp.rst
@@ -1,10 +1,13 @@
- =======================
- INTEL POWERCLAMP DRIVER
- =======================
-By: Arjan van de Ven <arjan@linux.intel.com>
- Jacob Pan <jacob.jun.pan@linux.intel.com>
+=======================
+Intel Powerclamp Driver
+=======================
+
+By:
+ - Arjan van de Ven <arjan@linux.intel.com>
+ - Jacob Pan <jacob.jun.pan@linux.intel.com>
+
+.. Contents:
-Contents:
(*) Introduction
- Goals and Objectives
@@ -23,7 +26,6 @@ Contents:
- Generic Thermal Layer (sysfs)
- Kernel APIs (TBD)
-============
INTRODUCTION
============
@@ -47,7 +49,6 @@ scalability, and user experience. In many cases, clear advantage is
shown over taking the CPU offline or modulating the CPU clock.
-===================
THEORY OF OPERATION
===================
@@ -57,11 +58,12 @@ Idle Injection
On modern Intel processors (Nehalem or later), package level C-state
residency is available in MSRs, thus also available to the kernel.
-These MSRs are:
- #define MSR_PKG_C2_RESIDENCY 0x60D
- #define MSR_PKG_C3_RESIDENCY 0x3F8
- #define MSR_PKG_C6_RESIDENCY 0x3F9
- #define MSR_PKG_C7_RESIDENCY 0x3FA
+These MSRs are::
+
+ #define MSR_PKG_C2_RESIDENCY 0x60D
+ #define MSR_PKG_C3_RESIDENCY 0x3F8
+ #define MSR_PKG_C6_RESIDENCY 0x3F9
+ #define MSR_PKG_C7_RESIDENCY 0x3FA
If the kernel can also inject idle time to the system, then a
closed-loop control system can be established that manages package
@@ -96,19 +98,21 @@ are not masked. Tests show that the extra wakeups from scheduler tick
have a dramatic impact on the effectiveness of the powerclamp driver
on large scale systems (Westmere system with 80 processors).
-CPU0
- ____________ ____________
-kidle_inject/0 | sleep | mwait | sleep |
- _________| |________| |_______
- duration
-CPU1
- ____________ ____________
-kidle_inject/1 | sleep | mwait | sleep |
- _________| |________| |_______
- ^
- |
- |
- roundup(jiffies, interval)
+::
+
+ CPU0
+ ____________ ____________
+ kidle_inject/0 | sleep | mwait | sleep |
+ _________| |________| |_______
+ duration
+ CPU1
+ ____________ ____________
+ kidle_inject/1 | sleep | mwait | sleep |
+ _________| |________| |_______
+ ^
+ |
+ |
+ roundup(jiffies, interval)
Only one CPU is allowed to collect statistics and update global
control parameters. This CPU is referred to as the controlling CPU in
@@ -148,7 +152,7 @@ b) determine the amount of compensation needed at each target ratio
Compensation to each target ratio consists of two parts:
- a) steady state error compensation
+ a) steady state error compensation
This is to offset the error occurring when the system can
enter idle without extra wakeups (such as external interrupts).
@@ -158,41 +162,42 @@ Compensation to each target ratio consists of two parts:
slowing down CPU activities.
A debugfs file is provided for the user to examine compensation
-progress and results, such as on a Westmere system.
-[jacob@nex01 ~]$ cat
-/sys/kernel/debug/intel_powerclamp/powerclamp_calib
-controlling cpu: 0
-pct confidence steady dynamic (compensation)
-0 0 0 0
-1 1 0 0
-2 1 1 0
-3 3 1 0
-4 3 1 0
-5 3 1 0
-6 3 1 0
-7 3 1 0
-8 3 1 0
-...
-30 3 2 0
-31 3 2 0
-32 3 1 0
-33 3 2 0
-34 3 1 0
-35 3 2 0
-36 3 1 0
-37 3 2 0
-38 3 1 0
-39 3 2 0
-40 3 3 0
-41 3 1 0
-42 3 2 0
-43 3 1 0
-44 3 1 0
-45 3 2 0
-46 3 3 0
-47 3 0 0
-48 3 2 0
-49 3 3 0
+progress and results, such as on a Westmere system::
+
+ [jacob@nex01 ~]$ cat
+ /sys/kernel/debug/intel_powerclamp/powerclamp_calib
+ controlling cpu: 0
+ pct confidence steady dynamic (compensation)
+ 0 0 0 0
+ 1 1 0 0
+ 2 1 1 0
+ 3 3 1 0
+ 4 3 1 0
+ 5 3 1 0
+ 6 3 1 0
+ 7 3 1 0
+ 8 3 1 0
+ ...
+ 30 3 2 0
+ 31 3 2 0
+ 32 3 1 0
+ 33 3 2 0
+ 34 3 1 0
+ 35 3 2 0
+ 36 3 1 0
+ 37 3 2 0
+ 38 3 1 0
+ 39 3 2 0
+ 40 3 3 0
+ 41 3 1 0
+ 42 3 2 0
+ 43 3 1 0
+ 44 3 1 0
+ 45 3 2 0
+ 46 3 3 0
+ 47 3 0 0
+ 48 3 2 0
+ 49 3 3 0
Calibration occurs during runtime. No offline method is available.
Steady state compensation is used only when confidence levels of all
@@ -217,9 +222,8 @@ keeps track of clamping kernel threads, even after they are migrated
to other CPUs, after a CPU offline event.
-=====================
Performance Analysis
-=====================
+====================
This section describes the general performance data collected on
multiple systems, including Westmere (80P) and Ivy Bridge (4P, 8P).
@@ -257,16 +261,15 @@ achieve up to 40% better performance per watt. (measured by a spin
counter summed over per CPU counting threads spawned for all running
CPUs).
-====================
Usage and Interfaces
====================
The powerclamp driver is registered to the generic thermal layer as a
-cooling device. Currently, it’s not bound to any thermal zones.
+cooling device. Currently, it’s not bound to any thermal zones::
-jacob@chromoly:/sys/class/thermal/cooling_device14$ grep . *
-cur_state:0
-max_state:50
-type:intel_powerclamp
+ jacob@chromoly:/sys/class/thermal/cooling_device14$ grep . *
+ cur_state:0
+ max_state:50
+ type:intel_powerclamp
cur_state allows user to set the desired idle percentage. Writing 0 to
cur_state will stop idle injection. Writing a value between 1 and
@@ -278,9 +281,9 @@ cur_state returns value -1 instead of 0 which is to avoid confusing
100% busy state with the disabled state.
Example usage:
-- To inject 25% idle time
-$ sudo sh -c "echo 25 > /sys/class/thermal/cooling_device80/cur_state
-"
+- To inject 25% idle time::
+
+ $ sudo sh -c "echo 25 > /sys/class/thermal/cooling_device80/cur_state
If the system is not busy and has more than 25% idle time already,
then the powerclamp driver will not start idle injection. Using Top
@@ -292,23 +295,23 @@ idle time is accounted as normal idle in that common code path is
taken as the idle task.
In this example, 24.1% idle is shown. This helps the system admin or
-user determine the cause of slowdown, when a powerclamp driver is in action.
+user determine the cause of slowdown, when a powerclamp driver is in action::
-Tasks: 197 total, 1 running, 196 sleeping, 0 stopped, 0 zombie
-Cpu(s): 71.2%us, 4.7%sy, 0.0%ni, 24.1%id, 0.0%wa, 0.0%hi, 0.0%si, 0.0%st
-Mem: 3943228k total, 1689632k used, 2253596k free, 74960k buffers
-Swap: 4087804k total, 0k used, 4087804k free, 945336k cached
+ Tasks: 197 total, 1 running, 196 sleeping, 0 stopped, 0 zombie
+ Cpu(s): 71.2%us, 4.7%sy, 0.0%ni, 24.1%id, 0.0%wa, 0.0%hi, 0.0%si, 0.0%st
+ Mem: 3943228k total, 1689632k used, 2253596k free, 74960k buffers
+ Swap: 4087804k total, 0k used, 4087804k free, 945336k cached
- PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND
- 3352 jacob 20 0 262m 644 428 S 286 0.0 0:17.16 spin
- 3341 root -51 0 0 0 0 D 25 0.0 0:01.62 kidle_inject/0
- 3344 root -51 0 0 0 0 D 25 0.0 0:01.60 kidle_inject/3
- 3342 root -51 0 0 0 0 D 25 0.0 0:01.61 kidle_inject/1
- 3343 root -51 0 0 0 0 D 25 0.0 0:01.60 kidle_inject/2
- 2935 jacob 20 0 696m 125m 35m S 5 3.3 0:31.11 firefox
- 1546 root 20 0 158m 20m 6640 S 3 0.5 0:26.97 Xorg
- 2100 jacob 20 0 1223m 88m 30m S 3 2.3 0:23.68 compiz
+ PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND
+ 3352 jacob 20 0 262m 644 428 S 286 0.0 0:17.16 spin
+ 3341 root -51 0 0 0 0 D 25 0.0 0:01.62 kidle_inject/0
+ 3344 root -51 0 0 0 0 D 25 0.0 0:01.60 kidle_inject/3
+ 3342 root -51 0 0 0 0 D 25 0.0 0:01.61 kidle_inject/1
+ 3343 root -51 0 0 0 0 D 25 0.0 0:01.60 kidle_inject/2
+ 2935 jacob 20 0 696m 125m 35m S 5 3.3 0:31.11 firefox
+ 1546 root 20 0 158m 20m 6640 S 3 0.5 0:26.97 Xorg
+ 2100 jacob 20 0 1223m 88m 30m S 3 2.3 0:23.68 compiz
Tests have shown that by using the powerclamp driver as a cooling
device, a PID based userspace thermal controller can manage to
diff --git a/Documentation/thermal/nouveau_thermal b/Documentation/thermal/nouveau_thermal.rst
similarity index 64%
rename from Documentation/thermal/nouveau_thermal
rename to Documentation/thermal/nouveau_thermal.rst
index 6e17a11efcb0..37255fd6735d 100644
--- a/Documentation/thermal/nouveau_thermal
+++ b/Documentation/thermal/nouveau_thermal.rst
@@ -1,13 +1,15 @@
+=====================
Kernel driver nouveau
-===================
+=====================
Supported chips:
+
* NV43+
Authors: Martin Peres (mupuf) <martin.peres@free.fr>
Description
----------
+-----------
This driver allows to read the GPU core temperature, drive the GPU fan and
set temperature alarms.
@@ -19,20 +21,25 @@ interface is likely not to work. This document may then not cover your situation
entirely.
Temperature management
---------------------
+----------------------
Temperature is exposed under as a read-only HWMON attribute temp1_input.
In order to protect the GPU from overheating, Nouveau supports 4 configurable
temperature thresholds:
- * Fan_boost: Fan speed is set to 100% when reaching this temperature;
- * Downclock: The GPU will be downclocked to reduce its power dissipation;
- * Critical: The GPU is put on hold to further lower power dissipation;
- * Shutdown: Shut the computer down to protect your GPU.
+ * Fan_boost:
+ Fan speed is set to 100% when reaching this temperature;
+ * Downclock:
+ The GPU will be downclocked to reduce its power dissipation;
+ * Critical:
+ The GPU is put on hold to further lower power dissipation;
+ * Shutdown:
+ Shut the computer down to protect your GPU.
-WARNING: Some of these thresholds may not be used by Nouveau depending
-on your chipset.
+WARNING:
+ Some of these thresholds may not be used by Nouveau depending
+ on your chipset.
The default value for these thresholds comes from the GPU's vbios. These
thresholds can be configured thanks to the following HWMON attributes:
@@ -46,19 +53,24 @@ NOTE: Remember that the values are stored as milli degrees Celsius. Don't forget
to multiply!
Fan management
-------------
+--------------
Not all cards have a drivable fan. If you do, then the following HWMON
attributes should be available:
- * pwm1_enable: Current fan management mode (NONE, MANUAL or AUTO);
- * pwm1: Current PWM value (power percentage);
- * pwm1_min: The minimum PWM speed allowed;
- * pwm1_max: The maximum PWM speed allowed (bypassed when hitting Fan_boost);
+ * pwm1_enable:
+ Current fan management mode (NONE, MANUAL or AUTO);
+ * pwm1:
+ Current PWM value (power percentage);
+ * pwm1_min:
+ The minimum PWM speed allowed;
+ * pwm1_max:
+ The maximum PWM speed allowed (bypassed when hitting Fan_boost);
You may also have the following attribute:
- * fan1_input: Speed in RPM of your fan.
+ * fan1_input:
+ Speed in RPM of your fan.
Your fan can be driven in different modes:
@@ -66,14 +78,16 @@ Your fan can be driven in different modes:
* 1: The fan can be driven in manual (use pwm1 to change the speed);
* 2; The fan is driven automatically depending on the temperature.
-NOTE: Be sure to use the manual mode if you want to drive the fan speed manually
+NOTE:
+ Be sure to use the manual mode if you want to drive the fan speed manually
-NOTE2: When operating in manual mode outside the vbios-defined
-[PWM_min, PWM_max] range, the reported fan speed (RPM) may not be accurate
-depending on your hardware.
+NOTE2:
+ When operating in manual mode outside the vbios-defined
+ [PWM_min, PWM_max] range, the reported fan speed (RPM) may not be accurate
+ depending on your hardware.
Bug reports
----------
+-----------
Thermal management on Nouveau is new and may not work on all cards. If you have
inquiries, please ping mupuf on IRC (#nouveau, freenode).
diff --git a/Documentation/thermal/power_allocator.txt b/Documentation/thermal/power_allocator.rst
similarity index 74%
rename from Documentation/thermal/power_allocator.txt
rename to Documentation/thermal/power_allocator.rst
index 9fb0ff06dca9..67b6a3297238 100644
--- a/Documentation/thermal/power_allocator.txt
+++ b/Documentation/thermal/power_allocator.rst
@@ -1,3 +1,4 @@
+=================================
Power allocator governor tunables
=================================
@@ -25,36 +26,36 @@ temperature as the control input and power as the controlled output:
P_max = k_p * e + k_i * err_integral + k_d * diff_err + sustainable_power
where
- e = desired_temperature - current_temperature
- err_integral is the sum of previous errors
- diff_err = e - previous_error
+ - e = desired_temperature - current_temperature
+ - err_integral is the sum of previous errors
+ - diff_err = e - previous_error
-It is similar to the one depicted below:
+It is similar to the one depicted below::
- k_d
- |
-current_temp |
- | v
- | +----------+ +---+
- | +----->| diff_err |-->| X |------+
- | | +----------+ +---+ |
- | | | tdp actor
- | | k_i | | get_requested_power()
- | | | | | | |
- | | | | | | | ...
- v | v v v v v
- +---+ | +-------+ +---+ +---+ +---+ +----------+
- | S |-------+----->| sum e |----->| X |--->| S |-->| S |-->|power |
- +---+ | +-------+ +---+ +---+ +---+ |allocation|
- ^ | ^ +----------+
- | | | | |
- | | +---+ | | |
- | +------->| X |-------------------+ v v
- | +---+ granted performance
-desired_temperature ^
- |
- |
- k_po/k_pu
+ k_d
+ |
+ current_temp |
+ | v
+ | +----------+ +---+
+ | +----->| diff_err |-->| X |------+
+ | | +----------+ +---+ |
+ | | | tdp actor
+ | | k_i | | get_requested_power()
+ | | | | | | |
+ | | | | | | | ...
+ v | v v v v v
+ +---+ | +-------+ +---+ +---+ +---+ +----------+
+ | S |-----+----->| sum e |----->| X |--->| S |-->| S |-->|power |
+ +---+ | +-------+ +---+ +---+ +---+ |allocation|
+ ^ | ^ +----------+
+ | | | | |
+ | | +---+ | | |
+ | +------->| X |-------------------+ v v
+ | +---+ granted performance
+ desired_temperature ^
+ |
+ |
+ k_po/k_pu
Sustainable power
-----------------
@@ -73,7 +74,7 @@ is typically 2000mW, while on a 10" tablet is around 4500mW (may vary
depending on screen size).
If you are using device tree, do add it as a property of the
-thermal-zone. For example:
+thermal-zone. For example::
thermal-zones {
soc_thermal {
@@ -85,7 +86,7 @@ thermal-zone. For example:
Instead, if the thermal zone is registered from the platform code, pass a
`thermal_zone_params` that has a `sustainable_power`. If no
`thermal_zone_params` were being passed, then something like below
-will suffice:
+will suffice::
static const struct thermal_zone_params tz_params = {
.sustainable_power = 3500,
@@ -112,18 +113,18 @@ available capacity at a low temperature. On the other hand, a high
value of `k_pu` will result in the governor granting very high power
while temperature is low, and may lead to temperature overshooting.
-The default value for `k_pu` is:
+The default value for `k_pu` is::
2 * sustainable_power / (desired_temperature - switch_on_temp)
This means that at `switch_on_temp` the output of the controller's
proportional term will be 2 * `sustainable_power`. The default value
-for `k_po` is:
+for `k_po` is::
sustainable_power / (desired_temperature - switch_on_temp)
Focusing on the proportional and feed forward values of the PID
-controller equation we have:
+controller equation we have::
P_max = k_p * e + sustainable_power
@@ -134,21 +135,23 @@ is the desired one, then the proportional component is zero and
thermal equilibrium under constant load. `sustainable_power` is only
an estimate, which is the reason for closed-loop control such as this.
-Expanding `k_pu` we get:
+Expanding `k_pu` we get::
+
P_max = 2 * sustainable_power * (T_set - T) / (T_set - T_on) +
- sustainable_power
+ sustainable_power
-where
- T_set is the desired temperature
- T is the current temperature
- T_on is the switch on temperature
+where:
+
+ - T_set is the desired temperature
+ - T is the current temperature
+ - T_on is the switch on temperature
When the current temperature is the switch_on temperature, the above
-formula becomes:
+formula becomes::
P_max = 2 * sustainable_power * (T_set - T_on) / (T_set - T_on) +
- sustainable_power = 2 * sustainable_power + sustainable_power =
- 3 * sustainable_power
+ sustainable_power = 2 * sustainable_power + sustainable_power =
+ 3 * sustainable_power
Therefore, the proportional term alone linearly decreases power from
3 * `sustainable_power` to `sustainable_power` as the temperature
@@ -178,11 +181,18 @@ Cooling device power API
Cooling devices controlled by this governor must supply the additional
"power" API in their `cooling_device_ops`. It consists on three ops:
-1. int get_requested_power(struct thermal_cooling_device *cdev,
- struct thermal_zone_device *tz, u32 *power);
-@cdev: The `struct thermal_cooling_device` pointer
-@tz: thermal zone in which we are currently operating
-@power: pointer in which to store the calculated power
+1. ::
+
+ int get_requested_power(struct thermal_cooling_device *cdev,
+ struct thermal_zone_device *tz, u32 *power);
+
+
+@cdev:
+ The `struct thermal_cooling_device` pointer
+@tz:
+ thermal zone in which we are currently operating
+@power:
+ pointer in which to store the calculated power
`get_requested_power()` calculates the power requested by the device
in milliwatts and stores it in @power . It should return 0 on
@@ -190,23 +200,37 @@ success, -E* on failure. This is currently used by the power
allocator governor to calculate how much power to give to each cooling
device.
-2. int state2power(struct thermal_cooling_device *cdev, struct
- thermal_zone_device *tz, unsigned long state, u32 *power);
-@cdev: The `struct thermal_cooling_device` pointer
-@tz: thermal zone in which we are currently operating
-@state: A cooling device state
-@power: pointer in which to store the equivalent power
+2. ::
+
+ int state2power(struct thermal_cooling_device *cdev, struct
+ thermal_zone_device *tz, unsigned long state,
+ u32 *power);
+
+@cdev:
+ The `struct thermal_cooling_device` pointer
+@tz:
+ thermal zone in which we are currently operating
+@state:
+ A cooling device state
+@power:
+ pointer in which to store the equivalent power
Convert cooling device state @state into power consumption in
milliwatts and store it in @power. It should return 0 on success, -E*
on failure. This is currently used by thermal core to calculate the
maximum power that an actor can consume.
-3. int power2state(struct thermal_cooling_device *cdev, u32 power,
- unsigned long *state);
-@cdev: The `struct thermal_cooling_device` pointer
-@power: power in milliwatts
-@state: pointer in which to store the resulting state
+3. ::
+
+ int power2state(struct thermal_cooling_device *cdev, u32 power,
+ unsigned long *state);
+
+@cdev:
+ The `struct thermal_cooling_device` pointer
+@power:
+ power in milliwatts
+@state:
+ pointer in which to store the resulting state
Calculate a cooling device state that would make the device consume at
most @power mW and store it in @state. It should return 0 on success,
diff --git a/Documentation/thermal/sysfs-api.txt b/Documentation/thermal/sysfs-api.rst
similarity index 66%
rename from Documentation/thermal/sysfs-api.txt
rename to Documentation/thermal/sysfs-api.rst
index c3fa500df92c..e4930761d3e5 100644
--- a/Documentation/thermal/sysfs-api.txt
+++ b/Documentation/thermal/sysfs-api.rst
@@ -1,3 +1,4 @@
+===================================
Generic Thermal Sysfs driver How To
===================================
@@ -9,6 +10,7 @@ Copyright (c) 2008 Intel Corporation
0. Introduction
+===============
The generic thermal sysfs provides a set of interfaces for thermal zone
devices (sensors) and thermal cooling devices (fan, processor...) to register
@@ -25,59 +27,90 @@ An intelligent thermal management application can make decisions based on
inputs from thermal zone attributes (the current temperature and trip point
temperature) and throttle appropriate devices.
-[0-*] denotes any positive number starting from 0
-[1-*] denotes any positive number starting from 1
+- `[0-*]` denotes any positive number starting from 0
+- `[1-*]` denotes any positive number starting from 1
1. thermal sysfs driver interface functions
+===========================================
1.1 thermal zone device interface
-1.1.1 struct thermal_zone_device *thermal_zone_device_register(char *type,
- int trips, int mask, void *devdata,
- struct thermal_zone_device_ops *ops,
- const struct thermal_zone_params *tzp,
- int passive_delay, int polling_delay))
+---------------------------------
+
+ ::
+
+ struct thermal_zone_device
+ *thermal_zone_device_register(char *type,
+ int trips, int mask, void *devdata,
+ struct thermal_zone_device_ops *ops,
+ const struct thermal_zone_params *tzp,
+ int passive_delay, int polling_delay))
This interface function adds a new thermal zone device (sensor) to
- /sys/class/thermal folder as thermal_zone[0-*]. It tries to bind all the
+ /sys/class/thermal folder as `thermal_zone[0-*]`. It tries to bind all the
thermal cooling devices registered at the same time.
- type: the thermal zone type.
- trips: the total number of trip points this thermal zone supports.
- mask: Bit string: If 'n'th bit is set, then trip point 'n' is writeable.
- devdata: device private data
- ops: thermal zone device call-backs.
- .bind: bind the thermal zone device with a thermal cooling device.
- .unbind: unbind the thermal zone device with a thermal cooling device.
- .get_temp: get the current temperature of the thermal zone.
- .set_trips: set the trip points window. Whenever the current temperature
+ type:
+ the thermal zone type.
+ trips:
+ the total number of trip points this thermal zone supports.
+ mask:
+ Bit string: If 'n'th bit is set, then trip point 'n' is writeable.
+ devdata:
+ device private data
+ ops:
+ thermal zone device call-backs.
+
+ .bind:
+ bind the thermal zone device with a thermal cooling device.
+ .unbind:
+ unbind the thermal zone device with a thermal cooling device.
+ .get_temp:
+ get the current temperature of the thermal zone.
+ .set_trips:
+ set the trip points window. Whenever the current temperature
is updated, the trip points immediately below and above the
current temperature are found.
- .get_mode: get the current mode (enabled/disabled) of the thermal zone.
- - "enabled" means the kernel thermal management is enabled.
- - "disabled" will prevent kernel thermal driver action upon trip points
- so that user applications can take charge of thermal management.
- .set_mode: set the mode (enabled/disabled) of the thermal zone.
- .get_trip_type: get the type of certain trip point.
- .get_trip_temp: get the temperature above which the certain trip point
+ .get_mode:
+ get the current mode (enabled/disabled) of the thermal zone.
+
+ - "enabled" means the kernel thermal management is
+ enabled.
+ - "disabled" will prevent kernel thermal driver action
+ upon trip points so that user applications can take
+ charge of thermal management.
+ .set_mode:
+ set the mode (enabled/disabled) of the thermal zone.
+ .get_trip_type:
+ get the type of certain trip point.
+ .get_trip_temp:
+ get the temperature above which the certain trip point
will be fired.
- .set_emul_temp: set the emulation temperature which helps in debugging
+ .set_emul_temp:
+ set the emulation temperature which helps in debugging
different threshold temperature points.
- tzp: thermal zone platform parameters.
- passive_delay: number of milliseconds to wait between polls when
+ tzp:
+ thermal zone platform parameters.
+ passive_delay:
+ number of milliseconds to wait between polls when
performing passive cooling.
- polling_delay: number of milliseconds to wait between polls when checking
+ polling_delay:
+ number of milliseconds to wait between polls when checking
whether trip points have been crossed (0 for interrupt driven systems).
+ ::
-1.1.2 void thermal_zone_device_unregister(struct thermal_zone_device *tz)
+ void thermal_zone_device_unregister(struct thermal_zone_device *tz)
This interface function removes the thermal zone device.
It deletes the corresponding entry from /sys/class/thermal folder and
unbinds all the thermal cooling devices it uses.
-1.1.3 struct thermal_zone_device *thermal_zone_of_sensor_register(
- struct device *dev, int sensor_id, void *data,
- const struct thermal_zone_of_device_ops *ops)
+ ::
+
+ struct thermal_zone_device
+ *thermal_zone_of_sensor_register(struct device *dev, int sensor_id,
+ void *data,
+ const struct thermal_zone_of_device_ops *ops)
This interface adds a new sensor to a DT thermal zone.
This function will search the list of thermal zones described in
@@ -87,25 +120,33 @@ temperature) and throttle appropriate devices.
thermal zone device.
The parameters for this interface are:
- dev: Device node of sensor containing valid node pointer in
+
+ dev:
+ Device node of sensor containing valid node pointer in
dev->of_node.
- sensor_id: a sensor identifier, in case the sensor IP has more
+ sensor_id:
+ a sensor identifier, in case the sensor IP has more
than one sensors
- data: a private pointer (owned by the caller) that will be
+ data:
+ a private pointer (owned by the caller) that will be
passed back, when a temperature reading is needed.
- ops: struct thermal_zone_of_device_ops *.
+ ops:
+ `struct thermal_zone_of_device_ops *`.
- get_temp: a pointer to a function that reads the
+ ============== =======================================
+ get_temp a pointer to a function that reads the
sensor temperature. This is mandatory
callback provided by sensor driver.
- set_trips: a pointer to a function that sets a
+ set_trips a pointer to a function that sets a
temperature window. When this window is
left the driver must inform the thermal
core via thermal_zone_device_update.
- get_trend: a pointer to a function that reads the
+ get_trend a pointer to a function that reads the
sensor temperature trend.
- set_emul_temp: a pointer to a function that sets
+ set_emul_temp a pointer to a function that sets
sensor emulated temperature.
+ ============== =======================================
+
The thermal zone temperature is provided by the get_temp() function
pointer of thermal_zone_of_device_ops. When called, it will
have the private pointer @data back.
@@ -114,8 +155,10 @@ temperature) and throttle appropriate devices.
handle. Caller should check the return handle with IS_ERR() for finding
whether success or not.
-1.1.4 void thermal_zone_of_sensor_unregister(struct device *dev,
- struct thermal_zone_device *tzd)
+ ::
+
+ void thermal_zone_of_sensor_unregister(struct device *dev,
+ struct thermal_zone_device *tzd)
This interface unregisters a sensor from a DT thermal zone which was
successfully added by interface thermal_zone_of_sensor_register().
@@ -124,21 +167,29 @@ temperature) and throttle appropriate devices.
interface. It will also silent the zone by remove the .get_temp() and
get_trend() thermal zone device callbacks.
-1.1.5 struct thermal_zone_device *devm_thermal_zone_of_sensor_register(
- struct device *dev, int sensor_id,
- void *data, const struct thermal_zone_of_device_ops *ops)
+ ::
+
+ struct thermal_zone_device
+ *devm_thermal_zone_of_sensor_register(struct device *dev,
+ int sensor_id,
+ void *data,
+ const struct thermal_zone_of_device_ops *ops)
This interface is resource managed version of
thermal_zone_of_sensor_register().
+
All details of thermal_zone_of_sensor_register() described in
section 1.1.3 is applicable here.
+
The benefit of using this interface to register sensor is that it
is not require to explicitly call thermal_zone_of_sensor_unregister()
in error path or during driver unbinding as this is done by driver
resource manager.
-1.1.6 void devm_thermal_zone_of_sensor_unregister(struct device *dev,
- struct thermal_zone_device *tzd)
+ ::
+
+ void devm_thermal_zone_of_sensor_unregister(struct device *dev,
+ struct thermal_zone_device *tzd)
This interface is resource managed version of
thermal_zone_of_sensor_unregister().
@@ -147,123 +198,186 @@ temperature) and throttle appropriate devices.
Normally this function will not need to be called and the resource
management code will ensure that the resource is freed.
-1.1.7 int thermal_zone_get_slope(struct thermal_zone_device *tz)
+ ::
+
+ int thermal_zone_get_slope(struct thermal_zone_device *tz)
This interface is used to read the slope attribute value
for the thermal zone device, which might be useful for platform
drivers for temperature calculations.
-1.1.8 int thermal_zone_get_offset(struct thermal_zone_device *tz)
+ ::
+
+ int thermal_zone_get_offset(struct thermal_zone_device *tz)
This interface is used to read the offset attribute value
for the thermal zone device, which might be useful for platform
drivers for temperature calculations.
1.2 thermal cooling device interface
-1.2.1 struct thermal_cooling_device *thermal_cooling_device_register(char *name,
- void *devdata, struct thermal_cooling_device_ops *)
+------------------------------------
+
+
+ ::
+
+ struct thermal_cooling_device
+ *thermal_cooling_device_register(char *name,
+ void *devdata, struct thermal_cooling_device_ops *)
This interface function adds a new thermal cooling device (fan/processor/...)
- to /sys/class/thermal/ folder as cooling_device[0-*]. It tries to bind itself
+ to /sys/class/thermal/ folder as `cooling_device[0-*]`. It tries to bind itself
to all the thermal zone devices registered at the same time.
- name: the cooling device name.
- devdata: device private data.
- ops: thermal cooling devices call-backs.
- .get_max_state: get the Maximum throttle state of the cooling device.
- .get_cur_state: get the Currently requested throttle state of the cooling device.
- .set_cur_state: set the Current throttle state of the cooling device.
-
-1.2.2 void thermal_cooling_device_unregister(struct thermal_cooling_device *cdev)
+
+ name:
+ the cooling device name.
+ devdata:
+ device private data.
+ ops:
+ thermal cooling devices call-backs.
+
+ .get_max_state:
+ get the Maximum throttle state of the cooling device.
+ .get_cur_state:
+ get the Currently requested throttle state of the
+ cooling device.
+ .set_cur_state:
+ set the Current throttle state of the cooling device.
+
+ ::
+
+ void thermal_cooling_device_unregister(struct thermal_cooling_device *cdev)
This interface function removes the thermal cooling device.
It deletes the corresponding entry from /sys/class/thermal folder and
unbinds itself from all the thermal zone devices using it.
1.3 interface for binding a thermal zone device with a thermal cooling device
-1.3.1 int thermal_zone_bind_cooling_device(struct thermal_zone_device *tz,
- int trip, struct thermal_cooling_device *cdev,
- unsigned long upper, unsigned long lower, unsigned int weight);
+-----------------------------------------------------------------------------
+
+ ::
+
+ int thermal_zone_bind_cooling_device(struct thermal_zone_device *tz,
+ int trip, struct thermal_cooling_device *cdev,
+ unsigned long upper, unsigned long lower, unsigned int weight);
This interface function binds a thermal cooling device to a particular trip
point of a thermal zone device.
+
This function is usually called in the thermal zone device .bind callback.
- tz: the thermal zone device
- cdev: thermal cooling device
- trip: indicates which trip point in this thermal zone the cooling device
- is associated with.
- upper:the Maximum cooling state for this trip point.
- THERMAL_NO_LIMIT means no upper limit,
+
+ tz:
+ the thermal zone device
+ cdev:
+ thermal cooling device
+ trip:
+ indicates which trip point in this thermal zone the cooling device
+ is associated with.
+ upper:
+ the Maximum cooling state for this trip point.
+ THERMAL_NO_LIMIT means no upper limit,
and the cooling device can be in max_state.
- lower:the Minimum cooling state can be used for this trip point.
- THERMAL_NO_LIMIT means no lower limit,
+ lower:
+ the Minimum cooling state can be used for this trip point.
+ THERMAL_NO_LIMIT means no lower limit,
and the cooling device can be in cooling state 0.
- weight: the influence of this cooling device in this thermal
- zone. See 1.4.1 below for more information.
+ weight:
+ the influence of this cooling device in this thermal
+ zone. See 1.4.1 below for more information.
-1.3.2 int thermal_zone_unbind_cooling_device(struct thermal_zone_device *tz,
- int trip, struct thermal_cooling_device *cdev);
+ ::
+
+ int thermal_zone_unbind_cooling_device(struct thermal_zone_device *tz,
+ int trip, struct thermal_cooling_device *cdev);
This interface function unbinds a thermal cooling device from a particular
trip point of a thermal zone device. This function is usually called in
the thermal zone device .unbind callback.
- tz: the thermal zone device
- cdev: thermal cooling device
- trip: indicates which trip point in this thermal zone the cooling device
- is associated with.
+
+ tz:
+ the thermal zone device
+ cdev:
+ thermal cooling device
+ trip:
+ indicates which trip point in this thermal zone the cooling device
+ is associated with.
1.4 Thermal Zone Parameters
-1.4.1 struct thermal_bind_params
+---------------------------
+
+ ::
+
+ struct thermal_bind_params
+
This structure defines the following parameters that are used to bind
a zone with a cooling device for a particular trip point.
- .cdev: The cooling device pointer
- .weight: The 'influence' of a particular cooling device on this
- zone. This is relative to the rest of the cooling
- devices. For example, if all cooling devices have a
- weight of 1, then they all contribute the same. You can
- use percentages if you want, but it's not mandatory. A
- weight of 0 means that this cooling device doesn't
- contribute to the cooling of this zone unless all cooling
- devices have a weight of 0. If all weights are 0, then
- they all contribute the same.
- .trip_mask:This is a bit mask that gives the binding relation between
- this thermal zone and cdev, for a particular trip point.
- If nth bit is set, then the cdev and thermal zone are bound
- for trip point n.
- .binding_limits: This is an array of cooling state limits. Must have
- exactly 2 * thermal_zone.number_of_trip_points. It is an
- array consisting of tuples <lower-state upper-state> of
- state limits. Each trip will be associated with one state
- limit tuple when binding. A NULL pointer means
- <THERMAL_NO_LIMITS THERMAL_NO_LIMITS> on all trips.
- These limits are used when binding a cdev to a trip point.
- .match: This call back returns success(0) if the 'tz and cdev' need to
+
+ .cdev:
+ The cooling device pointer
+ .weight:
+ The 'influence' of a particular cooling device on this
+ zone. This is relative to the rest of the cooling
+ devices. For example, if all cooling devices have a
+ weight of 1, then they all contribute the same. You can
+ use percentages if you want, but it's not mandatory. A
+ weight of 0 means that this cooling device doesn't
+ contribute to the cooling of this zone unless all cooling
+ devices have a weight of 0. If all weights are 0, then
+ they all contribute the same.
+ .trip_mask:
+ This is a bit mask that gives the binding relation between
+ this thermal zone and cdev, for a particular trip point.
+ If nth bit is set, then the cdev and thermal zone are bound
+ for trip point n.
+ .binding_limits:
+ This is an array of cooling state limits. Must have
+ exactly 2 * thermal_zone.number_of_trip_points. It is an
+ array consisting of tuples <lower-state upper-state> of
+ state limits. Each trip will be associated with one state
+ limit tuple when binding. A NULL pointer means
+ <THERMAL_NO_LIMITS THERMAL_NO_LIMITS> on all trips.
+ These limits are used when binding a cdev to a trip point.
+ .match:
+ This call back returns success(0) if the 'tz and cdev' need to
be bound, as per platform data.
-1.4.2 struct thermal_zone_params
+
+ ::
+
+ struct thermal_zone_params
+
This structure defines the platform level parameters for a thermal zone.
This data, for each thermal zone should come from the platform layer.
This is an optional feature where some platforms can choose not to
provide this data.
- .governor_name: Name of the thermal governor used for this zone
- .no_hwmon: a boolean to indicate if the thermal to hwmon sysfs interface
- is required. when no_hwmon == false, a hwmon sysfs interface
- will be created. when no_hwmon == true, nothing will be done.
- In case the thermal_zone_params is NULL, the hwmon interface
- will be created (for backward compatibility).
- .num_tbps: Number of thermal_bind_params entries for this zone
- .tbp: thermal_bind_params entries
+
+ .governor_name:
+ Name of the thermal governor used for this zone
+ .no_hwmon:
+ a boolean to indicate if the thermal to hwmon sysfs interface
+ is required. when no_hwmon == false, a hwmon sysfs interface
+ will be created. when no_hwmon == true, nothing will be done.
+ In case the thermal_zone_params is NULL, the hwmon interface
+ will be created (for backward compatibility).
+ .num_tbps:
+ Number of thermal_bind_params entries for this zone
+ .tbp:
+ thermal_bind_params entries
2. sysfs attributes structure
+=============================
+== ================
RO read only value
WO write only value
RW read/write value
+== ================
Thermal sysfs attributes will be represented under /sys/class/thermal.
Hwmon sysfs I/F extension is also available under /sys/class/hwmon
if hwmon is compiled in or built as a module.
-Thermal zone device sys I/F, created once it's registered:
-/sys/class/thermal/thermal_zone[0-*]:
+Thermal zone device sys I/F, created once it's registered::
+
+ /sys/class/thermal/thermal_zone[0-*]:
|---type: Type of the thermal zone
|---temp: Current temperature
|---mode: Working mode of the thermal zone
@@ -282,8 +396,9 @@ Thermal zone device sys I/F, created once it's registered:
|---slope: Slope constant applied as linear extrapolation
|---offset: Offset constant applied as linear extrapolation
-Thermal cooling device sys I/F, created once it's registered:
-/sys/class/thermal/cooling_device[0-*]:
+Thermal cooling device sys I/F, created once it's registered::
+
+ /sys/class/thermal/cooling_device[0-*]:
|---type: Type of the cooling device(processor/fan/...)
|---max_state: Maximum cooling state of the cooling device
|---cur_state: Current cooling state of the cooling device
@@ -299,11 +414,13 @@ the relationship between a thermal zone and its associated cooling device.
They are created/removed for each successful execution of
thermal_zone_bind_cooling_device/thermal_zone_unbind_cooling_device.
-/sys/class/thermal/thermal_zone[0-*]:
+::
+
+ /sys/class/thermal/thermal_zone[0-*]:
|---cdev[0-*]: [0-*]th cooling device in current thermal zone
|---cdev[0-*]_trip_point: Trip point that cdev[0-*] is associated with
|---cdev[0-*]_weight: Influence of the cooling device in
- this thermal zone
+ this thermal zone
Besides the thermal zone device sysfs I/F and cooling device sysfs I/F,
the generic thermal driver also creates a hwmon sysfs I/F for each _type_
@@ -311,16 +428,17 @@ of thermal zone device. E.g. the generic thermal driver registers one hwmon
class device and build the associated hwmon sysfs I/F for all the registered
ACPI thermal zones.
-/sys/class/hwmon/hwmon[0-*]:
+::
+
+ /sys/class/hwmon/hwmon[0-*]:
|---name: The type of the thermal zone devices
|---temp[1-*]_input: The current temperature of thermal zone [1-*]
|---temp[1-*]_critical: The critical trip point of thermal zone [1-*]
Please read Documentation/hwmon/sysfs-interface.rst for additional information.
-***************************
-* Thermal zone attributes *
-***************************
+Thermal zone attributes
+-----------------------
type
Strings which represent the thermal zone type.
@@ -340,54 +458,67 @@ mode
This file gives information about the algorithm that is currently
managing the thermal zone. It can be either default kernel based
algorithm or user space application.
- enabled = enable Kernel Thermal management.
- disabled = Preventing kernel thermal zone driver actions upon
+
+ enabled
+ enable Kernel Thermal management.
+ disabled
+ Preventing kernel thermal zone driver actions upon
trip points so that user application can take full
charge of the thermal management.
+
RW, Optional
policy
One of the various thermal governors used for a particular zone.
+
RW, Required
available_policies
Available thermal governors which can be used for a particular zone.
+
RO, Required
-trip_point_[0-*]_temp
+`trip_point_[0-*]_temp`
The temperature above which trip point will be fired.
+
Unit: millidegree Celsius
+
RO, Optional
-trip_point_[0-*]_type
+`trip_point_[0-*]_type`
Strings which indicate the type of the trip point.
- E.g. it can be one of critical, hot, passive, active[0-*] for ACPI
+
+ E.g. it can be one of critical, hot, passive, `active[0-*]` for ACPI
thermal zone.
+
RO, Optional
-trip_point_[0-*]_hyst
+`trip_point_[0-*]_hyst`
The hysteresis value for a trip point, represented as an integer
Unit: Celsius
RW, Optional
-cdev[0-*]
+`cdev[0-*]`
Sysfs link to the thermal cooling device node where the sys I/F
for cooling device throttling control represents.
+
RO, Optional
-cdev[0-*]_trip_point
- The trip point in this thermal zone which cdev[0-*] is associated
+`cdev[0-*]_trip_point`
+ The trip point in this thermal zone which `cdev[0-*]` is associated
with; -1 means the cooling device is not associated with any trip
point.
+
RO, Optional
-cdev[0-*]_weight
- The influence of cdev[0-*] in this thermal zone. This value
- is relative to the rest of cooling devices in the thermal
- zone. For example, if a cooling device has a weight double
- than that of other, it's twice as effective in cooling the
- thermal zone.
- RW, Optional
+`cdev[0-*]_weight`
+ The influence of `cdev[0-*]` in this thermal zone. This value
+ is relative to the rest of cooling devices in the thermal
+ zone. For example, if a cooling device has a weight double
+ than that of other, it's twice as effective in cooling the
+ thermal zone.
+
+ RW, Optional
passive
Attribute is only present for zones in which the passive cooling
@@ -395,8 +526,11 @@ passive
and can be set to a temperature (in millidegrees) to enable a
passive trip point for the zone. Activation is done by polling with
an interval of 1 second.
+
Unit: millidegrees Celsius
+
Valid values: 0 (disabled) or greater than 1000
+
RW, Optional
emul_temp
@@ -407,17 +541,21 @@ emul_temp
threshold and its associated cooling action. This is write only node
and writing 0 on this node should disable emulation.
Unit: millidegree Celsius
+
WO, Optional
- WARNING: Be careful while enabling this option on production systems,
- because userland can easily disable the thermal policy by simply
- flooding this sysfs node with low temperature values.
+ WARNING:
+ Be careful while enabling this option on production systems,
+ because userland can easily disable the thermal policy by simply
+ flooding this sysfs node with low temperature values.
sustainable_power
An estimate of the sustained power that can be dissipated by
the thermal zone. Used by the power allocator governor. For
- more information see Documentation/thermal/power_allocator.txt
+ more information see Documentation/thermal/power_allocator.rst
+
Unit: milliwatts
+
RW, Optional
k_po
@@ -425,7 +563,8 @@ k_po
controller during temperature overshoot. Temperature overshoot
is when the current temperature is above the "desired
temperature" trip point. For more information see
- Documentation/thermal/power_allocator.txt
+ Documentation/thermal/power_allocator.rst
+
RW, Optional
k_pu
@@ -433,20 +572,23 @@ k_pu
controller during temperature undershoot. Temperature undershoot
is when the current temperature is below the "desired
temperature" trip point. For more information see
- Documentation/thermal/power_allocator.txt
+ Documentation/thermal/power_allocator.rst
+
RW, Optional
k_i
The integral term of the power allocator governor's PID
controller. This term allows the PID controller to compensate
for long term drift. For more information see
- Documentation/thermal/power_allocator.txt
+ Documentation/thermal/power_allocator.rst
+
RW, Optional
k_d
The derivative term of the power allocator governor's PID
controller. For more information see
- Documentation/thermal/power_allocator.txt
+ Documentation/thermal/power_allocator.rst
+
RW, Optional
integral_cutoff
@@ -456,8 +598,10 @@ integral_cutoff
example, if integral_cutoff is 0, then the integral term only
accumulates error when temperature is above the desired
temperature trip point. For more information see
- Documentation/thermal/power_allocator.txt
+ Documentation/thermal/power_allocator.rst
+
Unit: millidegree Celsius
+
RW, Optional
slope
@@ -465,6 +609,7 @@ slope
to determine a hotspot temperature based off the sensor's
raw readings. It is up to the device driver to determine
the usage of these values.
+
RW, Optional
offset
@@ -472,28 +617,33 @@ offset
to determine a hotspot temperature based off the sensor's
raw readings. It is up to the device driver to determine
the usage of these values.
+
RW, Optional
-*****************************
-* Cooling device attributes *
-*****************************
+Cooling device attributes
+-------------------------
type
String which represents the type of device, e.g:
+
- for generic ACPI: should be "Fan", "Processor" or "LCD"
- for memory controller device on intel_menlow platform:
should be "Memory controller".
+
RO, Required
max_state
The maximum permissible cooling state of this cooling device.
+
RO, Required
cur_state
The current cooling state of this cooling device.
The value can any integer numbers between 0 and max_state:
+
- cur_state == 0 means no cooling
- cur_state == max_state means the maximum cooling.
+
RW, Required
stats/reset
@@ -508,9 +658,11 @@ stats/time_in_state_ms:
units here is 10mS (similar to other time exported in /proc).
RO, Required
+
stats/total_trans:
A single positive value showing the total number of times the state of a
cooling device is changed.
+
RO, Required
stats/trans_table:
@@ -522,6 +674,7 @@ stats/trans_table:
RO, Required
3. A simple implementation
+==========================
ACPI thermal zone may support multiple trip points like critical, hot,
passive, active. If an ACPI thermal zone supports critical, passive,
@@ -532,11 +685,10 @@ thermal_cooling_device. Both are considered to have the same
effectiveness in cooling the thermal zone.
If the processor is listed in _PSL method, and the fan is listed in _AL0
-method, the sys I/F structure will be built like this:
+method, the sys I/F structure will be built like this::
-/sys/class/thermal:
-
-|thermal_zone1:
+ /sys/class/thermal:
+ |thermal_zone1:
|---type: acpitz
|---temp: 37000
|---mode: enabled
@@ -557,24 +709,24 @@ method, the sys I/F structure will be built like this:
|---cdev1_trip_point: 2 /* cdev1 can be used for active[0]*/
|---cdev1_weight: 1024
-|cooling_device0:
+ |cooling_device0:
|---type: Processor
|---max_state: 8
|---cur_state: 0
-|cooling_device3:
+ |cooling_device3:
|---type: Fan
|---max_state: 2
|---cur_state: 0
-/sys/class/hwmon:
-
-|hwmon0:
+ /sys/class/hwmon:
+ |hwmon0:
|---name: acpitz
|---temp1_input: 37000
|---temp1_crit: 100000
4. Event Notification
+=====================
The framework includes a simple notification mechanism, in the form of a
netlink event. Netlink socket initialization is done during the _init_
@@ -587,21 +739,28 @@ event will be one of:{THERMAL_AUX0, THERMAL_AUX1, THERMAL_CRITICAL,
THERMAL_DEV_FAULT}. Notification can be sent when the current temperature
crosses any of the configured thresholds.
-5. Export Symbol APIs:
+5. Export Symbol APIs
+=====================
+
+5.1. get_tz_trend
+-----------------
-5.1: get_tz_trend:
This function returns the trend of a thermal zone, i.e the rate of change
of temperature of the thermal zone. Ideally, the thermal sensor drivers
are supposed to implement the callback. If they don't, the thermal
framework calculated the trend by comparing the previous and the current
temperature values.
-5.2:get_thermal_instance:
+5.2. get_thermal_instance
+-------------------------
+
This function returns the thermal_instance corresponding to a given
{thermal_zone, cooling_device, trip_point} combination. Returns NULL
if such an instance does not exist.
-5.3:thermal_notify_framework:
+5.3. thermal_notify_framework
+-----------------------------
+
This function handles the trip events from sensor drivers. It starts
throttling the cooling devices according to the policy configured.
For CRITICAL and HOT trip points, this notifies the respective drivers,
@@ -609,12 +768,15 @@ and does actual throttling for other trip points i.e ACTIVE and PASSIVE.
The throttling policy is based on the configured platform data; if no
platform data is provided, this uses the step_wise throttling policy.
-5.4:thermal_cdev_update:
+5.4. thermal_cdev_update
+------------------------
+
This function serves as an arbitrator to set the state of a cooling
device. It sets the cooling device to the deepest cooling state if
possible.
-6. thermal_emergency_poweroff:
+6. thermal_emergency_poweroff
+=============================
On an event of critical trip temperature crossing. Thermal framework
allows the system to shutdown gracefully by calling orderly_poweroff().
diff --git a/Documentation/thermal/x86_pkg_temperature_thermal b/Documentation/thermal/x86_pkg_temperature_thermal.rst
similarity index 80%
rename from Documentation/thermal/x86_pkg_temperature_thermal
rename to Documentation/thermal/x86_pkg_temperature_thermal.rst
index 17a3a4c0a0ca..f134dbd3f5a9 100644
--- a/Documentation/thermal/x86_pkg_temperature_thermal
+++ b/Documentation/thermal/x86_pkg_temperature_thermal.rst
@@ -1,19 +1,23 @@
+===================================
Kernel driver: x86_pkg_temp_thermal
-===================
+===================================
Supported chips:
+
* x86: with package level thermal management
+
(Verify using: CPUID.06H:EAX[bit 6] =1)
Authors: Srinivas Pandruvada <srinivas.pandruvada@linux.intel.com>
Reference
----
+---------
+
Intel® 64 and IA-32 Architectures Software Developer’s Manual (Jan, 2013):
Chapter 14.6: PACKAGE LEVEL THERMAL MANAGEMENT
Description
----------
+-----------
This driver register CPU digital temperature package level sensor as a thermal
zone with maximum two user mode configurable trip points. Number of trip points
@@ -25,23 +29,27 @@ take any action to control temperature.
Threshold management
--------------------
Each package will register as a thermal zone under /sys/class/thermal.
-Example:
-/sys/class/thermal/thermal_zone1
+
+Example::
+
+ /sys/class/thermal/thermal_zone1
This contains two trip points:
+
- trip_point_0_temp
- trip_point_1_temp
User can set any temperature between 0 to TJ-Max temperature. Temperature units
-are in milli-degree Celsius. Refer to "Documentation/thermal/sysfs-api.txt" for
+are in milli-degree Celsius. Refer to "Documentation/thermal/sysfs-api.rst" for
thermal sys-fs details.
Any value other than 0 in these trip points, can trigger thermal notifications.
Setting 0, stops sending thermal notifications.
-Thermal notifications: To get kobject-uevent notifications, set the thermal zone
-policy to "user_space". For example: echo -n "user_space" > policy
-
-
+Thermal notifications:
+To get kobject-uevent notifications, set the thermal zone
+policy to "user_space".
+For example::
+ echo -n "user_space" > policy
diff --git a/MAINTAINERS b/MAINTAINERS
index d9e214f68e52..b2254bc8e495 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -15687,7 +15687,7 @@ M: Viresh Kumar <viresh.kumar@linaro.org>
M: Javi Merino <javi.merino@kernel.org>
L: linux-pm@vger.kernel.org
S: Supported
-F: Documentation/thermal/cpu-cooling-api.txt
+F: Documentation/thermal/cpu-cooling-api.rst
F: drivers/thermal/cpu_cooling.c
F: include/linux/cpu_cooling.h
diff --git a/include/linux/thermal.h b/include/linux/thermal.h
index 15a4ca5d7099..681047f8cc05 100644
--- a/include/linux/thermal.h
+++ b/include/linux/thermal.h
@@ -251,7 +251,7 @@ struct thermal_bind_params {
* platform characterization. This value is relative to the
* rest of the weights so a cooling device whose weight is
* double that of another cooling device is twice as
- * effective. See Documentation/thermal/sysfs-api.txt for more
+ * effective. See Documentation/thermal/sysfs-api.rst for more
* information.
*/
int weight;
@@ -259,7 +259,7 @@ struct thermal_bind_params {
/*
* This is a bit mask that gives the binding relation between this
* thermal zone and cdev, for a particular trip point.
- * See Documentation/thermal/sysfs-api.txt for more information.
+ * See Documentation/thermal/sysfs-api.rst for more information.
*/
int trip_mask;
--
2.21.0
^ permalink raw reply related
* [PATCH v1 09/22] docs: block: convert to ReST
From: Mauro Carvalho Chehab @ 2019-06-18 21:05 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Paolo Valente, Jens Axboe, linux-block
In-Reply-To: <cover.1560891322.git.mchehab+samsung@kernel.org>
Rename the block documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.
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: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../admin-guide/kernel-parameters.txt | 8 +-
.../{bfq-iosched.txt => bfq-iosched.rst} | 66 ++--
.../block/{biodoc.txt => biodoc.rst} | 364 +++++++++++-------
.../block/{biovecs.txt => biovecs.rst} | 20 +-
.../block/{capability.txt => capability.rst} | 17 +-
...ne-partition.txt => cmdline-partition.rst} | 13 +-
...{data-integrity.txt => data-integrity.rst} | 60 +--
...dline-iosched.txt => deadline-iosched.rst} | 21 +-
Documentation/block/index.rst | 25 ++
.../block/{ioprio.txt => ioprio.rst} | 95 +++--
.../{kyber-iosched.txt => kyber-iosched.rst} | 3 +-
.../block/{null_blk.txt => null_blk.rst} | 65 +++-
Documentation/block/{pr.txt => pr.rst} | 18 +-
.../{queue-sysfs.txt => queue-sysfs.rst} | 7 +-
.../block/{request.txt => request.rst} | 47 ++-
Documentation/block/{stat.txt => stat.rst} | 13 +-
...witching-sched.txt => switching-sched.rst} | 28 +-
...ontrol.txt => writeback_cache_control.rst} | 12 +-
Documentation/blockdev/zram.rst | 2 +-
MAINTAINERS | 2 +-
block/Kconfig | 2 +-
block/Kconfig.iosched | 2 +-
block/bfq-iosched.c | 2 +-
block/blk-integrity.c | 2 +-
block/ioprio.c | 2 +-
block/mq-deadline.c | 2 +-
block/partitions/cmdline.c | 2 +-
27 files changed, 550 insertions(+), 350 deletions(-)
rename Documentation/block/{bfq-iosched.txt => bfq-iosched.rst} (95%)
rename Documentation/block/{biodoc.txt => biodoc.rst} (83%)
rename Documentation/block/{biovecs.txt => biovecs.rst} (92%)
rename Documentation/block/{capability.txt => capability.rst} (40%)
rename Documentation/block/{cmdline-partition.txt => cmdline-partition.rst} (92%)
rename Documentation/block/{data-integrity.txt => data-integrity.rst} (91%)
rename Documentation/block/{deadline-iosched.txt => deadline-iosched.rst} (89%)
create mode 100644 Documentation/block/index.rst
rename Documentation/block/{ioprio.txt => ioprio.rst} (75%)
rename Documentation/block/{kyber-iosched.txt => kyber-iosched.rst} (86%)
rename Documentation/block/{null_blk.txt => null_blk.rst} (60%)
rename Documentation/block/{pr.txt => pr.rst} (93%)
rename Documentation/block/{queue-sysfs.txt => queue-sysfs.rst} (99%)
rename Documentation/block/{request.txt => request.rst} (59%)
rename Documentation/block/{stat.txt => stat.rst} (89%)
rename Documentation/block/{switching-sched.txt => switching-sched.rst} (67%)
rename Documentation/block/{writeback_cache_control.txt => writeback_cache_control.rst} (94%)
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index a15295e180fe..d11b8a745897 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -430,7 +430,7 @@
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
@@ -1199,9 +1199,9 @@
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
diff --git a/Documentation/block/bfq-iosched.txt b/Documentation/block/bfq-iosched.rst
similarity index 95%
rename from Documentation/block/bfq-iosched.txt
rename to Documentation/block/bfq-iosched.rst
index b2265cf6c9c3..3fd9e8029347 100644
--- a/Documentation/block/bfq-iosched.txt
+++ b/Documentation/block/bfq-iosched.rst
@@ -1,9 +1,11 @@
+==========================
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;
@@ -55,18 +57,18 @@ sustainable throughputs, on the same systems as above:
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
- 1-2 Server systems
-2. How does BFQ work?
-3. What are BFQ's tunables and how to properly configure BFQ?
-4. BFQ group scheduling
- 4-1 Service guarantees provided
- 4-2 Interface
+ 1. When may BFQ be useful?
+ 1-1 Personal systems
+ 1-2 Server systems
+ 2. How does BFQ work?
+ 3. What are BFQ's tunables and how to properly configure BFQ?
+ 4. BFQ group scheduling
+ 4-1 Service guarantees provided
+ 4-2 Interface
1. When may BFQ be useful?
==========================
@@ -77,17 +79,20 @@ BFQ provides the following benefits on personal and server 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,
@@ -95,13 +100,14 @@ applications experience high latencies, or even become unresponsive
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
@@ -109,6 +115,7 @@ tasks (compilation, checkout, merge, ...) much more quickly than CFQ,
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
@@ -117,6 +124,7 @@ and with all the workloads on flash-based devices, BFQ achieves,
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
@@ -133,15 +141,15 @@ Most benefits for server systems follow from the same service
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?
@@ -151,7 +159,7 @@ BFQ is a proportional-share I/O scheduler, whose general structure,
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
@@ -540,11 +548,12 @@ created, and kept up-to-date by bfq, depends on whether
CONFIG_DEBUG_BLK_CGROUP is set. If it is set, then bfq creates all
the stat files documented in
Documentation/cgroup-v1/blkio-controller.rst. If, instead,
-CONFIG_DEBUG_BLK_CGROUP is not set, then bfq creates only the files
-blkio.bfq.io_service_bytes
-blkio.bfq.io_service_bytes_recursive
-blkio.bfq.io_serviced
-blkio.bfq.io_serviced_recursive
+CONFIG_DEBUG_BLK_CGROUP is not set, then bfq creates only the files::
+
+ blkio.bfq.io_service_bytes
+ blkio.bfq.io_service_bytes_recursive
+ blkio.bfq.io_serviced
+ blkio.bfq.io_serviced_recursive
The value of CONFIG_DEBUG_BLK_CGROUP greatly influences the maximum
throughput sustainable with bfq, because updating the blkio.bfq.*
@@ -567,17 +576,22 @@ weight of the queues associated with interactive and soft real-time
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
diff --git a/Documentation/block/biodoc.txt b/Documentation/block/biodoc.rst
similarity index 83%
rename from Documentation/block/biodoc.txt
rename to Documentation/block/biodoc.rst
index ac504de0cb93..59bd93bec8fc 100644
--- a/Documentation/block/biodoc.txt
+++ b/Documentation/block/biodoc.rst
@@ -1,15 +1,24 @@
- Notes on the Generic Block Layer Rewrite in Linux 2.5
- =====================================================
+=====================================================
+Notes on the Generic Block Layer Rewrite in Linux 2.5
+=====================================================
+
+.. note::
+
+ It seems that there are lot of outdated stuff here. This seems
+ to be written somewhat as a task list. Yet, eventually, something
+ here might still be useful.
Notes Written on Jan 15, 2002:
- Jens Axboe <jens.axboe@oracle.com>
- Suparna Bhattacharya <suparna@in.ibm.com>
+ - Jens Axboe <jens.axboe@oracle.com>
+ - Suparna Bhattacharya <suparna@in.ibm.com>
Last Updated May 2, 2002
+
September 2003: Updated I/O Scheduler portions
- Nick Piggin <npiggin@kernel.dk>
+ - Nick Piggin <npiggin@kernel.dk>
-Introduction:
+Introduction
+============
These are some notes describing some aspects of the 2.5 block layer in the
context of the bio rewrite. The idea is to bring out some of the key
@@ -17,11 +26,11 @@ changes and a glimpse of the rationale behind those changes.
Please mail corrections & suggestions to suparna@in.ibm.com.
-Credits:
----------
+Credits
+=======
2.5 bio rewrite:
- Jens Axboe <jens.axboe@oracle.com>
+ - Jens Axboe <jens.axboe@oracle.com>
Many aspects of the generic block layer redesign were driven by and evolved
over discussions, prior patches and the collective experience of several
@@ -29,62 +38,63 @@ people. See sections 8 and 9 for a list of some related references.
The following people helped with review comments and inputs for this
document:
- Christoph Hellwig <hch@infradead.org>
- Arjan van de Ven <arjanv@redhat.com>
- Randy Dunlap <rdunlap@xenotime.net>
- Andre Hedrick <andre@linux-ide.org>
+
+ - Christoph Hellwig <hch@infradead.org>
+ - Arjan van de Ven <arjanv@redhat.com>
+ - Randy Dunlap <rdunlap@xenotime.net>
+ - Andre Hedrick <andre@linux-ide.org>
The following people helped with fixes/contributions to the bio patches
while it was still work-in-progress:
- David S. Miller <davem@redhat.com>
+ - David S. Miller <davem@redhat.com>
-Description of Contents:
-------------------------
-1. Scope for tuning of logic to various needs
- 1.1 Tuning based on device or low level driver capabilities
+.. Description of Contents:
+
+ 1. Scope for tuning of logic to various needs
+ 1.1 Tuning based on device or low level driver capabilities
- Per-queue parameters
- Highmem I/O support
- I/O scheduler modularization
- 1.2 Tuning based on high level requirements/capabilities
+ 1.2 Tuning based on high level requirements/capabilities
1.2.1 Request Priority/Latency
- 1.3 Direct access/bypass to lower layers for diagnostics and special
- device operations
+ 1.3 Direct access/bypass to lower layers for diagnostics and special
+ device operations
1.3.1 Pre-built commands
-2. New flexible and generic but minimalist i/o structure or descriptor
- (instead of using buffer heads at the i/o layer)
- 2.1 Requirements/Goals addressed
- 2.2 The bio struct in detail (multi-page io unit)
- 2.3 Changes in the request structure
-3. Using bios
- 3.1 Setup/teardown (allocation, splitting)
- 3.2 Generic bio helper routines
- 3.2.1 Traversing segments and completion units in a request
- 3.2.2 Setting up DMA scatterlists
- 3.2.3 I/O completion
- 3.2.4 Implications for drivers that do not interpret bios (don't handle
- multiple segments)
- 3.3 I/O submission
-4. The I/O scheduler
-5. Scalability related changes
- 5.1 Granular locking: Removal of io_request_lock
- 5.2 Prepare for transition to 64 bit sector_t
-6. Other Changes/Implications
- 6.1 Partition re-mapping handled by the generic block layer
-7. A few tips on migration of older drivers
-8. A list of prior/related/impacted patches/ideas
-9. Other References/Discussion Threads
+ 2. New flexible and generic but minimalist i/o structure or descriptor
+ (instead of using buffer heads at the i/o layer)
+ 2.1 Requirements/Goals addressed
+ 2.2 The bio struct in detail (multi-page io unit)
+ 2.3 Changes in the request structure
+ 3. Using bios
+ 3.1 Setup/teardown (allocation, splitting)
+ 3.2 Generic bio helper routines
+ 3.2.1 Traversing segments and completion units in a request
+ 3.2.2 Setting up DMA scatterlists
+ 3.2.3 I/O completion
+ 3.2.4 Implications for drivers that do not interpret bios (don't handle
+ multiple segments)
+ 3.3 I/O submission
+ 4. The I/O scheduler
+ 5. Scalability related changes
+ 5.1 Granular locking: Removal of io_request_lock
+ 5.2 Prepare for transition to 64 bit sector_t
+ 6. Other Changes/Implications
+ 6.1 Partition re-mapping handled by the generic block layer
+ 7. A few tips on migration of older drivers
+ 8. A list of prior/related/impacted patches/ideas
+ 9. Other References/Discussion Threads
----------------------------------------------------------------------------
Bio Notes
---------
+=========
Let us discuss the changes in the context of how some overall goals for the
block layer are addressed.
1. Scope for tuning the generic logic to satisfy various requirements
+=====================================================================
The block layer design supports adaptable abstractions to handle common
processing with the ability to tune the logic to an appropriate extent
@@ -97,6 +107,7 @@ and application/middleware software designed to take advantage of these
capabilities.
1.1 Tuning based on low level device / driver capabilities
+----------------------------------------------------------
Sophisticated devices with large built-in caches, intelligent i/o scheduling
optimizations, high memory DMA support, etc may find some of the
@@ -133,12 +144,12 @@ Some new queue property settings:
Sets two variables that limit the size of the request.
- The request queue's max_sectors, which is a soft size in
- units of 512 byte sectors, and could be dynamically varied
- by the core kernel.
+ units of 512 byte sectors, and could be dynamically varied
+ by the core kernel.
- The request queue's max_hw_sectors, which is a hard limit
- and reflects the maximum size request a driver can handle
- in units of 512 byte sectors.
+ and reflects the maximum size request a driver can handle
+ in units of 512 byte sectors.
The default for both max_sectors and max_hw_sectors is
255. The upper limit of max_sectors is 1024.
@@ -234,6 +245,7 @@ I/O scheduler wrappers are to be used instead of accessing the queue directly.
See section 4. The I/O scheduler for details.
1.2 Tuning Based on High level code capabilities
+------------------------------------------------
i. Application capabilities for raw i/o
@@ -258,9 +270,11 @@ would need an additional mechanism either via open flags or ioctls, or some
other upper level mechanism to communicate such settings to block.
1.2.1 Request Priority/Latency
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Todo/Under discussion:
-Arjan's proposed request priority scheme allows higher levels some broad
+Todo/Under discussion::
+
+ Arjan's proposed request priority scheme allows higher levels some broad
control (high/med/low) over the priority of an i/o request vs other pending
requests in the queue. For example it allows reads for bringing in an
executable page on demand to be given a higher priority over pending write
@@ -272,7 +286,9 @@ Arjan's proposed request priority scheme allows higher levels some broad
1.3 Direct Access to Low level Device/Driver Capabilities (Bypass mode)
- (e.g Diagnostics, Systems Management)
+-----------------------------------------------------------------------
+
+(e.g Diagnostics, Systems Management)
There are situations where high-level code needs to have direct access to
the low level device capabilities or requires the ability to issue commands
@@ -308,28 +324,32 @@ involved. In the latter case, the driver would modify and manage the
request->buffer, request->sector and request->nr_sectors or
request->current_nr_sectors fields itself rather than using the block layer
end_request or end_that_request_first completion interfaces.
-(See 2.3 or Documentation/block/request.txt for a brief explanation of
+(See 2.3 or Documentation/block/request.rst for a brief explanation of
the request structure fields)
-[TBD: end_that_request_last should be usable even in this case;
-Perhaps an end_that_direct_request_first routine could be implemented to make
-handling direct requests easier for such drivers; Also for drivers that
-expect bios, a helper function could be provided for setting up a bio
-corresponding to a data buffer]
+::
-<JENS: I dont understand the above, why is end_that_request_first() not
-usable? Or _last for that matter. I must be missing something>
-<SUP: What I meant here was that if the request doesn't have a bio, then
- end_that_request_first doesn't modify nr_sectors or current_nr_sectors,
- and hence can't be used for advancing request state settings on the
- completion of partial transfers. The driver has to modify these fields
- directly by hand.
- This is because end_that_request_first only iterates over the bio list,
- and always returns 0 if there are none associated with the request.
- _last works OK in this case, and is not a problem, as I mentioned earlier
->
+ [TBD: end_that_request_last should be usable even in this case;
+ Perhaps an end_that_direct_request_first routine could be implemented to make
+ handling direct requests easier for such drivers; Also for drivers that
+ expect bios, a helper function could be provided for setting up a bio
+ corresponding to a data buffer]
+
+ <JENS: I dont understand the above, why is end_that_request_first() not
+ usable? Or _last for that matter. I must be missing something>
+
+ <SUP: What I meant here was that if the request doesn't have a bio, then
+ end_that_request_first doesn't modify nr_sectors or current_nr_sectors,
+ and hence can't be used for advancing request state settings on the
+ completion of partial transfers. The driver has to modify these fields
+ directly by hand.
+ This is because end_that_request_first only iterates over the bio list,
+ and always returns 0 if there are none associated with the request.
+ _last works OK in this case, and is not a problem, as I mentioned earlier
+ >
1.3.1 Pre-built Commands
+^^^^^^^^^^^^^^^^^^^^^^^^
A request can be created with a pre-built custom command to be sent directly
to the device. The cmd block in the request structure has room for filling
@@ -360,9 +380,11 @@ Aside:
the pre-builder hook can be invoked there.
-2. Flexible and generic but minimalist i/o structure/descriptor.
+2. Flexible and generic but minimalist i/o structure/descriptor
+===============================================================
2.1 Reason for a new structure and requirements addressed
+---------------------------------------------------------
Prior to 2.5, buffer heads were used as the unit of i/o at the generic block
layer, and the low level request structure was associated with a chain of
@@ -378,26 +400,26 @@ which were generated for each such chunk.
The following were some of the goals and expectations considered in the
redesign of the block i/o data structure in 2.5.
-i. Should be appropriate as a descriptor for both raw and buffered i/o -
+1. Should be appropriate as a descriptor for both raw and buffered i/o -
avoid cache related fields which are irrelevant in the direct/page i/o path,
or filesystem block size alignment restrictions which may not be relevant
for raw i/o.
-ii. Ability to represent high-memory buffers (which do not have a virtual
+2. Ability to represent high-memory buffers (which do not have a virtual
address mapping in kernel address space).
-iii.Ability to represent large i/os w/o unnecessarily breaking them up (i.e
+3. Ability to represent large i/os w/o unnecessarily breaking them up (i.e
greater than PAGE_SIZE chunks in one shot)
-iv. At the same time, ability to retain independent identity of i/os from
+4. At the same time, ability to retain independent identity of i/os from
different sources or i/o units requiring individual completion (e.g. for
latency reasons)
-v. Ability to represent an i/o involving multiple physical memory segments
+5. Ability to represent an i/o involving multiple physical memory segments
(including non-page aligned page fragments, as specified via readv/writev)
without unnecessarily breaking it up, if the underlying device is capable of
handling it.
-vi. Preferably should be based on a memory descriptor structure that can be
+6. Preferably should be based on a memory descriptor structure that can be
passed around different types of subsystems or layers, maybe even
networking, without duplication or extra copies of data/descriptor fields
themselves in the process
-vii.Ability to handle the possibility of splits/merges as the structure passes
+7. Ability to handle the possibility of splits/merges as the structure passes
through layered drivers (lvm, md, evms), with minimal overhead.
The solution was to define a new structure (bio) for the block layer,
@@ -408,6 +430,7 @@ bh structure for buffered i/o, and in the case of raw/direct i/o kiobufs are
mapped to bio structures.
2.2 The bio struct
+------------------
The bio structure uses a vector representation pointing to an array of tuples
of <page, offset, len> to describe the i/o buffer, and has various other
@@ -417,34 +440,36 @@ performing the i/o.
Notice that this representation means that a bio has no virtual address
mapping at all (unlike buffer heads).
-struct bio_vec {
- struct page *bv_page;
- unsigned short bv_len;
- unsigned short bv_offset;
-};
+::
-/*
- * main unit of I/O for the block layer and lower layers (ie drivers)
- */
-struct bio {
- struct bio *bi_next; /* request queue link */
- struct block_device *bi_bdev; /* target device */
- unsigned long bi_flags; /* status, command, etc */
- unsigned long bi_opf; /* low bits: r/w, high: priority */
+ struct bio_vec {
+ struct page *bv_page;
+ unsigned short bv_len;
+ unsigned short bv_offset;
+ };
- unsigned int bi_vcnt; /* how may bio_vec's */
- struct bvec_iter bi_iter; /* current index into bio_vec array */
+ /*
+ * main unit of I/O for the block layer and lower layers (ie drivers)
+ */
+ struct bio {
+ struct bio *bi_next; /* request queue link */
+ struct block_device *bi_bdev; /* target device */
+ unsigned long bi_flags; /* status, command, etc */
+ unsigned long bi_opf; /* low bits: r/w, high: priority */
- unsigned int bi_size; /* total size in bytes */
- unsigned short bi_phys_segments; /* segments after physaddr coalesce*/
- unsigned short bi_hw_segments; /* segments after DMA remapping */
- unsigned int bi_max; /* max bio_vecs we can hold
- used as index into pool */
- struct bio_vec *bi_io_vec; /* the actual vec list */
- bio_end_io_t *bi_end_io; /* bi_end_io (bio) */
- atomic_t bi_cnt; /* pin count: free when it hits zero */
- void *bi_private;
-};
+ unsigned int bi_vcnt; /* how may bio_vec's */
+ struct bvec_iter bi_iter; /* current index into bio_vec array */
+
+ unsigned int bi_size; /* total size in bytes */
+ unsigned short bi_phys_segments; /* segments after physaddr coalesce*/
+ unsigned short bi_hw_segments; /* segments after DMA remapping */
+ unsigned int bi_max; /* max bio_vecs we can hold
+ used as index into pool */
+ struct bio_vec *bi_io_vec; /* the actual vec list */
+ bio_end_io_t *bi_end_io; /* bi_end_io (bio) */
+ atomic_t bi_cnt; /* pin count: free when it hits zero */
+ void *bi_private;
+ };
With this multipage bio design:
@@ -454,7 +479,7 @@ With this multipage bio design:
- Splitting of an i/o request across multiple devices (as in the case of
lvm or raid) is achieved by cloning the bio (where the clone points to
the same bi_io_vec array, but with the index and size accordingly modified)
-- A linked list of bios is used as before for unrelated merges (*) - this
+- A linked list of bios is used as before for unrelated merges [*]_ - this
avoids reallocs and makes independent completions easier to handle.
- Code that traverses the req list can find all the segments of a bio
by using rq_for_each_segment. This handles the fact that a request
@@ -463,10 +488,12 @@ With this multipage bio design:
field to keep track of the next bio_vec entry to process.
(e.g a 1MB bio_vec needs to be handled in max 128kB chunks for IDE)
[TBD: Should preferably also have a bi_voffset and bi_vlen to avoid modifying
- bi_offset an len fields]
+ bi_offset an len fields]
-(*) unrelated merges -- a request ends up containing two or more bios that
- didn't originate from the same place.
+.. [*]
+
+ unrelated merges -- a request ends up containing two or more bios that
+ didn't originate from the same place.
bi_end_io() i/o callback gets called on i/o completion of the entire bio.
@@ -484,10 +511,11 @@ which in turn means that only raw I/O uses it (direct i/o may not work
right now). The intent however is to enable clustering of pages etc to
become possible. The pagebuf abstraction layer from SGI also uses multi-page
bios, but that is currently not included in the stock development kernels.
-The same is true of Andrew Morton's work-in-progress multipage bio writeout
+The same is true of Andrew Morton's work-in-progress multipage bio writeout
and readahead patches.
2.3 Changes in the Request Structure
+------------------------------------
The request structure is the structure that gets passed down to low level
drivers. The block layer make_request function builds up a request structure,
@@ -500,11 +528,11 @@ request structure.
Only some relevant fields (mainly those which changed or may be referred
to in some of the discussion here) are listed below, not necessarily in
the order in which they occur in the structure (see include/linux/blkdev.h)
-Refer to Documentation/block/request.txt for details about all the request
+Refer to Documentation/block/request.rst for details about all the request
structure fields and a quick reference about the layers which are
-supposed to use or modify those fields.
+supposed to use or modify those fields::
-struct request {
+ struct request {
struct list_head queuelist; /* Not meant to be directly accessed by
the driver.
Used by q->elv_next_request_fn
@@ -549,11 +577,11 @@ struct request {
.
struct bio *bio, *biotail; /* bio list instead of bh */
struct request_list *rl;
-}
-
+ }
+
See the req_ops and req_flag_bits definitions for an explanation of the various
flags available. Some bits are used by the block layer or i/o scheduler.
-
+
The behaviour of the various sector counts are almost the same as before,
except that since we have multi-segment bios, current_nr_sectors refers
to the numbers of sectors in the current segment being processed which could
@@ -579,8 +607,10 @@ a driver needs to be careful about interoperation with the block layer helper
functions which the driver uses. (Section 1.3)
3. Using bios
+=============
3.1 Setup/Teardown
+------------------
There are routines for managing the allocation, and reference counting, and
freeing of bios (bio_alloc, bio_get, bio_put).
@@ -607,10 +637,13 @@ case of bio, these routines make use of the standard slab allocator.
The caller of bio_alloc is expected to taken certain steps to avoid
deadlocks, e.g. avoid trying to allocate more memory from the pool while
already holding memory obtained from the pool.
-[TBD: This is a potential issue, though a rare possibility
- in the bounce bio allocation that happens in the current code, since
- it ends up allocating a second bio from the same pool while
- holding the original bio ]
+
+::
+
+ [TBD: This is a potential issue, though a rare possibility
+ in the bounce bio allocation that happens in the current code, since
+ it ends up allocating a second bio from the same pool while
+ holding the original bio ]
Memory allocated from the pool should be released back within a limited
amount of time (in the case of bio, that would be after the i/o is completed).
@@ -636,14 +669,18 @@ same bio_vec_list). This would typically be used for splitting i/o requests
in lvm or md.
3.2 Generic bio helper Routines
+-------------------------------
3.2.1 Traversing segments and completion units in a request
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The macro rq_for_each_segment() should be used for traversing the bios
in the request list (drivers should avoid directly trying to do it
themselves). Using these helpers should also make it easier to cope
with block changes in the future.
+::
+
struct req_iterator iter;
rq_for_each_segment(bio_vec, rq, iter)
/* bio_vec is now current segment */
@@ -654,6 +691,7 @@ which don't make a distinction between segments and completion units would
need to be reorganized to support multi-segment bios.
3.2.2 Setting up DMA scatterlists
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The blk_rq_map_sg() helper routine would be used for setting up scatter
gather lists from a request, so a driver need not do it on its own.
@@ -684,6 +722,7 @@ of physical data segments in a request (i.e. the largest sized scatter list
a driver could handle)
3.2.3 I/O completion
+^^^^^^^^^^^^^^^^^^^^
The existing generic block layer helper routines end_request,
end_that_request_first and end_that_request_last can be used for i/o
@@ -692,8 +731,10 @@ request can be kicked of) as before. With the introduction of multi-page
bio support, end_that_request_first requires an additional argument indicating
the number of sectors completed.
-3.2.4 Implications for drivers that do not interpret bios (don't handle
- multiple segments)
+3.2.4 Implications for drivers that do not interpret bios
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+(don't handle multiple segments)
Drivers that do not interpret bios e.g those which do not handle multiple
segments and do not support i/o into high memory addresses (require bounce
@@ -708,15 +749,18 @@ be used if only if the request has come down from block/bio path, not for
direct access requests which only specify rq->buffer without a valid rq->bio)
3.3 I/O Submission
+------------------
The routine submit_bio() is used to submit a single io. Higher level i/o
routines make use of this:
(a) Buffered i/o:
+
The routine submit_bh() invokes submit_bio() on a bio corresponding to the
bh, allocating the bio if required. ll_rw_block() uses submit_bh() as before.
(b) Kiobuf i/o (for raw/direct i/o):
+
The ll_rw_kio() routine breaks up the kiobuf into page sized chunks and
maps the array to one or more multi-page bios, issuing submit_bio() to
perform the i/o on each of these.
@@ -739,6 +783,7 @@ Todo/Observation:
(c) Page i/o:
+
Todo/Under discussion:
Andrew Morton's multi-page bio patches attempt to issue multi-page
@@ -754,6 +799,7 @@ Todo/Under discussion:
abstraction, but intended to be as lightweight as possible).
(d) Direct access i/o:
+
Direct access requests that do not contain bios would be submitted differently
as discussed earlier in section 1.3.
@@ -781,11 +827,13 @@ Aside:
4. The I/O scheduler
+====================
+
I/O scheduler, a.k.a. elevator, is implemented in two layers. Generic dispatch
queue and specific I/O schedulers. Unless stated otherwise, elevator is used
to refer to both parts and I/O scheduler to specific I/O schedulers.
-Block layer implements generic dispatch queue in block/*.c.
+Block layer implements generic dispatch queue in `block/*.c`.
The generic dispatch queue is responsible for requeueing, handling non-fs
requests and all other subtleties.
@@ -803,8 +851,11 @@ doesn't implement a function, the switch does nothing or some minimal house
keeping work.
4.1. I/O scheduler API
+----------------------
The functions an elevator may implement are: (* are mandatory)
+
+=============================== ================================================
elevator_merge_fn called to query requests for merge with a bio
elevator_merge_req_fn called when two requests get merged. the one
@@ -863,8 +914,11 @@ elevator_deactivate_req_fn Called when device driver decides to delay
elevator_init_fn*
elevator_exit_fn Allocate and free any elevator specific storage
for a queue.
+=============================== ================================================
4.2 Request flows seen by I/O schedulers
+----------------------------------------
+
All requests seen by I/O schedulers strictly follow one of the following three
flows.
@@ -878,9 +932,12 @@ flows.
-> put_req_fn
4.3 I/O scheduler implementation
+--------------------------------
+
The generic i/o scheduler algorithm attempts to sort/merge/batch requests for
optimal disk scan and request servicing performance (based on generic
principles and device capabilities), optimized for:
+
i. improved throughput
ii. improved latency
iii. better utilization of h/w & CPU time
@@ -934,15 +991,19 @@ Aside:
a big request from the broken up pieces coming by.
4.4 I/O contexts
+----------------
+
I/O contexts provide a dynamically allocated per process data area. They may
be used in I/O schedulers, and in the block layer (could be used for IO statis,
-priorities for example). See *io_context in block/ll_rw_blk.c, and as-iosched.c
+priorities for example). See `*io_context` in block/ll_rw_blk.c, and as-iosched.c
for an example of usage in an i/o scheduler.
5. Scalability related changes
+==============================
5.1 Granular Locking: io_request_lock replaced by a per-queue lock
+------------------------------------------------------------------
The global io_request_lock has been removed as of 2.5, to avoid
the scalability bottleneck it was causing, and has been replaced by more
@@ -957,20 +1018,23 @@ request_fn execution which it means that lots of older drivers
should still be SMP safe. Drivers are free to drop the queue
lock themselves, if required. Drivers that explicitly used the
io_request_lock for serialization need to be modified accordingly.
-Usually it's as easy as adding a global lock:
+Usually it's as easy as adding a global lock::
static DEFINE_SPINLOCK(my_driver_lock);
and passing the address to that lock to blk_init_queue().
5.2 64 bit sector numbers (sector_t prepares for 64 bit support)
+----------------------------------------------------------------
The sector number used in the bio structure has been changed to sector_t,
which could be defined as 64 bit in preparation for 64 bit sector support.
6. Other Changes/Implications
+=============================
6.1 Partition re-mapping handled by the generic block layer
+-----------------------------------------------------------
In 2.5 some of the gendisk/partition related code has been reorganized.
Now the generic block layer performs partition-remapping early and thus
@@ -985,6 +1049,7 @@ sent are offset from the beginning of the device.
7. A Few Tips on Migration of older drivers
+===========================================
Old-style drivers that just use CURRENT and ignores clustered requests,
may not need much change. The generic layer will automatically handle
@@ -1018,12 +1083,12 @@ blk_init_queue time.
Drivers no longer have to map a {partition, sector offset} into the
correct absolute location anymore, this is done by the block layer, so
-where a driver received a request ala this before:
+where a driver received a request ala this before::
rq->rq_dev = mk_kdev(3, 5); /* /dev/hda5 */
rq->sector = 0; /* first sector on hda5 */
- it will now see
+it will now see::
rq->rq_dev = mk_kdev(3, 0); /* /dev/hda */
rq->sector = 123128; /* offset from start of disk */
@@ -1040,38 +1105,65 @@ a bio into the virtual address space.
8. Prior/Related/Impacted patches
+=================================
8.1. Earlier kiobuf patches (sct/axboe/chait/hch/mkp)
+-----------------------------------------------------
+
- orig kiobuf & raw i/o patches (now in 2.4 tree)
- direct kiobuf based i/o to devices (no intermediate bh's)
- page i/o using kiobuf
- kiobuf splitting for lvm (mkp)
- elevator support for kiobuf request merging (axboe)
+
8.2. Zero-copy networking (Dave Miller)
+---------------------------------------
+
8.3. SGI XFS - pagebuf patches - use of kiobufs
+-----------------------------------------------
8.4. Multi-page pioent patch for bio (Christoph Hellwig)
+--------------------------------------------------------
8.5. Direct i/o implementation (Andrea Arcangeli) since 2.4.10-pre11
+--------------------------------------------------------------------
8.6. Async i/o implementation patch (Ben LaHaise)
+-------------------------------------------------
8.7. EVMS layering design (IBM EVMS team)
-8.8. Larger page cache size patch (Ben LaHaise) and
- Large page size (Daniel Phillips)
+-----------------------------------------
+8.8. Larger page cache size patch (Ben LaHaise) and Large page size (Daniel Phillips)
+-------------------------------------------------------------------------------------
+
=> larger contiguous physical memory buffers
+
8.9. VM reservations patch (Ben LaHaise)
+----------------------------------------
8.10. Write clustering patches ? (Marcelo/Quintela/Riel ?)
+----------------------------------------------------------
8.11. Block device in page cache patch (Andrea Archangeli) - now in 2.4.10+
-8.12. Multiple block-size transfers for faster raw i/o (Shailabh Nagar,
- Badari)
+---------------------------------------------------------------------------
+8.12. Multiple block-size transfers for faster raw i/o (Shailabh Nagar, Badari)
+-------------------------------------------------------------------------------
8.13 Priority based i/o scheduler - prepatches (Arjan van de Ven)
+------------------------------------------------------------------
8.14 IDE Taskfile i/o patch (Andre Hedrick)
+--------------------------------------------
8.15 Multi-page writeout and readahead patches (Andrew Morton)
+---------------------------------------------------------------
8.16 Direct i/o patches for 2.5 using kvec and bio (Badari Pulavarthy)
+-----------------------------------------------------------------------
-9. Other References:
+9. Other References
+===================
+
+9.1 The Splice I/O Model
+------------------------
+
+Larry McVoy (and subsequent discussions on lkml, and Linus' comments - Jan 2001
+
+9.2 Discussions about kiobuf and bh design
+------------------------------------------
+
+On lkml between sct, linus, alan et al - Feb-March 2001 (many of the
+initial thoughts that led to bio were brought up in this discussion thread)
-9.1 The Splice I/O Model - Larry McVoy (and subsequent discussions on lkml,
-and Linus' comments - Jan 2001)
-9.2 Discussions about kiobuf and bh design on lkml between sct, linus, alan
-et al - Feb-March 2001 (many of the initial thoughts that led to bio were
-brought up in this discussion thread)
9.3 Discussions on mempool on lkml - Dec 2001.
-
+----------------------------------------------
diff --git a/Documentation/block/biovecs.txt b/Documentation/block/biovecs.rst
similarity index 92%
rename from Documentation/block/biovecs.txt
rename to Documentation/block/biovecs.rst
index ce6eccaf5df7..86fa66c87172 100644
--- a/Documentation/block/biovecs.txt
+++ b/Documentation/block/biovecs.rst
@@ -1,6 +1,6 @@
-
-Immutable biovecs and biovec iterators:
-=======================================
+======================================
+Immutable biovecs and biovec iterators
+======================================
Kent Overstreet <kmo@daterainc.com>
@@ -121,10 +121,12 @@ Other implications:
Usage of helpers:
=================
-* 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.
+* 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()
@@ -132,13 +134,13 @@ driver.
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()
diff --git a/Documentation/block/capability.txt b/Documentation/block/capability.rst
similarity index 40%
rename from Documentation/block/capability.txt
rename to Documentation/block/capability.rst
index 2f1729424ef4..2cf258d64bbe 100644
--- a/Documentation/block/capability.txt
+++ b/Documentation/block/capability.rst
@@ -1,15 +1,18 @@
+===============================
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
- 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.
+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.
diff --git a/Documentation/block/cmdline-partition.txt b/Documentation/block/cmdline-partition.rst
similarity index 92%
rename from Documentation/block/cmdline-partition.txt
rename to Documentation/block/cmdline-partition.rst
index 760a3f7c3ed4..530bedff548a 100644
--- a/Documentation/block/cmdline-partition.txt
+++ b/Documentation/block/cmdline-partition.rst
@@ -1,5 +1,6 @@
+==============================================
Embedded device command line partition parsing
-=====================================================================
+==============================================
The "blkdevparts" command line option adds support for reading the
block device partition table from the kernel command line.
@@ -22,12 +23,15 @@ blkdevparts=<blkdev-def>[;<blkdev-def>]
<size>
partition size, in bytes, such as: 512, 1m, 1G.
size may contain an optional suffix of (upper or lower case):
+
K, M, G, T, P, E.
+
"-" is used to denote all remaining space.
<offset>
partition start address, in bytes.
offset may contain an optional suffix of (upper or lower case):
+
K, M, G, T, P, E.
(part-name)
@@ -36,11 +40,14 @@ blkdevparts=<blkdev-def>[;<blkdev-def>]
User space application can access partition by partition name.
Example:
+
eMMC disk names are "mmcblk0" and "mmcblk0boot0".
- bootargs:
+ bootargs::
+
'blkdevparts=mmcblk0:1G(data0),1G(data1),-;mmcblk0boot0:1m(boot),-(kernel)'
- dmesg:
+ dmesg::
+
mmcblk0: p1(data0) p2(data1) p3()
mmcblk0boot0: p1(boot) p2(kernel)
diff --git a/Documentation/block/data-integrity.txt b/Documentation/block/data-integrity.rst
similarity index 91%
rename from Documentation/block/data-integrity.txt
rename to Documentation/block/data-integrity.rst
index 934c44ea0c57..4f2452a95c43 100644
--- a/Documentation/block/data-integrity.txt
+++ b/Documentation/block/data-integrity.rst
@@ -1,5 +1,9 @@
-----------------------------------------------------------------------
-1. INTRODUCTION
+==============
+Data Integrity
+==============
+
+1. Introduction
+===============
Modern filesystems feature checksumming of data and metadata to
protect against data corruption. However, the detection of the
@@ -28,8 +32,8 @@ integrity of the I/O and reject it if corruption is detected. This
allows not only corruption prevention but also isolation of the point
of failure.
-----------------------------------------------------------------------
-2. THE DATA INTEGRITY EXTENSIONS
+2. The Data Integrity Extensions
+================================
As written, the protocol extensions only protect the path between
controller and storage device. However, many controllers actually
@@ -75,8 +79,8 @@ Extensions. As these extensions are outside the scope of the protocol
bodies (T10, T13), Oracle and its partners are trying to standardize
them within the Storage Networking Industry Association.
-----------------------------------------------------------------------
-3. KERNEL CHANGES
+3. Kernel Changes
+=================
The data integrity framework in Linux enables protection information
to be pinned to I/Os and sent to/received from controllers that
@@ -123,10 +127,11 @@ access to manipulate the tags from user space. A passthrough
interface for this is being worked on.
-----------------------------------------------------------------------
-4. BLOCK LAYER IMPLEMENTATION DETAILS
+4. Block Layer Implementation Details
+=====================================
-4.1 BIO
+4.1 Bio
+-------
The data integrity patches add a new field to struct bio when
CONFIG_BLK_DEV_INTEGRITY is enabled. bio_integrity(bio) returns a
@@ -145,7 +150,8 @@ attached using bio_integrity_add_page().
bio_free() will automatically free the bip.
-4.2 BLOCK DEVICE
+4.2 Block Device
+----------------
Because the format of the protection data is tied to the physical
disk, each block device has been extended with a block integrity
@@ -163,10 +169,11 @@ and MD linear, RAID0 and RAID1 are currently supported. RAID4/5/6
will require extra work due to the application tag.
-----------------------------------------------------------------------
-5.0 BLOCK LAYER INTEGRITY API
+5.0 Block Layer Integrity API
+=============================
-5.1 NORMAL FILESYSTEM
+5.1 Normal Filesystem
+---------------------
The normal filesystem is unaware that the underlying block device
is capable of sending/receiving integrity metadata. The IMD will
@@ -174,25 +181,26 @@ will require extra work due to the application tag.
in case of a WRITE. A READ request will cause the I/O integrity
to be verified upon completion.
- IMD generation and verification can be toggled using the
+ IMD generation and verification can be toggled using the::
/sys/block/<bdev>/integrity/write_generate
- and
+ and::
/sys/block/<bdev>/integrity/read_verify
flags.
-5.2 INTEGRITY-AWARE FILESYSTEM
+5.2 Integrity-Aware Filesystem
+------------------------------
A filesystem that is integrity-aware can prepare I/Os with IMD
attached. It can also use the application tag space if this is
supported by the block device.
- bool bio_integrity_prep(bio);
+ `bool bio_integrity_prep(bio);`
To generate IMD for WRITE and to set up buffers for READ, the
filesystem must call bio_integrity_prep(bio).
@@ -204,14 +212,15 @@ will require extra work due to the application tag.
Complete bio with error if prepare failed for some reson.
-5.3 PASSING EXISTING INTEGRITY METADATA
+5.3 Passing Existing Integrity Metadata
+---------------------------------------
Filesystems that either generate their own integrity metadata or
are capable of transferring IMD from user space can use the
following calls:
- struct bip * bio_integrity_alloc(bio, gfp_mask, nr_pages);
+ `struct bip * bio_integrity_alloc(bio, gfp_mask, nr_pages);`
Allocates the bio integrity payload and hangs it off of the bio.
nr_pages indicate how many pages of protection data need to be
@@ -220,7 +229,7 @@ will require extra work due to the application tag.
The integrity payload will be freed at bio_free() time.
- int bio_integrity_add_page(bio, page, len, offset);
+ `int bio_integrity_add_page(bio, page, len, offset);`
Attaches a page containing integrity metadata to an existing
bio. The bio must have an existing bip,
@@ -241,21 +250,21 @@ will require extra work due to the application tag.
integrity upon completion.
-5.4 REGISTERING A BLOCK DEVICE AS CAPABLE OF EXCHANGING INTEGRITY
- METADATA
+5.4 Registering A Block Device As Capable Of Exchanging Integrity Metadata
+--------------------------------------------------------------------------
To enable integrity exchange on a block device the gendisk must be
registered as capable:
- int blk_integrity_register(gendisk, blk_integrity);
+ `int blk_integrity_register(gendisk, blk_integrity);`
The blk_integrity struct is a template and should contain the
- following:
+ following::
static struct blk_integrity my_profile = {
.name = "STANDARDSBODY-TYPE-VARIANT-CSUM",
.generate_fn = my_generate_fn,
- .verify_fn = my_verify_fn,
+ .verify_fn = my_verify_fn,
.tuple_size = sizeof(struct my_tuple_size),
.tag_size = <tag bytes per hw sector>,
};
@@ -278,4 +287,5 @@ will require extra work due to the application tag.
0 depending on the value of the Control Mode Page ATO bit.
----------------------------------------------------------------------
+
2007-12-24 Martin K. Petersen <martin.petersen@oracle.com>
diff --git a/Documentation/block/deadline-iosched.txt b/Documentation/block/deadline-iosched.rst
similarity index 89%
rename from Documentation/block/deadline-iosched.txt
rename to Documentation/block/deadline-iosched.rst
index 2d82c80322cb..9f5c5a4c370e 100644
--- a/Documentation/block/deadline-iosched.txt
+++ b/Documentation/block/deadline-iosched.rst
@@ -1,3 +1,4 @@
+==============================
Deadline IO scheduler tunables
==============================
@@ -7,15 +8,13 @@ of interest to power users.
Selecting IO schedulers
-----------------------
-Refer to Documentation/block/switching-sched.txt for information on
+Refer to Documentation/block/switching-sched.rst for information on
selecting an io scheduler on a per-device basis.
-
-********************************************************************************
-
+------------------------------------------------------------------------------
read_expire (in ms)
------------
+-----------------------
The goal of the deadline io scheduler is to attempt to guarantee a start
service time for a request. As we focus mainly on read latencies, this is
@@ -25,15 +24,15 @@ milliseconds.
write_expire (in ms)
------------
+-----------------------
Similar to read_expire mentioned above, but for writes.
fifo_batch (number of requests)
-----------
+------------------------------------
-Requests are grouped into ``batches'' of a particular data direction (read or
+Requests are grouped into ``batches`` of a particular data direction (read or
write) which are serviced in increasing sector order. To limit extra seeking,
deadline expiries are only checked between batches. fifo_batch controls the
maximum number of requests per batch.
@@ -45,7 +44,7 @@ generally improves throughput, at the cost of latency variation.
writes_starved (number of dispatches)
---------------
+--------------------------------------
When we have to move requests from the io scheduler queue to the block
device dispatch queue, we always give a preference to reads. However, we
@@ -56,7 +55,7 @@ same criteria as reads.
front_merges (bool)
-------------
+----------------------
Sometimes it happens that a request enters the io scheduler that is contiguous
with a request that is already on the queue. Either it fits in the back of that
@@ -71,5 +70,3 @@ rbtree front sector lookup when the io scheduler merge function is called.
Nov 11 2002, Jens Axboe <jens.axboe@oracle.com>
-
-
diff --git a/Documentation/block/index.rst b/Documentation/block/index.rst
new file mode 100644
index 000000000000..8cd226a0e86e
--- /dev/null
+++ b/Documentation/block/index.rst
@@ -0,0 +1,25 @@
+:orphan:
+
+=====
+Block
+=====
+
+.. toctree::
+ :maxdepth: 1
+
+ bfq-iosched
+ biodoc
+ biovecs
+ capability
+ cmdline-partition
+ data-integrity
+ deadline-iosched
+ ioprio
+ kyber-iosched
+ null_blk
+ pr
+ queue-sysfs
+ request
+ stat
+ switching-sched
+ writeback_cache_control
diff --git a/Documentation/block/ioprio.txt b/Documentation/block/ioprio.rst
similarity index 75%
rename from Documentation/block/ioprio.txt
rename to Documentation/block/ioprio.rst
index 8ed8c59380b4..f72b0de65af7 100644
--- a/Documentation/block/ioprio.txt
+++ b/Documentation/block/ioprio.rst
@@ -1,3 +1,4 @@
+===================
Block io priorities
===================
@@ -40,81 +41,81 @@ class data, since it doesn't really apply here.
Tools
-----
-See below for a sample ionice tool. Usage:
+See below for a sample ionice tool. Usage::
-# ionice -c<class> -n<level> -p<pid>
+ # ionice -c<class> -n<level> -p<pid>
If pid isn't given, the current process is assumed. IO priority settings
are inherited on fork, so you can use ionice to start the process at a given
-level:
+level::
-# ionice -c2 -n0 /bin/ls
+ # ionice -c2 -n0 /bin/ls
will run ls at the best-effort scheduling class at the highest priority.
-For a running process, you can give the pid instead:
+For a running process, you can give the pid instead::
-# ionice -c1 -n2 -p100
+ # ionice -c1 -n2 -p100
will change pid 100 to run at the realtime scheduling class, at priority 2.
----> snip ionice.c tool <---
+ionice.c tool::
-#include <stdio.h>
-#include <stdlib.h>
-#include <errno.h>
-#include <getopt.h>
-#include <unistd.h>
-#include <sys/ptrace.h>
-#include <asm/unistd.h>
+ #include <stdio.h>
+ #include <stdlib.h>
+ #include <errno.h>
+ #include <getopt.h>
+ #include <unistd.h>
+ #include <sys/ptrace.h>
+ #include <asm/unistd.h>
-extern int sys_ioprio_set(int, int, int);
-extern int sys_ioprio_get(int, int);
+ extern int sys_ioprio_set(int, int, int);
+ extern int sys_ioprio_get(int, int);
-#if defined(__i386__)
-#define __NR_ioprio_set 289
-#define __NR_ioprio_get 290
-#elif defined(__ppc__)
-#define __NR_ioprio_set 273
-#define __NR_ioprio_get 274
-#elif defined(__x86_64__)
-#define __NR_ioprio_set 251
-#define __NR_ioprio_get 252
-#elif defined(__ia64__)
-#define __NR_ioprio_set 1274
-#define __NR_ioprio_get 1275
-#else
-#error "Unsupported arch"
-#endif
+ #if defined(__i386__)
+ #define __NR_ioprio_set 289
+ #define __NR_ioprio_get 290
+ #elif defined(__ppc__)
+ #define __NR_ioprio_set 273
+ #define __NR_ioprio_get 274
+ #elif defined(__x86_64__)
+ #define __NR_ioprio_set 251
+ #define __NR_ioprio_get 252
+ #elif defined(__ia64__)
+ #define __NR_ioprio_set 1274
+ #define __NR_ioprio_get 1275
+ #else
+ #error "Unsupported arch"
+ #endif
-static inline int ioprio_set(int which, int who, int ioprio)
-{
+ static inline int ioprio_set(int which, int who, int ioprio)
+ {
return syscall(__NR_ioprio_set, which, who, ioprio);
-}
+ }
-static inline int ioprio_get(int which, int who)
-{
+ static inline int ioprio_get(int which, int who)
+ {
return syscall(__NR_ioprio_get, which, who);
-}
+ }
-enum {
+ enum {
IOPRIO_CLASS_NONE,
IOPRIO_CLASS_RT,
IOPRIO_CLASS_BE,
IOPRIO_CLASS_IDLE,
-};
+ };
-enum {
+ enum {
IOPRIO_WHO_PROCESS = 1,
IOPRIO_WHO_PGRP,
IOPRIO_WHO_USER,
-};
+ };
-#define IOPRIO_CLASS_SHIFT 13
+ #define IOPRIO_CLASS_SHIFT 13
-const char *to_prio[] = { "none", "realtime", "best-effort", "idle", };
+ const char *to_prio[] = { "none", "realtime", "best-effort", "idle", };
-int main(int argc, char *argv[])
-{
+ int main(int argc, char *argv[])
+ {
int ioprio = 4, set = 0, ioprio_class = IOPRIO_CLASS_BE;
int c, pid = 0;
@@ -175,9 +176,7 @@ int main(int argc, char *argv[])
}
return 0;
-}
-
----> snip ionice.c tool <---
+ }
March 11 2005, Jens Axboe <jens.axboe@oracle.com>
diff --git a/Documentation/block/kyber-iosched.txt b/Documentation/block/kyber-iosched.rst
similarity index 86%
rename from Documentation/block/kyber-iosched.txt
rename to Documentation/block/kyber-iosched.rst
index e94feacd7edc..3e164dd0617c 100644
--- a/Documentation/block/kyber-iosched.txt
+++ b/Documentation/block/kyber-iosched.rst
@@ -1,5 +1,6 @@
+============================
Kyber I/O scheduler tunables
-===========================
+============================
The only two tunables for the Kyber scheduler are the target latencies for
reads and synchronous writes. Kyber will throttle requests in order to meet
diff --git a/Documentation/block/null_blk.txt b/Documentation/block/null_blk.rst
similarity index 60%
rename from Documentation/block/null_blk.txt
rename to Documentation/block/null_blk.rst
index 41f0a3d33bbd..31451d80783c 100644
--- a/Documentation/block/null_blk.txt
+++ b/Documentation/block/null_blk.rst
@@ -1,33 +1,43 @@
+========================
Null block device driver
-================================================================================
+========================
-I. Overview
+1. Overview
+===========
The null block device (/dev/nullb*) is used for benchmarking the various
block-layer implementations. It emulates a block device of X gigabytes in size.
The following instances are possible:
Single-queue block-layer
+
- Request-based.
- Single submission queue per device.
- Implements IO scheduling algorithms (CFQ, Deadline, noop).
+
Multi-queue block-layer
+
- Request-based.
- Configurable submission queues per device.
+
No block-layer (Known as bio-based)
+
- Bio-based. IO requests are submitted directly to the device driver.
- Directly accepts bio data structure and returns them.
All of them have a completion queue for each core in the system.
-II. Module parameters applicable for all instances:
+2. Module parameters applicable for all instances
+=================================================
queue_mode=[0-2]: Default: 2-Multi-queue
Selects which block-layer the module should instantiate with.
- 0: Bio-based.
- 1: Single-queue.
- 2: Multi-queue.
+ = ============
+ 0 Bio-based
+ 1 Single-queue
+ 2 Multi-queue
+ = ============
home_node=[0--nr_nodes]: Default: NUMA_NO_NODE
Selects what CPU node the data structures are allocated from.
@@ -45,12 +55,14 @@ nr_devices=[Number of devices]: Default: 1
irqmode=[0-2]: Default: 1-Soft-irq
The completion mode used for completing IOs to the block-layer.
- 0: None.
- 1: Soft-irq. Uses IPI to complete IOs across CPU nodes. Simulates the overhead
+ = ===========================================================================
+ 0 None.
+ 1 Soft-irq. Uses IPI to complete IOs across CPU nodes. Simulates the overhead
when IOs are issued from another CPU node than the home the device is
connected to.
- 2: Timer: Waits a specific period (completion_nsec) for each IO before
+ 2 Timer: Waits a specific period (completion_nsec) for each IO before
completion.
+ = ===========================================================================
completion_nsec=[ns]: Default: 10,000ns
Combined with irqmode=2 (timer). The time each completion event must wait.
@@ -66,30 +78,45 @@ hw_queue_depth=[0..qdepth]: Default: 64
III: Multi-queue specific parameters
use_per_node_hctx=[0/1]: Default: 0
- 0: The number of submit queues are set to the value of the submit_queues
+
+ = =====================================================================
+ 0 The number of submit queues are set to the value of the submit_queues
parameter.
- 1: The multi-queue block layer is instantiated with a hardware dispatch
+ 1 The multi-queue block layer is instantiated with a hardware dispatch
queue for each CPU node in the system.
+ = =====================================================================
no_sched=[0/1]: Default: 0
- 0: nullb* use default blk-mq io scheduler.
- 1: nullb* doesn't use io scheduler.
+
+ = ======================================
+ 0 nullb* use default blk-mq io scheduler
+ 1 nullb* doesn't use io scheduler
+ = ======================================
blocking=[0/1]: Default: 0
- 0: Register as a non-blocking blk-mq driver device.
- 1: Register as a blocking blk-mq driver device, null_blk will set
+
+ = ===============================================================
+ 0 Register as a non-blocking blk-mq driver device.
+ 1 Register as a blocking blk-mq driver device, null_blk will set
the BLK_MQ_F_BLOCKING flag, indicating that it sometimes/always
needs to block in its ->queue_rq() function.
+ = ===============================================================
shared_tags=[0/1]: Default: 0
- 0: Tag set is not shared.
- 1: Tag set shared between devices for blk-mq. Only makes sense with
+
+ = ================================================================
+ 0 Tag set is not shared.
+ 1 Tag set shared between devices for blk-mq. Only makes sense with
nr_devices > 1, otherwise there's no tag set to share.
+ = ================================================================
zoned=[0/1]: Default: 0
- 0: Block device is exposed as a random-access block device.
- 1: Block device is exposed as a host-managed zoned block device. Requires
+
+ = ======================================================================
+ 0 Block device is exposed as a random-access block device.
+ 1 Block device is exposed as a host-managed zoned block device. Requires
CONFIG_BLK_DEV_ZONED.
+ = ======================================================================
zone_size=[MB]: Default: 256
Per zone size when exposed as a zoned block device. Must be a power of two.
diff --git a/Documentation/block/pr.txt b/Documentation/block/pr.rst
similarity index 93%
rename from Documentation/block/pr.txt
rename to Documentation/block/pr.rst
index ac9b8e70e64b..30ea1c2e39eb 100644
--- a/Documentation/block/pr.txt
+++ b/Documentation/block/pr.rst
@@ -1,4 +1,4 @@
-
+===============================================
Block layer support for Persistent Reservations
===============================================
@@ -23,22 +23,18 @@ The following types of reservations are supported:
--------------------------------------------------
- PR_WRITE_EXCLUSIVE
-
Only the initiator that owns the reservation can write to the
device. Any initiator can read from the device.
- PR_EXCLUSIVE_ACCESS
-
Only the initiator that owns the reservation can access the
device.
- PR_WRITE_EXCLUSIVE_REG_ONLY
-
Only initiators with a registered key can write to the device,
Any initiator can read from the device.
- PR_EXCLUSIVE_ACCESS_REG_ONLY
-
Only initiators with a registered key can access the device.
- PR_WRITE_EXCLUSIVE_ALL_REGS
@@ -48,21 +44,21 @@ The following types of reservations are supported:
All initiators with a registered key are considered reservation
holders.
Please reference the SPC spec on the meaning of a reservation
- holder if you want to use this type.
+ holder if you want to use this type.
- PR_EXCLUSIVE_ACCESS_ALL_REGS
-
Only initiators with a registered key can access the device.
All initiators with a registered key are considered reservation
holders.
Please reference the SPC spec on the meaning of a reservation
- holder if you want to use this type.
+ holder if you want to use this type.
The following ioctl are supported:
----------------------------------
1. IOC_PR_REGISTER
+^^^^^^^^^^^^^^^^^^
This ioctl command registers a new reservation if the new_key argument
is non-null. If no existing reservation exists old_key must be zero,
@@ -74,6 +70,7 @@ in old_key.
2. IOC_PR_RESERVE
+^^^^^^^^^^^^^^^^^
This ioctl command reserves the device and thus restricts access for other
devices based on the type argument. The key argument must be the existing
@@ -82,12 +79,14 @@ IOC_PR_REGISTER_IGNORE, IOC_PR_PREEMPT or IOC_PR_PREEMPT_ABORT commands.
3. IOC_PR_RELEASE
+^^^^^^^^^^^^^^^^^
This ioctl command releases the reservation specified by key and flags
and thus removes any access restriction implied by it.
4. IOC_PR_PREEMPT
+^^^^^^^^^^^^^^^^^
This ioctl command releases the existing reservation referred to by
old_key and replaces it with a new reservation of type for the
@@ -95,11 +94,13 @@ reservation key new_key.
5. IOC_PR_PREEMPT_ABORT
+^^^^^^^^^^^^^^^^^^^^^^^
This ioctl command works like IOC_PR_PREEMPT except that it also aborts
any outstanding command sent over a connection identified by old_key.
6. IOC_PR_CLEAR
+^^^^^^^^^^^^^^^
This ioctl command unregisters both key and any other reservation key
registered with the device and drops any existing reservation.
@@ -111,7 +112,6 @@ Flags
All the ioctls have a flag field. Currently only one flag is supported:
- PR_FL_IGNORE_KEY
-
Ignore the existing reservation key. This is commonly supported for
IOC_PR_REGISTER, and some implementation may support the flag for
IOC_PR_RESERVE.
diff --git a/Documentation/block/queue-sysfs.txt b/Documentation/block/queue-sysfs.rst
similarity index 99%
rename from Documentation/block/queue-sysfs.txt
rename to Documentation/block/queue-sysfs.rst
index 83b457e24bba..9022249208b5 100644
--- a/Documentation/block/queue-sysfs.txt
+++ b/Documentation/block/queue-sysfs.rst
@@ -1,3 +1,4 @@
+=================
Queue sysfs files
=================
@@ -10,7 +11,7 @@ Files denoted with a RO postfix are readonly and the RW postfix means
read-write.
add_random (RW)
-----------------
+---------------
This file allows to turn off the disk entropy contribution. Default
value of this file is '1'(on).
@@ -21,13 +22,13 @@ used by CPU-addressable storage to bypass the pagecache. It shows '1'
if true, '0' if not.
discard_granularity (RO)
------------------------
+------------------------
This shows the size of internal allocation of the device in bytes, if
reported by the device. A value of '0' means device does not support
the discard functionality.
discard_max_hw_bytes (RO)
-----------------------
+-------------------------
Devices that support discard functionality may have internal limits on
the number of bytes that can be trimmed or unmapped in a single operation.
The discard_max_bytes parameter is set by the device driver to the maximum
diff --git a/Documentation/block/request.txt b/Documentation/block/request.rst
similarity index 59%
rename from Documentation/block/request.txt
rename to Documentation/block/request.rst
index 754e104ed369..747021e1ffdb 100644
--- a/Documentation/block/request.txt
+++ b/Documentation/block/request.rst
@@ -1,26 +1,37 @@
-
+============================
struct request documentation
+============================
Jens Axboe <jens.axboe@oracle.com> 27/05/02
-1.0
-Index
-2.0 Struct request members classification
+.. FIXME:
+ No idea about what does mean - seems just some noise, so comment it
- 2.1 struct request members explanation
+ 1.0
+ Index
+
+ 2.0 Struct request members classification
+
+ 2.1 struct request members explanation
+
+ 3.0
+
+
+ 2.0
-3.0
-2.0
Short explanation of request members
+====================================
Classification flags:
+ = ====================
D driver member
B block layer member
I I/O scheduler member
+ = ====================
Unless an entry contains a D classification, a device driver must not access
this member. Some members may contain D classifications, but should only be
@@ -28,14 +39,13 @@ access through certain macros or functions (eg ->flags).
<linux/blkdev.h>
-2.1
+=============================== ======= =======================================
Member Flag Comment
------- ---- -------
-
+=============================== ======= =======================================
struct list_head queuelist BI Organization on various internal
queues
-void *elevator_private I I/O scheduler private data
+``void *elevator_private`` I I/O scheduler private data
unsigned char cmd[16] D Driver can use this for setting up
a cdb before execution, see
@@ -71,18 +81,19 @@ unsigned int hard_cur_sectors B Used to keep current_nr_sectors sane
int tag DB TCQ tag, if assigned
-void *special D Free to be used by driver
+``void *special`` D Free to be used by driver
-char *buffer D Map of first segment, also see
+``char *buffer`` D Map of first segment, also see
section on bouncing SECTION
-struct completion *waiting D Can be used by driver to get signalled
+``struct completion *waiting`` D Can be used by driver to get signalled
on request completion
-struct bio *bio DBI First bio in request
+``struct bio *bio`` DBI First bio in request
-struct bio *biotail DBI Last bio in request
+``struct bio *biotail`` DBI Last bio in request
-struct request_queue *q DB Request queue this request belongs to
+``struct request_queue *q`` DB Request queue this request belongs to
-struct request_list *rl B Request list this request came from
+``struct request_list *rl`` B Request list this request came from
+=============================== ======= =======================================
diff --git a/Documentation/block/stat.txt b/Documentation/block/stat.rst
similarity index 89%
rename from Documentation/block/stat.txt
rename to Documentation/block/stat.rst
index 0aace9cc536c..9c07bc22b0bc 100644
--- a/Documentation/block/stat.txt
+++ b/Documentation/block/stat.rst
@@ -1,3 +1,4 @@
+===============================================
Block layer statistics in /sys/block/<dev>/stat
===============================================
@@ -6,9 +7,12 @@ This file documents the contents of the /sys/block/<dev>/stat file.
The stat file provides several statistics about the state of block
device <dev>.
-Q. Why are there multiple statistics in a single file? Doesn't sysfs
+Q.
+ Why are there multiple statistics in a single file? Doesn't sysfs
normally contain a single value per file?
-A. By having a single file, the kernel can guarantee that the statistics
+
+A.
+ By having a single file, the kernel can guarantee that the statistics
represent a consistent snapshot of the state of the device. If the
statistics were exported as multiple files containing one statistic
each, it would be impossible to guarantee that a set of readings
@@ -18,8 +22,10 @@ The stat file consists of a single line of text containing 11 decimal
values separated by whitespace. The fields are summarized in the
following table, and described in more detail below.
+
+=============== ============= =================================================
Name units description
----- ----- -----------
+=============== ============= =================================================
read I/Os requests number of read I/Os processed
read merges requests number of read I/Os merged with in-queue I/O
read sectors sectors number of sectors read
@@ -35,6 +41,7 @@ discard I/Os requests number of discard I/Os processed
discard merges requests number of discard I/Os merged with in-queue I/O
discard sectors sectors number of sectors discarded
discard ticks milliseconds total wait time for discard requests
+=============== ============= =================================================
read I/Os, write I/Os, discard I/0s
===================================
diff --git a/Documentation/block/switching-sched.txt b/Documentation/block/switching-sched.rst
similarity index 67%
rename from Documentation/block/switching-sched.txt
rename to Documentation/block/switching-sched.rst
index 7977f6fb8b20..42042417380e 100644
--- a/Documentation/block/switching-sched.txt
+++ b/Documentation/block/switching-sched.rst
@@ -1,35 +1,39 @@
+===================
+Switching Scheduler
+===================
+
To choose IO schedulers at boot time, use the argument 'elevator=deadline'.
'noop' and 'cfq' (the default) are also available. IO schedulers are assigned
globally at boot time only presently.
Each io queue has a set of io scheduler tunables associated with it. These
tunables control how the io scheduler works. You can find these entries
-in:
+in::
-/sys/block/<device>/queue/iosched
+ /sys/block/<device>/queue/iosched
assuming that you have sysfs mounted on /sys. If you don't have sysfs mounted,
-you can do so by typing:
+you can do so by typing::
-# mount none /sys -t sysfs
+ # mount none /sys -t sysfs
It is possible to change the IO scheduler for a given block device on
the fly to select one of mq-deadline, none, bfq, or kyber schedulers -
which can improve that device's throughput.
-To set a specific scheduler, simply do this:
+To set a specific scheduler, simply do this::
-echo SCHEDNAME > /sys/block/DEV/queue/scheduler
+ echo SCHEDNAME > /sys/block/DEV/queue/scheduler
where SCHEDNAME is the name of a defined IO scheduler, and DEV is the
device name (hda, hdb, sga, or whatever you happen to have).
The list of defined schedulers can be found by simply doing
a "cat /sys/block/DEV/queue/scheduler" - the list of valid names
-will be displayed, with the currently selected scheduler in brackets:
+will be displayed, with the currently selected scheduler in brackets::
-# cat /sys/block/sda/queue/scheduler
-[mq-deadline] kyber bfq none
-# echo none >/sys/block/sda/queue/scheduler
-# cat /sys/block/sda/queue/scheduler
-[none] mq-deadline kyber bfq
+ # cat /sys/block/sda/queue/scheduler
+ [mq-deadline] kyber bfq none
+ # echo none >/sys/block/sda/queue/scheduler
+ # cat /sys/block/sda/queue/scheduler
+ [none] mq-deadline kyber bfq
diff --git a/Documentation/block/writeback_cache_control.txt b/Documentation/block/writeback_cache_control.rst
similarity index 94%
rename from Documentation/block/writeback_cache_control.txt
rename to Documentation/block/writeback_cache_control.rst
index 8a6bdada5f6b..2c752c57c14c 100644
--- a/Documentation/block/writeback_cache_control.txt
+++ b/Documentation/block/writeback_cache_control.rst
@@ -1,6 +1,6 @@
-
+==========================================
Explicit volatile write back cache control
-=====================================
+==========================================
Introduction
------------
@@ -31,7 +31,7 @@ the blkdev_issue_flush() helper for a pure cache flush.
Forced Unit Access
------------------
+------------------
The REQ_FUA flag can be OR ed into the r/w flags of a bio submitted from the
filesystem and will make sure that I/O completion for this request is only
@@ -62,14 +62,14 @@ flags themselves without any help from the block layer.
Implementation details for request_fn based block drivers
---------------------------------------------------------------
+---------------------------------------------------------
For devices that do not support volatile write caches there is no driver
support required, the block layer completes empty REQ_PREFLUSH requests before
entering the driver and strips off the REQ_PREFLUSH and REQ_FUA bits from
requests that have a payload. For devices with volatile write caches the
driver needs to tell the block layer that it supports flushing caches by
-doing:
+doing::
blk_queue_write_cache(sdkp->disk->queue, true, false);
@@ -77,7 +77,7 @@ and handle empty REQ_OP_FLUSH requests in its prep_fn/request_fn. Note that
REQ_PREFLUSH requests with a payload are automatically turned into a sequence
of an empty REQ_OP_FLUSH request followed by the actual write by the block
layer. For devices that also support the FUA bit the block layer needs
-to be told to pass through the REQ_FUA bit using:
+to be told to pass through the REQ_FUA bit using::
blk_queue_write_cache(sdkp->disk->queue, true, true);
diff --git a/Documentation/blockdev/zram.rst b/Documentation/blockdev/zram.rst
index 2111231c9c0f..6eccf13219ff 100644
--- a/Documentation/blockdev/zram.rst
+++ b/Documentation/blockdev/zram.rst
@@ -215,7 +215,7 @@ User space is advised to use the following files to read the device statistics.
File /sys/block/zram<id>/stat
-Represents block layer statistics. Read Documentation/block/stat.txt for
+Represents block layer statistics. Read Documentation/block/stat.rst for
details.
File /sys/block/zram<id>/io_stat
diff --git a/MAINTAINERS b/MAINTAINERS
index 2f8e1543caff..d850d7f15a38 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -2930,7 +2930,7 @@ M: Jens Axboe <axboe@kernel.dk>
L: linux-block@vger.kernel.org
S: Maintained
F: block/bfq-*
-F: Documentation/block/bfq-iosched.txt
+F: Documentation/block/bfq-iosched.rst
BFS FILE SYSTEM
M: "Tigran A. Aivazian" <aivazian.tigran@gmail.com>
diff --git a/block/Kconfig b/block/Kconfig
index 56cb1695cd87..b16b3e075d31 100644
--- a/block/Kconfig
+++ b/block/Kconfig
@@ -110,7 +110,7 @@ config BLK_CMDLINE_PARSER
which don't otherwise have any standardized method for listing the
partitions on a block device.
- See Documentation/block/cmdline-partition.txt for more information.
+ See Documentation/block/cmdline-partition.rst for more information.
config BLK_WBT
bool "Enable support for block device writeback throttling"
diff --git a/block/Kconfig.iosched b/block/Kconfig.iosched
index 4626b88b2d5a..eabd4328b228 100644
--- a/block/Kconfig.iosched
+++ b/block/Kconfig.iosched
@@ -26,7 +26,7 @@ config IOSCHED_BFQ
regardless of the device parameters and with any workload. It
also guarantees a low latency to interactive and soft
real-time applications. Details in
- Documentation/block/bfq-iosched.txt
+ Documentation/block/bfq-iosched.rst
config BFQ_GROUP_IOSCHED
bool "BFQ hierarchical scheduling support"
diff --git a/block/bfq-iosched.c b/block/bfq-iosched.c
index f8d430f88d25..37996013a301 100644
--- a/block/bfq-iosched.c
+++ b/block/bfq-iosched.c
@@ -17,7 +17,7 @@
* low-latency capabilities. BFQ also supports full hierarchical
* scheduling through cgroups. Next paragraphs provide an introduction
* on BFQ inner workings. Details on BFQ benefits, usage and
- * limitations can be found in Documentation/block/bfq-iosched.txt.
+ * limitations can be found in Documentation/block/bfq-iosched.rst.
*
* BFQ is a proportional-share storage-I/O scheduling algorithm based
* on the slice-by-slice service scheme of CFQ. But BFQ assigns
diff --git a/block/blk-integrity.c b/block/blk-integrity.c
index 825c9c070458..ca39b4624cf8 100644
--- a/block/blk-integrity.c
+++ b/block/blk-integrity.c
@@ -383,7 +383,7 @@ static const struct blk_integrity_profile nop_profile = {
* send/receive integrity metadata it must use this function to register
* the capability with the block layer. The template is a blk_integrity
* struct with values appropriate for the underlying hardware. See
- * Documentation/block/data-integrity.txt.
+ * Documentation/block/data-integrity.rst.
*/
void blk_integrity_register(struct gendisk *disk, struct blk_integrity *template)
{
diff --git a/block/ioprio.c b/block/ioprio.c
index 2e0559f157c8..77bcab11dce5 100644
--- a/block/ioprio.c
+++ b/block/ioprio.c
@@ -17,7 +17,7 @@
*
* ioprio_set(PRIO_PROCESS, pid, prio);
*
- * See also Documentation/block/ioprio.txt
+ * See also Documentation/block/ioprio.rst
*
*/
#include <linux/gfp.h>
diff --git a/block/mq-deadline.c b/block/mq-deadline.c
index 1876f5712bfd..4fa0ae242880 100644
--- a/block/mq-deadline.c
+++ b/block/mq-deadline.c
@@ -25,7 +25,7 @@
#include "blk-mq-sched.h"
/*
- * See Documentation/block/deadline-iosched.txt
+ * See Documentation/block/deadline-iosched.rst
*/
static const int read_expire = HZ / 2; /* max time before a read is submitted. */
static const int write_expire = 5 * HZ; /* ditto for writes, these limits are SOFT! */
diff --git a/block/partitions/cmdline.c b/block/partitions/cmdline.c
index 60fb3df9897c..f1edd5452249 100644
--- a/block/partitions/cmdline.c
+++ b/block/partitions/cmdline.c
@@ -11,7 +11,7 @@
*
* The format for the command line is just like mtdparts.
*
- * For further information, see "Documentation/block/cmdline-partition.txt"
+ * For further information, see "Documentation/block/cmdline-partition.rst"
*
*/
--
2.21.0
^ permalink raw reply related
* [PATCH v1 05/22] docs: rapidio: convert to ReST
From: Mauro Carvalho Chehab @ 2019-06-18 21:05 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Matt Porter, Alexandre Bounine
In-Reply-To: <cover.1560891322.git.mchehab+samsung@kernel.org>
Rename the rapidio documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.
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: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/rapidio/index.rst | 15 +++++
.../{mport_cdev.txt => mport_cdev.rst} | 47 ++++++-------
.../rapidio/{rapidio.txt => rapidio.rst} | 39 +++++++----
.../rapidio/{rio_cm.txt => rio_cm.rst} | 66 ++++++++++++-------
.../rapidio/{sysfs.txt => sysfs.rst} | 4 ++
.../rapidio/{tsi721.txt => tsi721.rst} | 45 ++++++++-----
drivers/rapidio/Kconfig | 2 +-
7 files changed, 141 insertions(+), 77 deletions(-)
create mode 100644 Documentation/rapidio/index.rst
rename Documentation/rapidio/{mport_cdev.txt => mport_cdev.rst} (84%)
rename Documentation/rapidio/{rapidio.txt => rapidio.rst} (97%)
rename Documentation/rapidio/{rio_cm.txt => rio_cm.rst} (76%)
rename Documentation/rapidio/{sysfs.txt => sysfs.rst} (75%)
rename Documentation/rapidio/{tsi721.txt => tsi721.rst} (79%)
diff --git a/Documentation/rapidio/index.rst b/Documentation/rapidio/index.rst
new file mode 100644
index 000000000000..ab7b5541b346
--- /dev/null
+++ b/Documentation/rapidio/index.rst
@@ -0,0 +1,15 @@
+:orphan:
+
+===========================
+The Linux RapidIO Subsystem
+===========================
+
+.. toctree::
+ :maxdepth: 1
+
+ rapidio
+ sysfs
+
+ tsi721
+ mport_cdev
+ rio_cm
diff --git a/Documentation/rapidio/mport_cdev.txt b/Documentation/rapidio/mport_cdev.rst
similarity index 84%
rename from Documentation/rapidio/mport_cdev.txt
rename to Documentation/rapidio/mport_cdev.rst
index a53f786ee2e9..df77a7f7be7d 100644
--- a/Documentation/rapidio/mport_cdev.txt
+++ b/Documentation/rapidio/mport_cdev.rst
@@ -1,13 +1,9 @@
+==================================================================
RapidIO subsystem mport character device driver (rio_mport_cdev.c)
==================================================================
-Version History:
-----------------
- 1.0.0 - Initial driver release.
-
-==================================================================
-
-I. Overview
+1. Overview
+===========
This device driver is the result of collaboration within the RapidIO.org
Software Task Group (STG) between Texas Instruments, Freescale,
@@ -29,40 +25,41 @@ Using available set of ioctl commands user-space applications can perform
following RapidIO bus and subsystem operations:
- Reads and writes from/to configuration registers of mport devices
- (RIO_MPORT_MAINT_READ_LOCAL/RIO_MPORT_MAINT_WRITE_LOCAL)
+ (RIO_MPORT_MAINT_READ_LOCAL/RIO_MPORT_MAINT_WRITE_LOCAL)
- Reads and writes from/to configuration registers of remote RapidIO devices.
This operations are defined as RapidIO Maintenance reads/writes in RIO spec.
- (RIO_MPORT_MAINT_READ_REMOTE/RIO_MPORT_MAINT_WRITE_REMOTE)
+ (RIO_MPORT_MAINT_READ_REMOTE/RIO_MPORT_MAINT_WRITE_REMOTE)
- Set RapidIO Destination ID for mport devices (RIO_MPORT_MAINT_HDID_SET)
- Set RapidIO Component Tag for mport devices (RIO_MPORT_MAINT_COMPTAG_SET)
- Query logical index of mport devices (RIO_MPORT_MAINT_PORT_IDX_GET)
- Query capabilities and RapidIO link configuration of mport devices
- (RIO_MPORT_GET_PROPERTIES)
+ (RIO_MPORT_GET_PROPERTIES)
- Enable/Disable reporting of RapidIO doorbell events to user-space applications
- (RIO_ENABLE_DOORBELL_RANGE/RIO_DISABLE_DOORBELL_RANGE)
+ (RIO_ENABLE_DOORBELL_RANGE/RIO_DISABLE_DOORBELL_RANGE)
- Enable/Disable reporting of RIO port-write events to user-space applications
- (RIO_ENABLE_PORTWRITE_RANGE/RIO_DISABLE_PORTWRITE_RANGE)
+ (RIO_ENABLE_PORTWRITE_RANGE/RIO_DISABLE_PORTWRITE_RANGE)
- Query/Control type of events reported through this driver: doorbells,
port-writes or both (RIO_SET_EVENT_MASK/RIO_GET_EVENT_MASK)
- Configure/Map mport's outbound requests window(s) for specific size,
RapidIO destination ID, hopcount and request type
- (RIO_MAP_OUTBOUND/RIO_UNMAP_OUTBOUND)
+ (RIO_MAP_OUTBOUND/RIO_UNMAP_OUTBOUND)
- Configure/Map mport's inbound requests window(s) for specific size,
RapidIO base address and local memory base address
- (RIO_MAP_INBOUND/RIO_UNMAP_INBOUND)
+ (RIO_MAP_INBOUND/RIO_UNMAP_INBOUND)
- Allocate/Free contiguous DMA coherent memory buffer for DMA data transfers
to/from remote RapidIO devices (RIO_ALLOC_DMA/RIO_FREE_DMA)
- Initiate DMA data transfers to/from remote RapidIO devices (RIO_TRANSFER).
Supports blocking, asynchronous and posted (a.k.a 'fire-and-forget') data
transfer modes.
- Check/Wait for completion of asynchronous DMA data transfer
- (RIO_WAIT_FOR_ASYNC)
+ (RIO_WAIT_FOR_ASYNC)
- Manage device objects supported by RapidIO subsystem (RIO_DEV_ADD/RIO_DEV_DEL).
This allows implementation of various RapidIO fabric enumeration algorithms
as user-space applications while using remaining functionality provided by
kernel RapidIO subsystem.
-II. Hardware Compatibility
+2. Hardware Compatibility
+=========================
This device driver uses standard interfaces defined by kernel RapidIO subsystem
and therefore it can be used with any mport device driver registered by RapidIO
@@ -78,29 +75,35 @@ functionality of their platform when planning to use this driver:
specific DMA engine support and therefore DMA data transfers mport_cdev driver
are not available.
-III. Module parameters
+3. Module parameters
+====================
-- 'dma_timeout' - DMA transfer completion timeout (in msec, default value 3000).
+- 'dma_timeout'
+ - DMA transfer completion timeout (in msec, default value 3000).
This parameter set a maximum completion wait time for SYNC mode DMA
transfer requests and for RIO_WAIT_FOR_ASYNC ioctl requests.
-- 'dbg_level' - This parameter allows to control amount of debug information
+- 'dbg_level'
+ - This parameter allows to control amount of debug information
generated by this device driver. This parameter is formed by set of
bit masks that correspond to the specific functional blocks.
For mask definitions see 'drivers/rapidio/devices/rio_mport_cdev.c'
This parameter can be changed dynamically.
Use CONFIG_RAPIDIO_DEBUG=y to enable debug output at the top level.
-IV. Known problems
+4. Known problems
+=================
None.
-V. User-space Applications and API
+5. User-space Applications and API
+==================================
API library and applications that use this device driver are available from
RapidIO.org.
-VI. TODO List
+6. TODO List
+============
- Add support for sending/receiving "raw" RapidIO messaging packets.
- Add memory mapped DMA data transfers as an option when RapidIO-specific DMA
diff --git a/Documentation/rapidio/rapidio.txt b/Documentation/rapidio/rapidio.rst
similarity index 97%
rename from Documentation/rapidio/rapidio.txt
rename to Documentation/rapidio/rapidio.rst
index 28fbd877f85a..fb8942d3ba85 100644
--- a/Documentation/rapidio/rapidio.txt
+++ b/Documentation/rapidio/rapidio.rst
@@ -1,6 +1,6 @@
- The Linux RapidIO Subsystem
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+============
+Introduction
+============
The RapidIO standard is a packet-based fabric interconnect standard designed for
use in embedded systems. Development of the RapidIO standard is directed by the
@@ -11,7 +11,7 @@ This document describes the basics of the Linux RapidIO subsystem and provides
information on its major components.
1 Overview
-----------
+==========
Because the RapidIO subsystem follows the Linux device model it is integrated
into the kernel similarly to other buses by defining RapidIO-specific device and
@@ -22,7 +22,7 @@ architecture-specific interfaces that provide support for common RapidIO
subsystem operations.
2. Core Components
-------------------
+==================
A typical RapidIO network is a combination of endpoints and switches.
Each of these components is represented in the subsystem by an associated data
@@ -30,6 +30,7 @@ structure. The core logical components of the RapidIO subsystem are defined
in include/linux/rio.h file.
2.1 Master Port
+---------------
A master port (or mport) is a RapidIO interface controller that is local to the
processor executing the Linux code. A master port generates and receives RapidIO
@@ -46,6 +47,7 @@ includes rio_ops data structure which contains pointers to hardware specific
implementations of RapidIO functions.
2.2 Device
+----------
A RapidIO device is any endpoint (other than mport) or switch in the network.
All devices are presented in the RapidIO subsystem by corresponding rio_dev data
@@ -53,6 +55,7 @@ structure. Devices form one global device list and per-network device lists
(depending on number of available mports and networks).
2.3 Switch
+----------
A RapidIO switch is a special class of device that routes packets between its
ports towards their final destination. The packet destination port within a
@@ -66,6 +69,7 @@ specific switch drivers that are designed to provide hardware-specific
implementation of common switch management routines.
2.4 Network
+-----------
A RapidIO network is a combination of interconnected endpoint and switch devices.
Each RapidIO network known to the system is represented by corresponding rio_net
@@ -74,11 +78,13 @@ ports that form the same network. It also contains a pointer to the default
master port that is used to communicate with devices within the network.
2.5 Device Drivers
+------------------
RapidIO device-specific drivers follow Linux Kernel Driver Model and are
intended to support specific RapidIO devices attached to the RapidIO network.
2.6 Subsystem Interfaces
+------------------------
RapidIO interconnect specification defines features that may be used to provide
one or more common service layers for all participating RapidIO devices. These
@@ -90,7 +96,7 @@ subsystem interfaces. This allows to have multiple common services attached to
the same device without blocking attachment of a device-specific driver.
3. Subsystem Initialization
----------------------------
+===========================
In order to initialize the RapidIO subsystem, a platform must initialize and
register at least one master port within the RapidIO network. To register mport
@@ -105,7 +111,7 @@ RapidIO subsystem can be configured to be built as a statically linked or
modular component of the kernel (see details below).
4. Enumeration and Discovery
-----------------------------
+============================
4.1 Overview
------------
@@ -168,14 +174,16 @@ on RapidIO subsystem build configuration:
(b) If the RapidIO subsystem core is built as a loadable module, in addition
to the method shown above, the host destination ID(s) can be specified using
traditional methods of passing module parameter "hdid=" during its loading:
+
- from command line: "modprobe rapidio hdid=-1,7", or
- from modprobe configuration file using configuration command "options",
like in this example: "options rapidio hdid=-1,7". An example of modprobe
configuration file is provided in the section below.
- NOTES:
+NOTES:
(i) if "hdid=" parameter is omitted all available mport will be assigned
destination ID = -1;
+
(ii) the "hdid=" parameter in systems with multiple mports can have
destination ID assignments omitted from the end of list (default = -1).
@@ -317,8 +325,7 @@ must ensure that they are loaded before the enumeration/discovery starts.
This process can be automated by specifying pre- or post- dependencies in the
RapidIO-specific modprobe configuration file as shown in the example below.
- File /etc/modprobe.d/rapidio.conf:
- ----------------------------------
+File /etc/modprobe.d/rapidio.conf::
# Configure RapidIO subsystem modules
@@ -335,17 +342,21 @@ RapidIO-specific modprobe configuration file as shown in the example below.
--------------------------
-NOTE: In the example above, one of "softdep" commands must be removed or
-commented out to keep required module loading sequence.
+NOTE:
+ In the example above, one of "softdep" commands must be removed or
+ commented out to keep required module loading sequence.
-A. References
--------------
+5. References
+=============
[1] RapidIO Trade Association. RapidIO Interconnect Specifications.
http://www.rapidio.org.
+
[2] Rapidio TA. Technology Comparisons.
http://www.rapidio.org/education/technology_comparisons/
+
[3] RapidIO support for Linux.
http://lwn.net/Articles/139118/
+
[4] Matt Porter. RapidIO for Linux. Ottawa Linux Symposium, 2005
http://www.kernel.org/doc/ols/2005/ols2005v2-pages-43-56.pdf
diff --git a/Documentation/rapidio/rio_cm.txt b/Documentation/rapidio/rio_cm.rst
similarity index 76%
rename from Documentation/rapidio/rio_cm.txt
rename to Documentation/rapidio/rio_cm.rst
index 27aa401f1126..5294430a7a74 100644
--- a/Documentation/rapidio/rio_cm.txt
+++ b/Documentation/rapidio/rio_cm.rst
@@ -1,13 +1,10 @@
+==========================================================================
RapidIO subsystem Channelized Messaging character device driver (rio_cm.c)
==========================================================================
-Version History:
-----------------
- 1.0.0 - Initial driver release.
-==========================================================================
-
-I. Overview
+1. Overview
+===========
This device driver is the result of collaboration within the RapidIO.org
Software Task Group (STG) between Texas Instruments, Prodrive Technologies,
@@ -41,79 +38,98 @@ in /dev directory common for all registered RapidIO mport devices.
Following ioctl commands are available to user-space applications:
-- RIO_CM_MPORT_GET_LIST : Returns to caller list of local mport devices that
+- RIO_CM_MPORT_GET_LIST:
+ Returns to caller list of local mport devices that
support messaging operations (number of entries up to RIO_MAX_MPORTS).
Each list entry is combination of mport's index in the system and RapidIO
destination ID assigned to the port.
-- RIO_CM_EP_GET_LIST_SIZE : Returns number of messaging capable remote endpoints
+- RIO_CM_EP_GET_LIST_SIZE:
+ Returns number of messaging capable remote endpoints
in a RapidIO network associated with the specified mport device.
-- RIO_CM_EP_GET_LIST : Returns list of RapidIO destination IDs for messaging
+- RIO_CM_EP_GET_LIST:
+ Returns list of RapidIO destination IDs for messaging
capable remote endpoints (peers) available in a RapidIO network associated
with the specified mport device.
-- RIO_CM_CHAN_CREATE : Creates RapidIO message exchange channel data structure
+- RIO_CM_CHAN_CREATE:
+ Creates RapidIO message exchange channel data structure
with channel ID assigned automatically or as requested by a caller.
-- RIO_CM_CHAN_BIND : Binds the specified channel data structure to the specified
+- RIO_CM_CHAN_BIND:
+ Binds the specified channel data structure to the specified
mport device.
-- RIO_CM_CHAN_LISTEN : Enables listening for connection requests on the specified
+- RIO_CM_CHAN_LISTEN:
+ Enables listening for connection requests on the specified
channel.
-- RIO_CM_CHAN_ACCEPT : Accepts a connection request from peer on the specified
+- RIO_CM_CHAN_ACCEPT:
+ Accepts a connection request from peer on the specified
channel. If wait timeout for this request is specified by a caller it is
a blocking call. If timeout set to 0 this is non-blocking call - ioctl
handler checks for a pending connection request and if one is not available
exits with -EGAIN error status immediately.
-- RIO_CM_CHAN_CONNECT : Sends a connection request to a remote peer/channel.
-- RIO_CM_CHAN_SEND : Sends a data message through the specified channel.
+- RIO_CM_CHAN_CONNECT:
+ Sends a connection request to a remote peer/channel.
+- RIO_CM_CHAN_SEND:
+ Sends a data message through the specified channel.
The handler for this request assumes that message buffer specified by
a caller includes the reserved space for a packet header required by
this driver.
-- RIO_CM_CHAN_RECEIVE : Receives a data message through a connected channel.
+- RIO_CM_CHAN_RECEIVE:
+ Receives a data message through a connected channel.
If the channel does not have an incoming message ready to return this ioctl
handler will wait for new message until timeout specified by a caller
expires. If timeout value is set to 0, ioctl handler uses a default value
defined by MAX_SCHEDULE_TIMEOUT.
-- RIO_CM_CHAN_CLOSE : Closes a specified channel and frees associated buffers.
+- RIO_CM_CHAN_CLOSE:
+ Closes a specified channel and frees associated buffers.
If the specified channel is in the CONNECTED state, sends close notification
to the remote peer.
The ioctl command codes and corresponding data structures intended for use by
user-space applications are defined in 'include/uapi/linux/rio_cm_cdev.h'.
-II. Hardware Compatibility
+2. Hardware Compatibility
+=========================
This device driver uses standard interfaces defined by kernel RapidIO subsystem
and therefore it can be used with any mport device driver registered by RapidIO
subsystem with limitations set by available mport HW implementation of messaging
mailboxes.
-III. Module parameters
+3. Module parameters
+====================
-- 'dbg_level' - This parameter allows to control amount of debug information
+- 'dbg_level'
+ - This parameter allows to control amount of debug information
generated by this device driver. This parameter is formed by set of
bit masks that correspond to the specific functional block.
For mask definitions see 'drivers/rapidio/devices/rio_cm.c'
This parameter can be changed dynamically.
Use CONFIG_RAPIDIO_DEBUG=y to enable debug output at the top level.
-- 'cmbox' - Number of RapidIO mailbox to use (default value is 1).
+- 'cmbox'
+ - Number of RapidIO mailbox to use (default value is 1).
This parameter allows to set messaging mailbox number that will be used
within entire RapidIO network. It can be used when default mailbox is
used by other device drivers or is not supported by some nodes in the
RapidIO network.
-- 'chstart' - Start channel number for dynamic assignment. Default value - 256.
+- 'chstart'
+ - Start channel number for dynamic assignment. Default value - 256.
Allows to exclude channel numbers below this parameter from dynamic
allocation to avoid conflicts with software components that use
reserved predefined channel numbers.
-IV. Known problems
+4. Known problems
+=================
None.
-V. User-space Applications and API Library
+5. User-space Applications and API Library
+==========================================
Messaging API library and applications that use this device driver are available
from RapidIO.org.
-VI. TODO List
+6. TODO List
+============
- Add support for system notification messages (reserved channel 0).
diff --git a/Documentation/rapidio/sysfs.txt b/Documentation/rapidio/sysfs.rst
similarity index 75%
rename from Documentation/rapidio/sysfs.txt
rename to Documentation/rapidio/sysfs.rst
index a1adac888e6e..540f72683496 100644
--- a/Documentation/rapidio/sysfs.txt
+++ b/Documentation/rapidio/sysfs.rst
@@ -1,3 +1,7 @@
+=============
+Sysfs entries
+=============
+
The RapidIO sysfs files have moved to:
Documentation/ABI/testing/sysfs-bus-rapidio and
Documentation/ABI/testing/sysfs-class-rapidio
diff --git a/Documentation/rapidio/tsi721.txt b/Documentation/rapidio/tsi721.rst
similarity index 79%
rename from Documentation/rapidio/tsi721.txt
rename to Documentation/rapidio/tsi721.rst
index cd2a2935d51d..42aea438cd20 100644
--- a/Documentation/rapidio/tsi721.txt
+++ b/Documentation/rapidio/tsi721.rst
@@ -1,7 +1,9 @@
+=========================================================================
RapidIO subsystem mport driver for IDT Tsi721 PCI Express-to-SRIO bridge.
=========================================================================
-I. Overview
+1. Overview
+===========
This driver implements all currently defined RapidIO mport callback functions.
It supports maintenance read and write operations, inbound and outbound RapidIO
@@ -17,7 +19,9 @@ into the corresponding message queue. Messaging callbacks are implemented to be
fully compatible with RIONET driver (Ethernet over RapidIO messaging services).
1. Module parameters:
-- 'dbg_level' - This parameter allows to control amount of debug information
+
+- 'dbg_level'
+ - This parameter allows to control amount of debug information
generated by this device driver. This parameter is formed by set of
This parameter can be changed bit masks that correspond to the specific
functional block.
@@ -25,37 +29,44 @@ fully compatible with RIONET driver (Ethernet over RapidIO messaging services).
This parameter can be changed dynamically.
Use CONFIG_RAPIDIO_DEBUG=y to enable debug output at the top level.
-- 'dma_desc_per_channel' - This parameter defines number of hardware buffer
+- 'dma_desc_per_channel'
+ - This parameter defines number of hardware buffer
descriptors allocated for each registered Tsi721 DMA channel.
Its default value is 128.
-- 'dma_txqueue_sz' - DMA transactions queue size. Defines number of pending
+- 'dma_txqueue_sz'
+ - DMA transactions queue size. Defines number of pending
transaction requests that can be accepted by each DMA channel.
Default value is 16.
-- 'dma_sel' - DMA channel selection mask. Bitmask that defines which hardware
+- 'dma_sel'
+ - DMA channel selection mask. Bitmask that defines which hardware
DMA channels (0 ... 6) will be registered with DmaEngine core.
If bit is set to 1, the corresponding DMA channel will be registered.
DMA channels not selected by this mask will not be used by this device
driver. Default value is 0x7f (use all channels).
-- 'pcie_mrrs' - override value for PCIe Maximum Read Request Size (MRRS).
+- 'pcie_mrrs'
+ - override value for PCIe Maximum Read Request Size (MRRS).
This parameter gives an ability to override MRRS value set during PCIe
configuration process. Tsi721 supports read request sizes up to 4096B.
Value for this parameter must be set as defined by PCIe specification:
0 = 128B, 1 = 256B, 2 = 512B, 3 = 1024B, 4 = 2048B and 5 = 4096B.
Default value is '-1' (= keep platform setting).
-- 'mbox_sel' - RIO messaging MBOX selection mask. This is a bitmask that defines
+- 'mbox_sel'
+ - RIO messaging MBOX selection mask. This is a bitmask that defines
messaging MBOXes are managed by this device driver. Mask bits 0 - 3
correspond to MBOX0 - MBOX3. MBOX is under driver's control if the
corresponding bit is set to '1'. Default value is 0x0f (= all).
-II. Known problems
+2. Known problems
+=================
None.
-III. DMA Engine Support
+3. DMA Engine Support
+=====================
Tsi721 mport driver supports DMA data transfers between local system memory and
remote RapidIO devices. This functionality is implemented according to SLAVE
@@ -68,17 +79,21 @@ One BDMA channel is reserved for generation of maintenance read/write requests.
If Tsi721 mport driver have been built with RAPIDIO_DMA_ENGINE support included,
this driver will accept DMA-specific module parameter:
- "dma_desc_per_channel" - defines number of hardware buffer descriptors used by
+
+ "dma_desc_per_channel"
+ - defines number of hardware buffer descriptors used by
each BDMA channel of Tsi721 (by default - 128).
-IV. Version History
+4. Version History
- 1.1.0 - DMA operations re-worked to support data scatter/gather lists larger
+ ===== ====================================================================
+ 1.1.0 DMA operations re-worked to support data scatter/gather lists larger
than hardware buffer descriptors ring.
- 1.0.0 - Initial driver release.
+ 1.0.0 Initial driver release.
+ ===== ====================================================================
-V. License
------------------------------------------------
+5. License
+===========
Copyright(c) 2011 Integrated Device Technology, Inc. All rights reserved.
diff --git a/drivers/rapidio/Kconfig b/drivers/rapidio/Kconfig
index fadafc64705f..467e8fa06904 100644
--- a/drivers/rapidio/Kconfig
+++ b/drivers/rapidio/Kconfig
@@ -86,7 +86,7 @@ config RAPIDIO_CHMAN
This option includes RapidIO channelized messaging driver which
provides socket-like interface to allow sharing of single RapidIO
messaging mailbox between multiple user-space applications.
- See "Documentation/rapidio/rio_cm.txt" for driver description.
+ See "Documentation/rapidio/rio_cm.rst" for driver description.
config RAPIDIO_MPORT_CDEV
tristate "RapidIO /dev mport device driver"
--
2.21.0
^ permalink raw reply related
* [PATCH v1 20/22] docs: extcon: move it to acpi dir and convert it to ReST
From: Mauro Carvalho Chehab @ 2019-06-18 21:05 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, MyungJoo Ham, Chanwoo Choi, Rafael J. Wysocki,
Len Brown, linux-acpi
In-Reply-To: <cover.1560891322.git.mchehab+samsung@kernel.org>
The intel-int3496.txt file is a documentation for an ACPI driver.
There's no reason to keep it on a separate directory.
So, instead of keeping it on some random location, move it
to a sub-directory inside the ACPI documentation dir.
For now, keep it with .txt extension, in order to avoid
Sphinx build noise. A later patch should change it to .rst
and movin it to be together with other acpi docs.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../acpi/extcon-intel-int3496.rst} | 14 ++++++++++----
Documentation/firmware-guide/acpi/index.rst | 1 +
MAINTAINERS | 6 +++---
3 files changed, 14 insertions(+), 7 deletions(-)
rename Documentation/{extcon/intel-int3496.txt => firmware-guide/acpi/extcon-intel-int3496.rst} (66%)
diff --git a/Documentation/extcon/intel-int3496.txt b/Documentation/firmware-guide/acpi/extcon-intel-int3496.rst
similarity index 66%
rename from Documentation/extcon/intel-int3496.txt
rename to Documentation/firmware-guide/acpi/extcon-intel-int3496.rst
index 8155dbc7fad3..5137ca834b54 100644
--- a/Documentation/extcon/intel-int3496.txt
+++ b/Documentation/firmware-guide/acpi/extcon-intel-int3496.rst
@@ -1,5 +1,6 @@
+=====================================================
Intel INT3496 ACPI device extcon driver documentation
------------------------------------------------------
+=====================================================
The Intel INT3496 ACPI device extcon driver is a driver for ACPI
devices with an acpi-id of INT3496, such as found for example on
@@ -13,15 +14,20 @@ between an USB host and an USB peripheral controller.
The ACPI devices exposes this functionality by returning an array with up
to 3 gpio descriptors from its ACPI _CRS (Current Resource Settings) call:
-Index 0: The input gpio for the id-pin, this is always present and valid
-Index 1: The output gpio for enabling Vbus output from the device to the otg
+======= =====================================================================
+Index 0 The input gpio for the id-pin, this is always present and valid
+Index 1 The output gpio for enabling Vbus output from the device to the otg
port, write 1 to enable the Vbus output (this gpio descriptor may
be absent or invalid)
-Index 2: The output gpio for muxing of the data pins between the USB host and
+Index 2 The output gpio for muxing of the data pins between the USB host and
the USB peripheral controller, write 1 to mux to the peripheral
controller
+======= =====================================================================
There is a mapping between indices and GPIO connection IDs as follows
+
+ ======= =======
id index 0
vbus index 1
mux index 2
+ ======= =======
diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
index ae609eec4679..90c90d42d9ad 100644
--- a/Documentation/firmware-guide/acpi/index.rst
+++ b/Documentation/firmware-guide/acpi/index.rst
@@ -24,3 +24,4 @@ ACPI Support
acpi-lid
lpit
video_extension
+ extcon-intel-int3496
diff --git a/MAINTAINERS b/MAINTAINERS
index e07cbd44d48a..b7c81bd0f8e8 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -321,7 +321,7 @@ F: drivers/pnp/pnpacpi/
F: include/linux/acpi.h
F: include/linux/fwnode.h
F: include/acpi/
-F: Documentation/acpi/
+F: Documentation/firmware-guide/acpi/
F: Documentation/ABI/testing/sysfs-bus-acpi
F: Documentation/ABI/testing/configfs-acpi
F: drivers/pci/*acpi*
@@ -4881,7 +4881,7 @@ S: Maintained
F: Documentation/
F: scripts/kernel-doc
X: Documentation/ABI/
-X: Documentation/acpi/
+X: Documentation/firmware-guide/acpi/
X: Documentation/devicetree/
X: Documentation/i2c/
X: Documentation/media/
@@ -6057,7 +6057,7 @@ S: Maintained
F: drivers/extcon/
F: include/linux/extcon/
F: include/linux/extcon.h
-F: Documentation/extcon/
+F: Documentation/firmware-guide/acpi/extcon-intel-int3496.rst
F: Documentation/devicetree/bindings/extcon/
EXYNOS DP DRIVER
--
2.21.0
^ permalink raw reply related
* [PATCH v1 19/22] docs: driver-api: add remaining converted dirs to it
From: Mauro Carvalho Chehab @ 2019-06-18 21:05 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Sudeep Dutt, Ashutosh Dixit, Kamil Debski,
Sylwester Nawrocki
In-Reply-To: <cover.1560891322.git.mchehab+samsung@kernel.org>
There are a number of driver-specific descriptions that contain a
mix of userspace and kernelspace documentation. Just like we did
with other similar subsystems, add them at the driver-api
groupset, but don't move the directories.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/index.rst | 3 +++
Documentation/mic/index.rst | 2 --
Documentation/phy/samsung-usb2.rst | 2 --
Documentation/scheduler/index.rst | 2 --
4 files changed, 3 insertions(+), 6 deletions(-)
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 82cd9528dff0..b4a48979e15a 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -105,6 +105,9 @@ needed).
PCI/index
usb/index
misc-devices/index
+ mic/index
+ phy/samsung-usb2
+ scheduler/index
Architecture-specific documentation
-----------------------------------
diff --git a/Documentation/mic/index.rst b/Documentation/mic/index.rst
index 082fa8f6a260..3a8d06367ef1 100644
--- a/Documentation/mic/index.rst
+++ b/Documentation/mic/index.rst
@@ -1,5 +1,3 @@
-:orphan:
-
=============================================
Intel Many Integrated Core (MIC) architecture
=============================================
diff --git a/Documentation/phy/samsung-usb2.rst b/Documentation/phy/samsung-usb2.rst
index 98b5952fcb97..c48c8b9797b9 100644
--- a/Documentation/phy/samsung-usb2.rst
+++ b/Documentation/phy/samsung-usb2.rst
@@ -1,5 +1,3 @@
-:orphan:
-
====================================
Samsung USB 2.0 PHY adaptation layer
====================================
diff --git a/Documentation/scheduler/index.rst b/Documentation/scheduler/index.rst
index 058be77a4c34..69074e5de9c4 100644
--- a/Documentation/scheduler/index.rst
+++ b/Documentation/scheduler/index.rst
@@ -1,5 +1,3 @@
-:orphan:
-
===============
Linux Scheduler
===============
--
2.21.0
^ permalink raw reply related
page: next (older) | prev (newer) | latest
- recent:[subjects (threaded)|topics (new)|topics (active)]
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox